ContainerResourceBuilderExtensions Methods
ClassMethods37 members
Provides extension methods for
IDistributedApplicationBuilder to add container resources to the application. AddContainer(IDistributedApplicationBuilder, string, string)Section titled 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) { // ... }}Parameters
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)Section titled 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) { // ... }}Parameters
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?)Section titled 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) { // ... }}Parameters
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.
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?)Section titled 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) { // ... }}Parameters
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.
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?)Section titled 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) { // ... }}Parameters
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.
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?)Section titled 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) { // ... }}Parameters
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?)Section titled 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) { // ... }}Parameters
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>)Section titled 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) { // ... }}Parameters
builderIResourceBuilder<T>Resource builder.Returns
IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.WithBindMount(IResourceBuilder<T>, string, string, bool)Section titled 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) { // ... }}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 app host 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 app host project directory path.
The target path specifies the path the file or directory will be mounted inside the container's file system.
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: var builder = DistributedApplication.CreateBuilder(args);
builder.AddContainer("mycontainer", "myimage") .WithBindMount("./config", "/database/config", isReadOnly: true);
builder.Build().Run();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: 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?)Section titled 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) { // ... }}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.
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>)Section titled 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) { // ... }}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.
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>)Section titled 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) { // ... }}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.
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>)Section titled 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) { // ... }}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 app hosts. Use the ATS wrapper overload instead.
WithContainerFiles(IResourceBuilder<T>, string, IEnumerable<ContainerFileSystemItem>, int?, int?, UnixFileMode?)Section titled 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) { // ... }}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.
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?)Section titled 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) { // ... }}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.
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, }), }, ], }, ];});WithContainerFiles(IResourceBuilder<T>, string, string, int?, int?, UnixFileMode?)Section titled 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) { // ... }}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.Remarks
This method is not available in polyglot app hosts.
WithContainerName(IResourceBuilder<T>, string)Section titled 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) { // ... }}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)Section titled 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) { // ... }}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[])Section titled 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) { // ... }}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>)Section titled 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) { // ... }}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>)Section titled 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) { // ... }}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?)Section titled 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) { // ... }}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.
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?)Section titled 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) { // ... }}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?)Section titled 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) { // ... }}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.
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?)Section titled 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) { // ... }}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.
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?)Section titled 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) { // ... }}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 calledmycontainer 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?)Section titled 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) { // ... }}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 calledmycontainer 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)Section titled 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) { // ... }}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)Section titled 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) { // ... }}Parameters
builderIResourceBuilder<T>The resource builder.entrypointstringThe new entrypoint for the container.Returns
IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.WithImage(IResourceBuilder<T>, string, string?)Section titled 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) { // ... }}Parameters
builderIResourceBuilder<T>Builder for the container resource.imagestringImage value.tagstring?optionalTag value.Returns
IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.WithImagePullPolicy(IResourceBuilder<T>, ImagePullPolicy)Section titled 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) { // ... }}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?)Section titled 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) { // ... }}Parameters
builderIResourceBuilder<T>Builder for the container resource.registrystring?Registry value.Returns
IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.WithImageSHA256(IResourceBuilder<T>, string)Section titled 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) { // ... }}Parameters
builderIResourceBuilder<T>Builder for the container resource.sha256stringRegistry value.Returns
IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.WithImageTag(IResourceBuilder<T>, string)Section titled 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) { // ... }}Parameters
builderIResourceBuilder<T>Builder for the container resource.tagstringTag value.Returns
IResourceBuilder<T>The ApplicationModel.IResourceBuilder`1.WithLifetime(IResourceBuilder<T>, ContainerLifetime)Section titled 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) { // ... }}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.
ContainerLifetime.Persistent lifetime. var builder = DistributedApplication.CreateBuilder(args);
builder.AddContainer("mycontainer", "myimage") .WithPersistentLifetime();
builder.Build().Run();WithVolume(IResourceBuilder<T>, string?, string, bool)Section titled 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) { // ... }}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.
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.
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)Section titled 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) { // ... }}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.
/usr/data: var builder = DistributedApplication.CreateBuilder(args);
builder.AddContainer("mycontainer", "myimage") .WithVolume("/usr/data");
builder.Build().Run();