ContainerResourceBuilderExtensions Methods

AddContainer(IDistributedApplicationBuilder, string, string)extensionIResourceBuilder<ContainerResource>

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

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

ContainerResourceBuilderExtensions.cs#L119-L125

Parameters

builderIDistributedApplicationBuilderThe IDistributedApplicationBuilder.

namestringThe name of the resource.

imagestringThe container image name. The tag is assumed to be "latest".

Returns

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

AddContainer(IDistributedApplicationBuilder, string, string, string)extensionIResourceBuilder<ContainerResource>

Adds a container resource to the application.

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

ContainerResourceBuilderExtensions.cs#L139-L140

Parameters

builderIDistributedApplicationBuilderThe IDistributedApplicationBuilder.

namestringThe name of the resource.

imagestringThe container image name.

tagstringThe container image tag.

Returns

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

AddDockerfile(IDistributedApplicationBuilder, string, string, string?, string?)extensionIResourceBuilder<ContainerResource>

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

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

ContainerResourceBuilderExtensions.cs#L923-L928

Parameters

builderIDistributedApplicationBuilderThe IDistributedApplicationBuilder.

namestringThe name of the resource.

contextPathstringPath to be used as the context for the container image build.

dockerfilePathstring?optionalPath to the Dockerfile relative to the contextPath. Defaults to "Dockerfile" if not specified.

stagestring?optionalThe 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 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.

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

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

extensionIResourceBuilder<ContainerResource>

Adds a Dockerfile to the application model that can be treated like a container resource, with the Dockerfile generated programmatically using the DockerfileBuilder API.

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIDistributedApplicationBuilderThe IDistributedApplicationBuilder.

namestringThe name of the resource.

contextPathstringPath to be used as the context for the container image build.

callbackFunc<DockerfileBuilderCallbackContext, Task>A callback that uses the DockerfileBuilder API to construct the Dockerfile.

stagestring?optionalThe 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 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:

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();

AddDockerfileBuilder(IDistributedApplicationBuilder, string, string, Action<DockerfileBuilderCallbackContext>, string?)extensionIResourceBuilder<ContainerResource>

Adds a Dockerfile to the application model that can be treated like a container resource, with the Dockerfile generated programmatically using the DockerfileBuilder API.

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIDistributedApplicationBuilderThe IDistributedApplicationBuilder.

namestringThe name of the resource.

contextPathstringPath to be used as the context for the container image build.

callbackAction<DockerfileBuilderCallbackContext>A synchronous callback that uses the DockerfileBuilder API to construct the Dockerfile.

stagestring?optionalThe 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 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:

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();

AddDockerfileFactory(IDistributedApplicationBuilder, string, string, Func<DockerfileFactoryContext, string>, string?)extensionIResourceBuilder<ContainerResource>

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.

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIDistributedApplicationBuilderThe IDistributedApplicationBuilder.

namestringThe name of the resource.

contextPathstringPath to be used as the context for the container image build.

dockerfileFactoryFunc<DockerfileFactoryContext, string>A synchronous function that returns the Dockerfile content as a string.

stagestring?optionalThe 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.

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

extensionIResourceBuilder<ContainerResource>

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.

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIDistributedApplicationBuilderThe IDistributedApplicationBuilder.

namestringThe name of the resource.

contextPathstringPath to be used as the context for the container image build.

dockerfileFactoryFunc<DockerfileFactoryContext, Task<string>>An asynchronous function that returns the Dockerfile content as a string.

stagestring?optionalThe 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.

PublishAsContainer(IResourceBuilder<T>)extensionIResourceBuilder<T>

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

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

ContainerResourceBuilderExtensions.cs#L632-L634

Parameters

builderIResourceBuilder<T>Resource builder.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

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

Adds a bind mount to a container resource.

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

ContainerResourceBuilderExtensions.cs#L321-L328

Parameters

builderIResourceBuilder<T>The resource builder.

sourcestringThe source path of the mount. This is the path to the file or directory on the host, relative to the AppHost project directory.

targetstringThe target path where the file or directory is mounted in the container.

isReadOnlybooloptionalA flag that indicates if this is a read-only mount.

Returns

IResourceBuilder<T>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.

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 AppHost 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 AppHost 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:

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 AppHost 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:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

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

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

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIResourceBuilder<T>The resource builder for the container resource.

namestringThe name of the build argument.

valueobject?The value of the build argument.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

Exceptions

InvalidOperationException Thrown when ContainerResourceBuilderExtensions.WithBuildArg is called before ContainerResourceBuilderExtensions.WithDockerfile.

Remarks

The ContainerResourceBuilderExtensions.WithBuildArg 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.

Adding a static build argument.

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

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

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

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIResourceBuilder<T>The resource builder for the container resource.

namestringThe name of the build argument.

valueIResourceBuilder<ParameterResource>The resource builder for a parameter resource.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

Exceptions

InvalidOperationException Thrown when ContainerResourceBuilderExtensions.WithBuildArg is called before ContainerResourceBuilderExtensions.WithDockerfile.

Remarks

The ContainerResourceBuilderExtensions.WithBuildArg 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.

Adding a build argument based on a parameter..

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

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

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

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

ContainerResourceBuilderExtensions.cs#L1278-L1291

Parameters

builderIResourceBuilder<T>The resource builder for the container resource.

namestringThe name of the secret build argument.

valueIResourceBuilder<ParameterResource>The resource builder for a parameter resource.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

Exceptions

InvalidOperationException Thrown when ContainerResourceBuilderExtensions.WithBuildSecret is called before ContainerResourceBuilderExtensions.WithDockerfile.

Remarks

The ContainerResourceBuilderExtensions.WithBuildSecret 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.

Adding a build secret based on a parameter.

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();

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

Adds a ContainerCertificatePathsAnnotation 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.

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)
    {
        // ...
    }
}

ContainerResourceBuilderExtensions.cs#L1309-L1316

Parameters

builderIResourceBuilder<TResource>The resource builder.

customCertificatesDestinationstring?optionalThe 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/.

defaultCertificateBundlePathsList<string>optionalList of default certificate bundle paths in the container that will be replaced in CertificateTrustScope.Override or CertificateTrustScope.System modes. If not specified, defaults to /etc/ssl/certs/ca-certificates.crt for Linux containers.

defaultCertificateDirectoryPathsList<string>optionalList of default certificate directory paths in the container that may be appended to the custom certificates directory in CertificateTrustScope.Append 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 AppHosts. Use the ATS wrapper overload instead.

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

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

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)
    {
        // ...
    }
}

ContainerResourceBuilderExtensions.cs#L1390-L1403

Parameters

builderIResourceBuilder<T>The resource builder for the container resource.

destinationPathstringThe destination (absolute) path in the container.

entriesIEnumerable<ContainerFileSystemItem>The file system entries to create.

defaultOwnerint?optionalThe default owner UID for the created or updated file system. Defaults to 0 for root if not set.

defaultGroupint?optionalThe default group ID for the created or updated file system. Defaults to 0 for root if not set.

umaskUnixFileMode?optionalThe 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>The ApplicationModel.IResourceBuilder`1.

Remarks

For containers with a ContainerLifetime.Persistent 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.

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);

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

extensionIResourceBuilder<T>

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.

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)
    {
        // ...
    }
}

ContainerResourceBuilderExtensions.cs#L1462-L1475

Parameters

builderIResourceBuilder<T>The resource builder for the container resource.

destinationPathstringThe destination (absolute) path in the container.

callbackFunc<ContainerFileSystemCallbackContext, CancellationToken, Task<IEnumerable<ContainerFileSystemItem>>>The callback that will be invoked when the resource is being created.

defaultOwnerint?optionalThe default owner UID for the created or updated file system. Defaults to 0 for root if not set.

defaultGroupint?optionalThe default group ID for the created or updated file system. Defaults to 0 for root if not set.

umaskUnixFileMode?optionalThe 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>The ApplicationModel.IResourceBuilder`1.

Remarks

For containers with a ContainerLifetime.Persistent 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.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
    .WithContainerFiles("/", (context, cancellationToken) =>
    {
        var appModel = context
            .Services
            .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,
                        }),
                },
            ],
        },
    ];
});

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

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.

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)
    {
        // ...
    }
}

ContainerResourceBuilderExtensions.cs#L1494-L1523

Parameters

builderIResourceBuilder<T>The resource builder for the container resource.

destinationPathstringThe destination (absolute) path in the container.

sourcePathstringThe source path on the host to copy files from.

defaultOwnerint?optionalThe default owner UID for the created or updated file system. Defaults to 0 for root if not set.

defaultGroupint?optionalThe default group ID for the created or updated file system. Defaults to 0 for root if not set.

umaskUnixFileMode?optionalThe 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>The ApplicationModel.IResourceBuilder`1.

WithContainerName(IResourceBuilder<T>, string)extensionIResourceBuilder<T>

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.

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

ContainerResourceBuilderExtensions.cs#L1107-L1110

Parameters

builderIResourceBuilder<T>The resource builder for the container resource.

namestringThe desired container name. Must be a valid container name or your runtime will report an error.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

Remarks

Combining this with ContainerLifetime.Persistent will allow Aspire to re-use an existing container that was not created by an Aspire AppHost.

WithContainerNetworkAlias(IResourceBuilder<T>, string)extensionIResourceBuilder<T>

Adds a network alias to container resource.

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

ContainerResourceBuilderExtensions.cs#L1880

Parameters

builderIResourceBuilder<T>The resource builder for the container resource.

aliasstringThe network alias for the container.

Returns

IResourceBuilder<T>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.

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

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.

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

ContainerResourceBuilderExtensions.cs#L510-L512

Parameters

builderIResourceBuilder<T>Builder for the container resource.

argsstring[]The arguments to be passed to the container runtime run command when the container resource is started.

Returns

IResourceBuilder<T>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 method.

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

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.

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIResourceBuilder<T>Builder for the container resource.

callbackAction<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>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 method.

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

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.

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIResourceBuilder<T>Builder for the container resource.

callbackFunc<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>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 method.

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

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

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

ContainerResourceBuilderExtensions.cs#L679-L734

Parameters

builderIResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

contextPathstringPath to be used as the context for the container image build.

dockerfilePathstring?optionalPath to the Dockerfile relative to the contextPath. Defaults to "Dockerfile" if not specified.

stagestring?optionalThe stage representing the image to be published in a multi-stage Dockerfile.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

Remarks

When this method is called an annotation is added to the ContainerResource 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 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.

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

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

Configures custom base images for generated Dockerfiles.

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

ContainerResourceBuilderExtensions.cs#L1845-L1856

Parameters

builderIResourceBuilder<T>The resource builder.

buildImagestring?optionalThe base image to use for the build stage. If null, uses the default build image.

runtimeImagestring?optionalThe base image to use for the runtime stage. If null, uses the default runtime image.

Returns

IResourceBuilder<T>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:

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();

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

Builds the specified container image from a Dockerfile generated by a callback using the DockerfileBuilder API.

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

contextPathstringPath to be used as the context for the container image build.

callbackFunc<DockerfileBuilderCallbackContext, Task>A callback that uses the DockerfileBuilder API to construct the Dockerfile.

stagestring?optionalThe stage representing the image to be published in a multi-stage Dockerfile.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

Remarks

This method provides a programmatic way to build Dockerfiles using the DockerfileBuilder 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:

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();

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

Builds the specified container image from a Dockerfile generated by a synchronous callback using the DockerfileBuilder API.

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

contextPathstringPath to be used as the context for the container image build.

callbackAction<DockerfileBuilderCallbackContext>A synchronous callback that uses the DockerfileBuilder API to construct the Dockerfile.

stagestring?optionalThe stage representing the image to be published in a multi-stage Dockerfile.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

Remarks

This method provides a programmatic way to build Dockerfiles using the DockerfileBuilder 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:

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();

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

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

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

contextPathstringPath to be used as the context for the container image build.

dockerfileFactoryFunc<DockerfileFactoryContext, string>A synchronous function that returns the Dockerfile content as a string.

stagestring?optionalThe stage representing the image to be published in a multi-stage Dockerfile.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

Remarks

When this method is called, an annotation is added to the ContainerResource 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.

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();

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

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

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

ContainerResourceBuilderExtensions.cs

Parameters

builderIResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

contextPathstringPath to be used as the context for the container image build.

dockerfileFactoryFunc<DockerfileFactoryContext, Task<string>>An asynchronous function that returns the Dockerfile content as a string.

stagestring?optionalThe stage representing the image to be published in a multi-stage Dockerfile.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

Remarks

When this method is called, an annotation is added to the ContainerResource 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.

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();

WithEndpointProxySupport(IResourceBuilder<T>, bool)extensionIResourceBuilder<T>

Set whether a container resource can use proxied endpoints or whether they should be disabled for all endpoints belonging to the resource.

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

ContainerResourceBuilderExtensions.cs#L44

Parameters

builderIResourceBuilder<T>The resource builder.

proxyEnabledboolShould endpoints for the resource support using a proxy?

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

Remarks

This method is intended to support scenarios with persistent lifetime resources where it is desirable for the resource 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 endpoints are using unique ports when disabling proxy support as by default for proxy-less endpoints, Aspire will allocate the target port as the host port, which will increase the chance of port conflicts.

WithEntrypoint(IResourceBuilder<T>, string)extensionIResourceBuilder<T>

Sets the Entrypoint for the container.

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

ContainerResourceBuilderExtensions.cs#L342-L346

Parameters

builderIResourceBuilder<T>The resource builder.

entrypointstringThe new entrypoint for the container.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

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

Allows overriding the image on a container.

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

ContainerResourceBuilderExtensions.cs#L415-L469

Parameters

builderIResourceBuilder<T>Builder for the container resource.

imagestringImage value.

tagstring?optionalTag value.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

WithImagePullPolicy(IResourceBuilder<T>, ImagePullPolicy)extensionIResourceBuilder<T>

Sets the pull policy for the container resource.

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

ContainerResourceBuilderExtensions.cs#L614-L616

Parameters

builderIResourceBuilder<T>Builder for the container resource.

pullPolicyImagePullPolicyThe pull policy behavior for the container resource.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

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

Allows overriding the image registry on a container.

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

ContainerResourceBuilderExtensions.cs#L392-L400

Parameters

builderIResourceBuilder<T>Builder for the container resource.

registrystring?Registry value.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

WithImageSHA256(IResourceBuilder<T>, string)extensionIResourceBuilder<T>

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

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

ContainerResourceBuilderExtensions.cs#L483-L492

Parameters

builderIResourceBuilder<T>Builder for the container resource.

sha256stringRegistry value.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

WithImageTag(IResourceBuilder<T>, string)extensionIResourceBuilder<T>

Allows overriding the image tag on a container.

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

ContainerResourceBuilderExtensions.cs#L360-L378

Parameters

builderIResourceBuilder<T>Builder for the container resource.

tagstringTag value.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

WithLifetime(IResourceBuilder<T>, ContainerLifetime)extensionIResourceBuilder<T>

Sets the lifetime behavior of the container resource.

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

ContainerResourceBuilderExtensions.cs#L588-L600

Parameters

builderIResourceBuilder<T>Builder for the container resource.

lifetimeContainerLifetimeThe lifetime behavior of the container resource. The default behavior is ContainerLifetime.Session.

Returns

IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.

Remarks

Prefer ResourceBuilderExtensions.WithPersistentLifetime or ResourceBuilderExtensions.WithSessionLifetime for new code.

Marking a container resource to have a ContainerLifetime.Persistent lifetime.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithPersistentLifetime();

builder.Build().Run();

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

Adds a volume to a container resource.

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

ContainerResourceBuilderExtensions.cs#L230

Parameters

builderIResourceBuilder<T>The resource builder.

namestring?The name of the volume.

targetstringThe target path where the volume is mounted in the container.

isReadOnlybooloptionalA flag that indicates if the volume should be mounted as read-only.

Returns

IResourceBuilder<T>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.

Named volumes are preserved independently of the container lifetime. A session-lifetime container is removed when the AppHost stops and reuses the named volume on its next run. A persistent-lifetime container can remain running and keeps the same attached volume.

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:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

WithVolume(IResourceBuilder<T>, string)extensionIResourceBuilder<T>

Adds an anonymous volume to a container resource.

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

ContainerResourceBuilderExtensions.cs#L267

Parameters

builderIResourceBuilder<T>The resource builder.

targetstringThe target path where the volume is mounted in the container.

Returns

IResourceBuilder<T>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.

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 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:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();