Add WithBuildStage method to allow changing Docker build stage after resource creation

[Copilot]

This PR adds a new WithBuildStage(string stage) extension method to ContainerResourceBuilderExtensions that allows users to change the Docker build stage for a container resource after it has been created with AddDockerfile or WithDockerfile.

Problem

Previously, users had to determine the Docker build stage upfront when calling AddDockerfile, leading to verbose conditional code patterns:

// Old approach - conditional overloads
var pythonInference =
    (builder.ExecutionContext.IsRunMode
        ? builder.AddDockerfile("python-inference", "../PythonInference", null, "base")
        : builder.AddDockerfile("python-inference", "../PythonInference"))
    .WithHttpEndpoint(targetPort: 62394, env: "UVICORN_PORT")
    .WithContainerRuntimeArgs("--gpus=all")
    .WithLifetime(ContainerLifetime.Persistent);

if (builder.ExecutionContext.IsRunMode)
{
    pythonInference
        .WithBindMount("../PythonInference", "/app")
        .WithArgs("--reload");
}

Solution

The new WithBuildStage method enables cleaner, more maintainable code:

// New approach - clean conditional pattern
var pythonInference = builder.AddDockerfile("python-inference", "../PythonInference")
    .WithHttpEndpoint(targetPort: 62394, env: "UVICORN_PORT")
    .WithContainerRuntimeArgs("--gpus=all")
    .WithLifetime(ContainerLifetime.Persistent);

if (builder.ExecutionContext.IsRunMode)
{
    // Configure the python inference app for development
    pythonInference
        .WithBuildStage("base")
        .WithBindMount("../PythonInference", "/app")
        .WithArgs("--reload");
}

Implementation Details

• The method validates that a DockerfileBuildAnnotation exists before allowing stage changes
• Preserves existing build arguments and secrets when updating the annotation
• Uses ResourceAnnotationMutationBehavior.Replace to properly update the annotation
• Includes comprehensive error handling with appropriate exception types
• Follows existing codebase patterns and conventions

Testing

Added comprehensive unit tests covering:

• Basic stage changing functionality
• Preserving build arguments and secrets during stage changes
• Error handling for null/empty parameters and missing dockerfile annotations
• Manifest generation verification
• Integration with existing Docker functionality

Fixes #6256.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.