# ContainerResourceBuilderExtensions Methods

- Package: [Aspire.Hosting](/reference/api/csharp/aspire.hosting.md)
- Type: [ContainerResourceBuilderExtensions](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions.md)
- Kind: `Methods`
- Members: `37`

Provides extension methods for [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) to add container resources to the application.

## AddContainer(IDistributedApplicationBuilder, string, string)

- Name: `AddContainer(IDistributedApplicationBuilder, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<ContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L97-L103)

Adds a container resource to the application. Uses the "latest" tag.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<ContainerResource> AddContainer(
        this IDistributedApplicationBuilder builder,
        string name,
        string image)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md))
  The [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md).
- `name` (`string`)
  The name of the resource.
- `image` (`string`)
  The container image name. The tag is assumed to be "latest".

## Returns

`IResourceBuilder<ContainerResource>` -- The `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### Ignored by ATS

- Reason: Use the polyglot addContainer overload that accepts a string or AddContainerOptions value.

## AddContainer(IDistributedApplicationBuilder, string, string, string)

- Name: `AddContainer(IDistributedApplicationBuilder, string, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<ContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L117-L118)

Adds a container resource to the application.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<ContainerResource> AddContainer(
        this IDistributedApplicationBuilder builder,
        string name,
        string image,
        string tag)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md))
  The [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md).
- `name` (`string`)
  The name of the resource.
- `image` (`string`)
  The container image name.
- `tag` (`string`)
  The container image tag.

## Returns

`IResourceBuilder<ContainerResource>` -- The `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### Ignored by ATS

- Reason: Use the polyglot addContainer overload that accepts a string or AddContainerOptions value.

## AddDockerfile(IDistributedApplicationBuilder, string, string, string?, string?)

- Name: `AddDockerfile(IDistributedApplicationBuilder, string, string, string?, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<ContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L864-L869)

Adds a Dockerfile to the application model that can be treated like a container resource.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<ContainerResource> AddDockerfile(
        this IDistributedApplicationBuilder builder,
        string name,
        string contextPath,
        string? dockerfilePath = null,
        string? stage = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md))
  The [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md).
- `name` (`string`)
  The name of the resource.
- `contextPath` (`string`)
  Path to be used as the context for the container image build.
- `dockerfilePath` (`string?`) `optional`
  Path to the Dockerfile relative to the `contextPath`. Defaults to "Dockerfile" if not specified.
- `stage` (`string?`) `optional`
  The stage representing the image to be published in a multi-stage Dockerfile.

## Returns

`IResourceBuilder<ContainerResource>` -- A `ApplicationModel.IResourceBuilder`1`.

## Remarks

The `contextPath` is relative to the AppHost directory unless it is a fully qualified path. The `dockerfilePath` is relative to the `contextPath` unless it is a fully qualified path. If the `dockerfilePath` is not provided, it defaults to "Dockerfile" in the `contextPath`.

When generating the manifest for deployment tools, the [ContainerResourceBuilderExtensions.AddDockerfile(IDistributedApplicationBuilder, string, string, string?, string?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#adddockerfile-idistributedapplicationbuilder-string-string-string-string) method results in an additional attribute being added to the `container.v1` resource type which contains the configuration necessary to allow the deployment tool to build the container image prior to deployment.

Creates a container called `mycontainer` based on a Dockerfile in the context path `path/to/context`.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddDockerfile("mycontainer", "path/to/context");

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## AddDockerfileBuilder(IDistributedApplicationBuilder, string, string, Func<DockerfileBuilderCallbackContext, Task>, string?)

> **Experimental:** ASPIREDOCKERFILEBUILDER001 - [Learn more](/diagnostics/aspiredockerfilebuilder001/)

- Name: `AddDockerfileBuilder(IDistributedApplicationBuilder, string, string, Func<DockerfileBuilderCallbackContext, Task>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<ContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Adds a Dockerfile to the application model that can be treated like a container resource, with the Dockerfile generated programmatically using the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<ContainerResource> AddDockerfileBuilder(
        this IDistributedApplicationBuilder builder,
        string name,
        string contextPath,
        Func<DockerfileBuilderCallbackContext, Task> callback,
        string? stage = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md))
  The [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md).
- `name` (`string`)
  The name of the resource.
- `contextPath` (`string`)
  Path to be used as the context for the container image build.
- `callback` (`Func<DockerfileBuilderCallbackContext, Task>`)
  A callback that uses the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API to construct the Dockerfile.
- `stage` (`string?`) `optional`
  The stage representing the image to be published in a multi-stage Dockerfile.

## Returns

`IResourceBuilder<ContainerResource>` -- A `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method provides a programmatic way to build Dockerfiles using the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API instead of string manipulation.

The `contextPath` is relative to the AppHost directory unless it is fully qualified.

Creates a container with a programmatically built Dockerfile:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddDockerfileBuilder("mycontainer", "path/to/context", context =>
{
    context.Builder.From("alpine:latest")
        .WorkDir("/app")
        .Copy(".", ".")
        .Cmd(["./myapp"]);
    return Task.CompletedTask;
});

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## AddDockerfileBuilder(IDistributedApplicationBuilder, string, string, Action<DockerfileBuilderCallbackContext>, string?)

> **Experimental:** ASPIREDOCKERFILEBUILDER001 - [Learn more](/diagnostics/aspiredockerfilebuilder001/)

- Name: `AddDockerfileBuilder(IDistributedApplicationBuilder, string, string, Action<DockerfileBuilderCallbackContext>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<ContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Adds a Dockerfile to the application model that can be treated like a container resource, with the Dockerfile generated programmatically using the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<ContainerResource> AddDockerfileBuilder(
        this IDistributedApplicationBuilder builder,
        string name,
        string contextPath,
        Action<DockerfileBuilderCallbackContext> callback,
        string? stage = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md))
  The [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md).
- `name` (`string`)
  The name of the resource.
- `contextPath` (`string`)
  Path to be used as the context for the container image build.
- `callback` (`Action<DockerfileBuilderCallbackContext>`)
  A synchronous callback that uses the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API to construct the Dockerfile.
- `stage` (`string?`) `optional`
  The stage representing the image to be published in a multi-stage Dockerfile.

## Returns

`IResourceBuilder<ContainerResource>` -- A `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method provides a programmatic way to build Dockerfiles using the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API instead of string manipulation.

The `contextPath` is relative to the AppHost directory unless it is fully qualified.

Creates a container with a programmatically built Dockerfile:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddDockerfileBuilder("mycontainer", "path/to/context", context =>
{
    context.Builder.From("node:18")
        .WorkDir("/app")
        .Copy("package*.json", "./")
        .Run("npm ci");
});

builder.Build().Run();
```

## ATS metadata

### Ignored by ATS

- Reason: This synchronous overload is excluded from the polyglot surface; only the async callback overload is exported.

## AddDockerfileFactory(IDistributedApplicationBuilder, string, string, Func<DockerfileFactoryContext, string>, string?)

- Name: `AddDockerfileFactory(IDistributedApplicationBuilder, string, string, Func<DockerfileFactoryContext, string>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<ContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Adds a Dockerfile to the application model that can be treated like a container resource, with the Dockerfile content generated by a synchronous factory function.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<ContainerResource> AddDockerfileFactory(
        this IDistributedApplicationBuilder builder,
        string name,
        string contextPath,
        Func<DockerfileFactoryContext, string> dockerfileFactory,
        string? stage = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md))
  The [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md).
- `name` (`string`)
  The name of the resource.
- `contextPath` (`string`)
  Path to be used as the context for the container image build.
- `dockerfileFactory` (`Func<DockerfileFactoryContext, string>`)
  A synchronous function that returns the Dockerfile content as a string.
- `stage` (`string?`) `optional`
  The stage representing the image to be published in a multi-stage Dockerfile.

## Returns

`IResourceBuilder<ContainerResource>` -- A `ApplicationModel.IResourceBuilder`1`.

## Remarks

The `contextPath` is relative to the AppHost directory unless it is fully qualified.

The factory function is invoked once during the build process to generate the Dockerfile content. The output is trusted and not validated.

## ATS metadata

### Ignored by ATS

- Reason: DockerfileFactoryContext exposes IServiceProvider and IResource -- .NET runtime types not usable from polyglot hosts.

## AddDockerfileFactory(IDistributedApplicationBuilder, string, string, Func<DockerfileFactoryContext, Task<string>>, string?)

- Name: `AddDockerfileFactory(IDistributedApplicationBuilder, string, string, Func<DockerfileFactoryContext, Task<string>>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<ContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Adds a Dockerfile to the application model that can be treated like a container resource, with the Dockerfile content generated by an asynchronous factory function.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<ContainerResource> AddDockerfileFactory(
        this IDistributedApplicationBuilder builder,
        string name,
        string contextPath,
        Func<DockerfileFactoryContext, Task<string>> dockerfileFactory,
        string? stage = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md))
  The [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md).
- `name` (`string`)
  The name of the resource.
- `contextPath` (`string`)
  Path to be used as the context for the container image build.
- `dockerfileFactory` (`Func<DockerfileFactoryContext, Task<string>>`)
  An asynchronous function that returns the Dockerfile content as a string.
- `stage` (`string?`) `optional`
  The stage representing the image to be published in a multi-stage Dockerfile.

## Returns

`IResourceBuilder<ContainerResource>` -- A `ApplicationModel.IResourceBuilder`1`.

## Remarks

The `contextPath` is relative to the AppHost directory unless it is fully qualified.

The factory function is invoked once during the build process to generate the Dockerfile content. The output is trusted and not validated.

## ATS metadata

### Ignored by ATS

- Reason: DockerfileFactoryContext exposes IServiceProvider and IResource -- .NET runtime types not usable from polyglot hosts.

## PublishAsContainer(IResourceBuilder<T>)

- Name: `PublishAsContainer(IResourceBuilder<T>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L585-L587)

Changes the resource to be published as a container in the manifest.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> PublishAsContainer<T>(
        this IResourceBuilder<T> builder)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Resource builder.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithBindMount(IResourceBuilder<T>, string, string, bool)

- Name: `WithBindMount(IResourceBuilder<T>, string, string, bool)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L298-L305)

Adds a bind mount to a container resource.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithBindMount<T>(
        this IResourceBuilder<T> builder,
        string source,
        string target,
        bool isReadOnly = false)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `source` (`string`)
  The source path of the mount. This is the path to the file or directory on the host, relative to the app host project directory.
- `target` (`string`)
  The target path where the file or directory is mounted in the container.
- `isReadOnly` (`bool`) `optional`
  A flag that indicates if this is a read-only mount.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

Bind mounts are used to mount files or directories from the host file-system into the container. If the host doesn't require access to the files, consider using volumes instead via [ContainerResourceBuilderExtensions.WithVolume(IResourceBuilder<T>, string?, string, bool)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withvolume-iresourcebuilder-t-string-string-bool).

The `source` path specifies the path of the file or directory on the host that will be mounted in the container. If the path is not absolute, it will be evaluated relative to the app host project directory path.

The `target` path specifies the path the file or directory will be mounted inside the container's file system.

Adds a bind mount that will mount the `config` directory in the app host project directory, to the container's file system at the path `/database/config`, and mark it read-only so that the container cannot modify it:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithBindMount("./config", "/database/config", isReadOnly: true);

builder.Build().Run();
```

Adds a bind mount that will mount the `init.sh` file from a directory outside the app host project directory, to the container's file system at the path `/usr/config/initialize.sh`, and mark it read-only so that the container cannot modify it:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithBindMount("../containerconfig/scripts/init.sh", "/usr/config/initialize.sh", isReadOnly: true);

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithBuildArg(IResourceBuilder<T>, string, object?)

- Name: `WithBuildArg(IResourceBuilder<T>, string, object?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Adds a build argument when the container is build from a Dockerfile.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithBuildArg<T>(
        this IResourceBuilder<T> builder,
        string name,
        object? value)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the container resource.
- `name` (`string`)
  The name of the build argument.
- `value` (`object?`)
  The value of the build argument.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `InvalidOperationException` -- Thrown when [ContainerResourceBuilderExtensions.WithBuildArg(IResourceBuilder<T>, string, object?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withbuildarg-iresourcebuilder-t-string-object) is called before [ContainerResourceBuilderExtensions.WithDockerfile(IResourceBuilder<T>, string, string?, string?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withdockerfile-iresourcebuilder-t-string-string-string).

## Remarks

The [ContainerResourceBuilderExtensions.WithBuildArg(IResourceBuilder<T>, string, object?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withbuildarg-iresourcebuilder-t-string-object) extension method adds an additional build argument the container resource to be used when the image is built. This method must be called after [ContainerResourceBuilderExtensions.WithDockerfile(IResourceBuilder<T>, string, string?, string?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withdockerfile-iresourcebuilder-t-string-string-string).

Adding a static build argument.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithDockerfile("../mycontainer")
       .WithBuildArg("CUSTOM_BRANDING", "/app/static/branding/custom");

builder.Build().Run();
```

## ATS metadata

### Ignored by ATS

- Reason: Uses object parameter which is not ATS-compatible.

## WithBuildArg(IResourceBuilder<T>, string, IResourceBuilder<ParameterResource>)

- Name: `WithBuildArg(IResourceBuilder<T>, string, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Adds a build argument when the container is built from a Dockerfile.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithBuildArg<T>(
        this IResourceBuilder<T> builder,
        string name,
        IResourceBuilder<ParameterResource> value)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the container resource.
- `name` (`string`)
  The name of the build argument.
- `value` (`IResourceBuilder<ParameterResource>`)
  The resource builder for a parameter resource.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `InvalidOperationException` -- Thrown when [ContainerResourceBuilderExtensions.WithBuildArg(IResourceBuilder<T>, string, object?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withbuildarg-iresourcebuilder-t-string-object) is called before [ContainerResourceBuilderExtensions.WithDockerfile(IResourceBuilder<T>, string, string?, string?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withdockerfile-iresourcebuilder-t-string-string-string).

## Remarks

The [ContainerResourceBuilderExtensions.WithBuildArg(IResourceBuilder<T>, string, object?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withbuildarg-iresourcebuilder-t-string-object) extension method adds an additional build argument the container resource to be used when the image is built. This method must be called after [ContainerResourceBuilderExtensions.WithDockerfile(IResourceBuilder<T>, string, string?, string?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withdockerfile-iresourcebuilder-t-string-string-string).

Adding a build argument based on a parameter..

```csharp
var builder = DistributedApplication.CreateBuilder(args);

var branding = builder.AddParameter("branding");

builder.AddContainer("mycontainer", "myimage")
       .WithDockerfile("../mycontainer")
       .WithBuildArg("CUSTOM_BRANDING", branding);

builder.Build().Run();
```

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the union-based withBuildArg dispatcher export.

## WithBuildSecret(IResourceBuilder<T>, string, IResourceBuilder<ParameterResource>)

- Name: `WithBuildSecret(IResourceBuilder<T>, string, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L1214-L1227)

Adds a secret build argument when the container is built from a Dockerfile.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithBuildSecret<T>(
        this IResourceBuilder<T> builder,
        string name,
        IResourceBuilder<ParameterResource> value)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the container resource.
- `name` (`string`)
  The name of the secret build argument.
- `value` (`IResourceBuilder<ParameterResource>`)
  The resource builder for a parameter resource.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `InvalidOperationException` -- Thrown when [ContainerResourceBuilderExtensions.WithBuildSecret(IResourceBuilder<T>, string, IResourceBuilder<ParameterResource>)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withbuildsecret-iresourcebuilder-t-string-iresourcebuilder-parameterresource) is called before [ContainerResourceBuilderExtensions.WithDockerfile(IResourceBuilder<T>, string, string?, string?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withdockerfile-iresourcebuilder-t-string-string-string).

## Remarks

The [ContainerResourceBuilderExtensions.WithBuildSecret(IResourceBuilder<T>, string, IResourceBuilder<ParameterResource>)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withbuildsecret-iresourcebuilder-t-string-iresourcebuilder-parameterresource) extension method results in a `--secret` argument being appended to the `docker build` or `podman build` command. This overload results in an environment variable-based secret being passed to the build process. The value of the environment variable is the value of the secret referenced by the [ParameterResource](/reference/api/csharp/aspire.hosting/parameterresource.md).

Adding a build secret based on a parameter.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

var accessToken = builder.AddParameter("accessToken", secret: true);

builder.AddContainer("mycontainer", "myimage")
       .WithDockerfile("../mycontainer")
       .WithBuildSecret("ACCESS_TOKEN", accessToken);

builder.Build().Run();
```

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting/withParameterBuildSecret`
- Generated method name override: `withBuildSecret`

## WithContainerCertificatePaths(IResourceBuilder<TResource>, string?, List<string>, List<string>)

- Name: `WithContainerCertificatePaths(IResourceBuilder<TResource>, string?, List<string>, List<string>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L1245-L1252)

Adds a [ContainerCertificatePathsAnnotation](/reference/api/csharp/aspire.hosting/containercertificatepathsannotation.md) to the resource that allows overriding the default paths in the container used for certificate trust. Custom certificate trust is only supported at run time.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> WithContainerCertificatePaths<TResource>(
        this IResourceBuilder<TResource> builder,
        string? customCertificatesDestination = null,
        List<string>? defaultCertificateBundlePaths = null,
        List<string>? defaultCertificateDirectoryPaths = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<TResource>`)
  The resource builder.
- `customCertificatesDestination` (`string?`) `optional`
  The destination path in the container where custom certificates will be copied to. If not specified, defaults to `/usr/local/share/ca-certificates/aspire-custom-certs/`.
- `defaultCertificateBundlePaths` (`List<string>`) `optional`
  List of default certificate bundle paths in the container that will be replaced in [CertificateTrustScope.Override](/reference/api/csharp/aspire.hosting/certificatetrustscope/fields.md) or [CertificateTrustScope.System](/reference/api/csharp/aspire.hosting/certificatetrustscope/fields.md) modes. If not specified, defaults to `/etc/ssl/certs/ca-certificates.crt` for Linux containers.
- `defaultCertificateDirectoryPaths` (`List<string>`) `optional`
  List of default certificate directory paths in the container that may be appended to the custom certificates directory in [CertificateTrustScope.Append](/reference/api/csharp/aspire.hosting/certificatetrustscope/fields.md) mode. If not specified, defaults to `/usr/local/share/ca-certificates/` for Linux containers.

## Returns

`IResourceBuilder<TResource>` -- The updated resource builder.

## Remarks

This method is not available in polyglot app hosts. Use the ATS wrapper overload instead.

## ATS metadata

### Ignored by ATS

- Reason: Uses List<string> which is not ATS-compatible (only T[] is supported, not List<T>).

## WithContainerFiles(IResourceBuilder<T>, string, IEnumerable<ContainerFileSystemItem>, int?, int?, UnixFileMode?)

- Name: `WithContainerFiles(IResourceBuilder<T>, string, IEnumerable<ContainerFileSystemItem>, int?, int?, UnixFileMode?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L1326-L1339)

Creates or updates files and/or folders at the destination path in the container.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithContainerFiles<T>(
        this IResourceBuilder<T> builder,
        string destinationPath,
        IEnumerable<ContainerFileSystemItem> entries,
        int? defaultOwner = null,
        int? defaultGroup = null,
        UnixFileMode? umask = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the container resource.
- `destinationPath` (`string`)
  The destination (absolute) path in the container.
- `entries` ([IEnumerable<ContainerFileSystemItem>](/reference/api/csharp/aspire.hosting/containerfilesystemitem.md))
  The file system entries to create.
- `defaultOwner` (`int?`) `optional`
  The default owner UID for the created or updated file system. Defaults to 0 for root if not set.
- `defaultGroup` (`int?`) `optional`
  The default group ID for the created or updated file system. Defaults to 0 for root if not set.
- `umask` (`UnixFileMode?`) `optional`
  The umask `IO.UnixFileMode` permissions to exclude from the default file and folder permissions. This takes away (rather than granting) default permissions to files and folders without an explicit mode permission set.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

For containers with a [ContainerLifetime.Persistent](/reference/api/csharp/aspire.hosting/containerlifetime/fields.md) lifetime, changing the contents of create file entries will result in the container being recreated. Make sure any data being written to containers is idempotent for a given app model configuration. Specifically, be careful not to include any data that will be unique on a per-run basis.

Create a directory called `custom-entry` in the container's file system at the path `/usr/data` and create a file called `entrypoint.sh` inside it with the content `echo hello world`. The default permissions for these files will be for the user or group to be able to read and write to the files, but not execute them. entrypoint.sh will be created with execution permissions for the owner.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
    .WithContainerFiles("/usr/data", [
        new ContainerDirectory
        {
            Name = "custom-entry",
            Entries = [
                new ContainerFile
                {
                    Name = "entrypoint.sh",
                    Contents = "echo hello world",
                    Mode = UnixFileMode.UserExecute | UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.GroupRead | UnixFileMode.GroupWrite,
                },
            ],
        },
    ],
    defaultOwner: 1000);
```

## ATS metadata

### Ignored by ATS

- Reason: ContainerFileSystemItem is an abstract class hierarchy (ContainerFile, ContainerDirectory, ContainerOpenSSLCertificateFile) with recursive Entries -- polymorphic types not supported by ATS.

## WithContainerFiles(IResourceBuilder<T>, string, Func<ContainerFileSystemCallbackContext, CancellationToken, Task<IEnumerable<ContainerFileSystemItem>>>, int?, int?, UnixFileMode?)

- Name: `WithContainerFiles(IResourceBuilder<T>, string, Func<ContainerFileSystemCallbackContext, CancellationToken, Task<IEnumerable<ContainerFileSystemItem>>>, int?, int?, UnixFileMode?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L1399-L1412)

Creates or updates files and/or folders at the destination path in the container. Receives a callback that will be invoked when the container is started to allow the files to be created based on other resources in the application model.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithContainerFiles<T>(
        this IResourceBuilder<T> builder,
        string destinationPath,
        Func<ContainerFileSystemCallbackContext, CancellationToken, Task<IEnumerable<ContainerFileSystemItem>>> callback,
        int? defaultOwner = null,
        int? defaultGroup = null,
        UnixFileMode? umask = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the container resource.
- `destinationPath` (`string`)
  The destination (absolute) path in the container.
- `callback` (`Func<ContainerFileSystemCallbackContext, CancellationToken, Task<IEnumerable<ContainerFileSystemItem>>>`)
  The callback that will be invoked when the resource is being created.
- `defaultOwner` (`int?`) `optional`
  The default owner UID for the created or updated file system. Defaults to 0 for root if not set.
- `defaultGroup` (`int?`) `optional`
  The default group ID for the created or updated file system. Defaults to 0 for root if not set.
- `umask` (`UnixFileMode?`) `optional`
  The umask `IO.UnixFileMode` permissions to exclude from the default file and folder permissions. This takes away (rather than granting) default permissions to files and folders without an explicit mode permission set.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

For containers with a [ContainerLifetime.Persistent](/reference/api/csharp/aspire.hosting/containerlifetime/fields.md) lifetime, changing the contents of create file entries will result in the container being recreated. Make sure any data being written to containers is idempotent for a given app model configuration. Specifically, be careful not to include any data that will be unique on a per-run basis.

Create a configuration file for every Postgres instance in the application model.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
    .WithContainerFiles("/", (context, cancellationToken) =>
    {
        var appModel = context.ServiceProvider.GetRequiredService<DistributedApplicationModel>();
        var postgresInstances = appModel.Resources.OfType<PostgresDatabaseResource>();

        return [
            new ContainerDirectory
            {
                Name = ".pgweb",
                Entries = [
                    new ContainerDirectory
                    {
                        Name = "bookmarks",
                        Entries = postgresInstances.Select(instance =>
                        new ContainerFile
                        {
                            Name = $"{instance.Name}.toml",
                            Contents = instance.ToPgWebBookmark(),
                            Owner = defaultOwner,
                            Group = defaultGroup,
                        }),
                },
            ],
        },
    ];
});
```

## ATS metadata

### Ignored by ATS

- Reason: ContainerFileSystemCallbackContext exposes IServiceProvider and IResource -- .NET runtime types not usable from polyglot hosts.

## WithContainerFiles(IResourceBuilder<T>, string, string, int?, int?, UnixFileMode?)

- Name: `WithContainerFiles(IResourceBuilder<T>, string, string, int?, int?, UnixFileMode?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L1432-L1461)

Creates or updates files and/or folders at the destination path in the container by copying them from a source path on the host. In run mode, this will copy the files from the host to the container at runtime, allowing for overriding ownership and permissions in the container. In publish mode, this will create a bind mount to the source path on the host.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithContainerFiles<T>(
        this IResourceBuilder<T> builder,
        string destinationPath,
        string sourcePath,
        int? defaultOwner = null,
        int? defaultGroup = null,
        UnixFileMode? umask = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the container resource.
- `destinationPath` (`string`)
  The destination (absolute) path in the container.
- `sourcePath` (`string`)
  The source path on the host to copy files from.
- `defaultOwner` (`int?`) `optional`
  The default owner UID for the created or updated file system. Defaults to 0 for root if not set.
- `defaultGroup` (`int?`) `optional`
  The default group ID for the created or updated file system. Defaults to 0 for root if not set.
- `umask` (`UnixFileMode?`) `optional`
  The umask `IO.UnixFileMode` permissions to exclude from the default file and folder permissions. This takes away (rather than granting) default permissions to files and folders without an explicit mode permission set.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: Uses UnixFileMode parameter which is not ATS-compatible.

## WithContainerName(IResourceBuilder<T>, string)

- Name: `WithContainerName(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L1046-L1049)

Overrides the default container name for this resource. By default Aspire generates a unique container name based on the resource name and a random postfix (or a postfix based on a hash of the AppHost project path for persistent container resources). This method allows you to override that behavior with a custom name, but could lead to naming conflicts if the specified name is not unique.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithContainerName<T>(
        this IResourceBuilder<T> builder,
        string name)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the container resource.
- `name` (`string`)
  The desired container name. Must be a valid container name or your runtime will report an error.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

Combining this with [ContainerLifetime.Persistent](/reference/api/csharp/aspire.hosting/containerlifetime/fields.md) will allow Aspire to re-use an existing container that was not created by an Aspire AppHost.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithContainerNetworkAlias(IResourceBuilder<T>, string)

- Name: `WithContainerNetworkAlias(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L1710)

Adds a network alias to container resource.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithContainerNetworkAlias<T>(
        this IResourceBuilder<T> builder,
        string alias)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the container resource.
- `alias` (`string`)
  The network alias for the container.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

Network aliases enable DNS resolution of the container on the network by custom names. By default, containers are accessible on the network using their resource name as a DNS alias. This method allows adding additional aliases for the same container.

Multiple aliases can be added by calling this method multiple times.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithContainerRuntimeArgs(IResourceBuilder<T>, string[])

- Name: `WithContainerRuntimeArgs(IResourceBuilder<T>, string[])`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L480-L482)

Adds a callback to be executed with a list of arguments to add to the container runtime run command when a container resource is started.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithContainerRuntimeArgs<T>(
        this IResourceBuilder<T> builder,
        params string[] args)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Builder for the container resource.
- `args` (`string[]`)
  The arguments to be passed to the container runtime run command when the container resource is started.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This is intended to pass additional arguments to the underlying container runtime run command to enable advanced features such as exposing GPUs to the container. To pass runtime arguments to the actual container, use the [ResourceBuilderExtensions.WithArgs(IResourceBuilder<T>, string[])](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withargs-iresourcebuilder-t-string) method.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithContainerRuntimeArgs(IResourceBuilder<T>, Action<ContainerRuntimeArgsCallbackContext>)

- Name: `WithContainerRuntimeArgs(IResourceBuilder<T>, Action<ContainerRuntimeArgsCallbackContext>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Adds a callback to be executed with a list of arguments to add to the container runtime run command when a container resource is started.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithContainerRuntimeArgs<T>(
        this IResourceBuilder<T> builder,
        Action<ContainerRuntimeArgsCallbackContext> callback)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Builder for the container resource.
- `callback` (`Action<ContainerRuntimeArgsCallbackContext>`)
  A callback that allows for deferred execution for computing arguments. This runs after resources have been allocation by the orchestrator and allows access to other resources to resolve computed data, e.g. connection strings, ports.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This is intended to pass additional arguments to the underlying container runtime run command to enable advanced features such as exposing GPUs to the container. To pass runtime arguments to the actual container, use the [ResourceBuilderExtensions.WithArgs(IResourceBuilder<T>, string[])](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withargs-iresourcebuilder-t-string) method.

## ATS metadata

### Ignored by ATS

- Reason: ContainerRuntimeArgsCallbackContext exposes IList<object> -- not usable from polyglot hosts.

## WithContainerRuntimeArgs(IResourceBuilder<T>, Func<ContainerRuntimeArgsCallbackContext, Task>)

- Name: `WithContainerRuntimeArgs(IResourceBuilder<T>, Func<ContainerRuntimeArgsCallbackContext, Task>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Adds a callback to be executed with a list of arguments to add to the container runtime run command when a container resource is started.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithContainerRuntimeArgs<T>(
        this IResourceBuilder<T> builder,
        Func<ContainerRuntimeArgsCallbackContext, Task> callback)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Builder for the container resource.
- `callback` (`Func<ContainerRuntimeArgsCallbackContext, Task>`)
  A callback that allows for deferred execution for computing arguments. This runs after resources have been allocation by the orchestrator and allows access to other resources to resolve computed data, e.g. connection strings, ports.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This is intended to pass additional arguments to the underlying container runtime run command to enable advanced features such as exposing GPUs to the container. To pass runtime arguments to the actual container, use the [ResourceBuilderExtensions.WithArgs(IResourceBuilder<T>, string[])](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withargs-iresourcebuilder-t-string) method.

## ATS metadata

### Ignored by ATS

- Reason: ContainerRuntimeArgsCallbackContext exposes IList<object> -- not usable from polyglot hosts.

## WithDockerfile(IResourceBuilder<T>, string, string?, string?)

- Name: `WithDockerfile(IResourceBuilder<T>, string, string?, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L630-L679)

Causes Aspire to build the specified container image from a Dockerfile.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithDockerfile<T>(
        this IResourceBuilder<T> builder,
        string contextPath,
        string? dockerfilePath = null,
        string? stage = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The `ApplicationModel.IResourceBuilder`1`.
- `contextPath` (`string`)
  Path to be used as the context for the container image build.
- `dockerfilePath` (`string?`) `optional`
  Path to the Dockerfile relative to the `contextPath`. Defaults to "Dockerfile" if not specified.
- `stage` (`string?`) `optional`
  The stage representing the image to be published in a multi-stage Dockerfile.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

When this method is called an annotation is added to the [ContainerResource](/reference/api/csharp/aspire.hosting/containerresource.md) that specifies the context path and Dockerfile path to be used when building the container image. These details are then used by the orchestrator to build the image before using that image to start the container.

The `contextPath` is relative to the AppHost directory unless it is a fully qualified path. The `dockerfilePath` is relative to the `contextPath` unless it is a fully qualified path. If the `dockerfilePath` is not provided, it defaults to "Dockerfile" in the `contextPath`.

When generating the manifest for deployment tools, the [ContainerResourceBuilderExtensions.WithDockerfile(IResourceBuilder<T>, string, string?, string?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withdockerfile-iresourcebuilder-t-string-string-string) method results in an additional attribute being added to the `container.v0` resource type which contains the configuration necessary to allow the deployment tool to build the container image prior to deployment.

Creates a container called `mycontainer` with an image called `myimage`.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithDockerfile("path/to/context");

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithDockerfileBaseImage(IResourceBuilder<T>, string?, string?)

> **Experimental:** ASPIREDOCKERFILEBUILDER001 - [Learn more](/diagnostics/aspiredockerfilebuilder001/)

- Name: `WithDockerfileBaseImage(IResourceBuilder<T>, string?, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L1676-L1687)

Configures custom base images for generated Dockerfiles.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithDockerfileBaseImage<T>(
        this IResourceBuilder<T> builder,
        string? buildImage = null,
        string? runtimeImage = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `buildImage` (`string?`) `optional`
  The base image to use for the build stage. If null, uses the default build image.
- `runtimeImage` (`string?`) `optional`
  The base image to use for the runtime stage. If null, uses the default runtime image.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This extension method allows customization of the base images used in generated Dockerfiles. For multi-stage Dockerfiles (e.g., Python with UV), you can specify separate build and runtime images.

Specify custom base images for a Python application:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddPythonApp("myapp", "path/to/app", "main.py")
       .WithDockerfileBaseImage(
           buildImage: "ghcr.io/astral-sh/uv:python3.12-bookworm-slim",
           runtimeImage: "python:3.12-slim-bookworm");

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithDockerfileBuilder(IResourceBuilder<T>, string, Func<DockerfileBuilderCallbackContext, Task>, string?)

> **Experimental:** ASPIREDOCKERFILEBUILDER001 - [Learn more](/diagnostics/aspiredockerfilebuilder001/)

- Name: `WithDockerfileBuilder(IResourceBuilder<T>, string, Func<DockerfileBuilderCallbackContext, Task>, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Builds the specified container image from a Dockerfile generated by a callback using the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithDockerfileBuilder<T>(
        this IResourceBuilder<T> builder,
        string contextPath,
        Func<DockerfileBuilderCallbackContext, Task> callback,
        string? stage = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The `ApplicationModel.IResourceBuilder`1`.
- `contextPath` (`string`)
  Path to be used as the context for the container image build.
- `callback` (`Func<DockerfileBuilderCallbackContext, Task>`)
  A callback that uses the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API to construct the Dockerfile.
- `stage` (`string?`) `optional`
  The stage representing the image to be published in a multi-stage Dockerfile.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method provides a programmatic way to build Dockerfiles using the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API instead of string manipulation. Callbacks can be composed by calling this method multiple times - each callback will be invoked in order to build up the final Dockerfile.

The `contextPath` is relative to the AppHost directory unless it is fully qualified.

Creates a container with a programmatically built Dockerfile using fluent API:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithDockerfileBuilder("path/to/context", context =>
       {
           context.Builder.From("alpine:latest")
               .WorkDir("/app")
               .Run("apk add curl")
               .Copy(".", ".")
               .Cmd(["./myapp"]);
           return Task.CompletedTask;
       });

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithDockerfileBuilder(IResourceBuilder<T>, string, Action<DockerfileBuilderCallbackContext>, string?)

> **Experimental:** ASPIREDOCKERFILEBUILDER001 - [Learn more](/diagnostics/aspiredockerfilebuilder001/)

- Name: `WithDockerfileBuilder(IResourceBuilder<T>, string, Action<DockerfileBuilderCallbackContext>, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Builds the specified container image from a Dockerfile generated by a synchronous callback using the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithDockerfileBuilder<T>(
        this IResourceBuilder<T> builder,
        string contextPath,
        Action<DockerfileBuilderCallbackContext> callback,
        string? stage = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The `ApplicationModel.IResourceBuilder`1`.
- `contextPath` (`string`)
  Path to be used as the context for the container image build.
- `callback` (`Action<DockerfileBuilderCallbackContext>`)
  A synchronous callback that uses the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API to construct the Dockerfile.
- `stage` (`string?`) `optional`
  The stage representing the image to be published in a multi-stage Dockerfile.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method provides a programmatic way to build Dockerfiles using the [DockerfileBuilder](/reference/api/csharp/aspire.hosting/dockerfilebuilder.md) API instead of string manipulation. Callbacks can be composed by calling this method multiple times - each callback will be invoked in order to build up the final Dockerfile.

The `contextPath` is relative to the AppHost directory unless it is fully qualified.

Creates a container with a programmatically built Dockerfile using fluent API:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithDockerfileBuilder("path/to/context", context =>
       {
           context.Builder.From("node:18")
               .WorkDir("/app")
               .Copy("package*.json", "./")
               .Run("npm ci");
       });

builder.Build().Run();
```

## ATS metadata

### Ignored by ATS

- Reason: This synchronous overload is excluded from the polyglot surface; only the async callback overload is exported.

## WithDockerfileFactory(IResourceBuilder<T>, string, Func<DockerfileFactoryContext, string>, string?)

- Name: `WithDockerfileFactory(IResourceBuilder<T>, string, Func<DockerfileFactoryContext, string>, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Builds the specified container image from a Dockerfile generated by a synchronous factory function.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithDockerfileFactory<T>(
        this IResourceBuilder<T> builder,
        string contextPath,
        Func<DockerfileFactoryContext, string> dockerfileFactory,
        string? stage = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The `ApplicationModel.IResourceBuilder`1`.
- `contextPath` (`string`)
  Path to be used as the context for the container image build.
- `dockerfileFactory` (`Func<DockerfileFactoryContext, string>`)
  A synchronous function that returns the Dockerfile content as a string.
- `stage` (`string?`) `optional`
  The stage representing the image to be published in a multi-stage Dockerfile.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

When this method is called, an annotation is added to the [ContainerResource](/reference/api/csharp/aspire.hosting/containerresource.md) that specifies the context path and a factory function that generates Dockerfile content. The factory is invoked at build time to produce the Dockerfile, which is then written to a temporary file and used by the orchestrator to build the container image.

The `contextPath` is relative to the AppHost directory unless it is fully qualified.

The factory function is invoked once during the build process to generate the Dockerfile content. The output is trusted and not validated.

Creates a container called `mycontainer` with a dynamically generated Dockerfile.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithDockerfileFactory("path/to/context", context =>
       {
           return "FROM alpine:latest\nRUN echo 'Hello World'";
       });

builder.Build().Run();
```

## ATS metadata

### Ignored by ATS

- Reason: DockerfileFactoryContext exposes IServiceProvider and IResource -- .NET runtime types not usable from polyglot hosts.

## WithDockerfileFactory(IResourceBuilder<T>, string, Func<DockerfileFactoryContext, Task<string>>, string?)

- Name: `WithDockerfileFactory(IResourceBuilder<T>, string, Func<DockerfileFactoryContext, Task<string>>, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs)

Builds the specified container image from a Dockerfile generated by an asynchronous factory function.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithDockerfileFactory<T>(
        this IResourceBuilder<T> builder,
        string contextPath,
        Func<DockerfileFactoryContext, Task<string>> dockerfileFactory,
        string? stage = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The `ApplicationModel.IResourceBuilder`1`.
- `contextPath` (`string`)
  Path to be used as the context for the container image build.
- `dockerfileFactory` (`Func<DockerfileFactoryContext, Task<string>>`)
  An asynchronous function that returns the Dockerfile content as a string.
- `stage` (`string?`) `optional`
  The stage representing the image to be published in a multi-stage Dockerfile.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

When this method is called, an annotation is added to the [ContainerResource](/reference/api/csharp/aspire.hosting/containerresource.md) that specifies the context path and a factory function that generates Dockerfile content. The factory is invoked at build time to produce the Dockerfile, which is then written to a temporary file and used by the orchestrator to build the container image.

The `contextPath` is relative to the AppHost directory unless it is fully qualified.

The factory function is invoked once during the build process to generate the Dockerfile content. The output is trusted and not validated.

Creates a container called `mycontainer` with a dynamically generated Dockerfile.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithDockerfileFactory("path/to/context", async context =>
       {
           var template = await File.ReadAllTextAsync("template.dockerfile", context.CancellationToken);
           return template.Replace("{{VERSION}}", "1.0");
       });

builder.Build().Run();
```

## ATS metadata

### Ignored by ATS

- Reason: DockerfileFactoryContext exposes IServiceProvider and IResource -- .NET runtime types not usable from polyglot hosts.

## WithEndpointProxySupport(IResourceBuilder<T>, bool)

- Name: `WithEndpointProxySupport(IResourceBuilder<T>, bool)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L1482-L1486)

Set whether a container resource can use proxied endpoints or whether they should be disabled for all endpoints belonging to the container. If set to `false`, endpoints belonging to the container resource will ignore the configured proxy settings and run proxy-less.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEndpointProxySupport<T>(
        this IResourceBuilder<T> builder,
        bool proxyEnabled)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the container resource.
- `proxyEnabled` (`bool`)
  Should endpoints for the container resource support using a proxy?

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is intended to support scenarios with persistent lifetime containers where it is desirable for the container to be accessible over the same port whether the Aspire application is running or not. Proxied endpoints bind ports that are only accessible while the Aspire application is running. The user needs to be careful to ensure that container endpoints are using unique ports when disabling proxy support as by default for proxy-less endpoints, Aspire will allocate the internal container port as the host port, which will increase the chance of port conflicts.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithEntrypoint(IResourceBuilder<T>, string)

- Name: `WithEntrypoint(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L318-L322)

Sets the Entrypoint for the container.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEntrypoint<T>(
        this IResourceBuilder<T> builder,
        string entrypoint)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `entrypoint` (`string`)
  The new entrypoint for the container.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithImage(IResourceBuilder<T>, string, string?)

- Name: `WithImage(IResourceBuilder<T>, string, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L388-L442)

Allows overriding the image on a container.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithImage<T>(
        this IResourceBuilder<T> builder,
        string image,
        string? tag = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Builder for the container resource.
- `image` (`string`)
  Image value.
- `tag` (`string?`) `optional`
  Tag value.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithImagePullPolicy(IResourceBuilder<T>, ImagePullPolicy)

- Name: `WithImagePullPolicy(IResourceBuilder<T>, ImagePullPolicy)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L568-L570)

Sets the pull policy for the container resource.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithImagePullPolicy<T>(
        this IResourceBuilder<T> builder,
        ImagePullPolicy pullPolicy)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Builder for the container resource.
- `pullPolicy` ([ImagePullPolicy](/reference/api/csharp/aspire.hosting/imagepullpolicy.md))
  The pull policy behavior for the container resource.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithImageRegistry(IResourceBuilder<T>, string?)

- Name: `WithImageRegistry(IResourceBuilder<T>, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L366-L374)

Allows overriding the image registry on a container.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithImageRegistry<T>(
        this IResourceBuilder<T> builder,
        string? registry)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Builder for the container resource.
- `registry` (`string?`)
  Registry value.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithImageSHA256(IResourceBuilder<T>, string)

- Name: `WithImageSHA256(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L455-L464)

Allows setting the image to a specific sha256 on a container.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithImageSHA256<T>(
        this IResourceBuilder<T> builder,
        string sha256)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Builder for the container resource.
- `sha256` (`string`)
  Registry value.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithImageTag(IResourceBuilder<T>, string)

- Name: `WithImageTag(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L335-L353)

Allows overriding the image tag on a container.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithImageTag<T>(
        this IResourceBuilder<T> builder,
        string tag)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Builder for the container resource.
- `tag` (`string`)
  Tag value.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithLifetime(IResourceBuilder<T>, ContainerLifetime)

- Name: `WithLifetime(IResourceBuilder<T>, ContainerLifetime)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L553-L555)

Sets the lifetime behavior of the container resource.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithLifetime<T>(
        this IResourceBuilder<T> builder,
        ContainerLifetime lifetime)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Builder for the container resource.
- `lifetime` ([ContainerLifetime](/reference/api/csharp/aspire.hosting/containerlifetime.md))
  The lifetime behavior of the container resource. The defaults behavior is [ContainerLifetime.Session](/reference/api/csharp/aspire.hosting/containerlifetime/fields.md).

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

Marking a container resource to have a [ContainerLifetime.Persistent](/reference/api/csharp/aspire.hosting/containerlifetime/fields.md) lifetime.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithLifetime(ContainerLifetime.Persistent);

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithVolume(IResourceBuilder<T>, string?, string, bool)

- Name: `WithVolume(IResourceBuilder<T>, string?, string, bool)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L201-L205)

Adds a volume to a container resource.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithVolume<T>(
        this IResourceBuilder<T> builder,
        string? name,
        string target,
        bool isReadOnly = false)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `name` (`string?`)
  The name of the volume.
- `target` (`string`)
  The target path where the volume is mounted in the container.
- `isReadOnly` (`bool`) `optional`
  A flag that indicates if the volume should be mounted as read-only.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

Volumes are used to persist file-based data generated by and used by the container. They are managed by the container runtime and can be shared among multiple containers. They are not shared with the host's file-system. To mount files from the host inside the container, call [ContainerResourceBuilderExtensions.WithBindMount(IResourceBuilder<T>, string, string, bool)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withbindmount-iresourcebuilder-t-string-string-bool).

If a value for the `name` of the volume is not provided, the volume is created as an "anonymous volume" and will be given a random name by the container runtime. To share a volume between multiple containers, specify the same `name`.

The `target` path specifies the path the volume will be mounted inside the container's file system.

Adds a volume named `data` that will be mounted in the container's file system at the path `/usr/data`:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithVolume("data", "/usr/data");

builder.Build().Run();
```

## ATS metadata

### Ignored by ATS

- Reason: Polyglot export is via CoreExports.WithVolume which reorders parameters.

## WithVolume(IResourceBuilder<T>, string)

- Name: `WithVolume(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L242-L246)

Adds an anonymous volume to a container resource.

```csharp
public static class ContainerResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithVolume<T>(
        this IResourceBuilder<T> builder,
        string target)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `target` (`string`)
  The target path where the volume is mounted in the container.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

Volumes are used to persist file-based data generated by and used by the container. They are managed by the container runtime and can be shared among multiple containers. They are not shared with the host's file-system. To mount files from the host inside the container, call [ContainerResourceBuilderExtensions.WithBindMount(IResourceBuilder<T>, string, string, bool)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withbindmount-iresourcebuilder-t-string-string-bool).

This overload will create an "anonymous volume" and will be given a random name by the container runtime. To share a volume between multiple containers, call [ContainerResourceBuilderExtensions.WithVolume(IResourceBuilder<T>, string?, string, bool)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withvolume-iresourcebuilder-t-string-string-bool) and specify the same value for `name`.

The `target` path specifies the path the volume will be mounted inside the container's file system.

Adds an anonymous volume that will be mounted in the container's file system at the path `/usr/data`:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithVolume("/usr/data");

builder.Build().Run();
```

## ATS metadata

### Ignored by ATS

- Reason: Polyglot export is via CoreExports.WithVolume which accepts optional name parameter.