Docker integration

此内容尚不支持你的语言。

The Aspire Docker hosting integration enables you to deploy your Aspire applications using Docker Compose. This integration models Docker Compose environments as compute resources that can host your application services. When you use this integration, Aspire generates Docker Compose files that define all the services, networks, and volumes needed to run your application in a containerized environment. It supports:

Generating Docker Compose files from your app model for deployment
Orchestrating multiple services, including an Aspire dashboard for telemetry visualization
Configuring environment variables and service dependencies
Managing container networking and service discovery

Hosting integration

The Docker hosting integration is available in the 📦 Aspire.Hosting.Docker NuGet package:

aspire add docker

Aspire CLI 是交互式的；按提示选择合适的搜索结果：

Select an integration to add:

> docker (Aspire.Hosting.Docker)
> Other results listed as selectable options...

#:package Aspire.Hosting.Docker@*

<PackageReference Include="Aspire.Hosting.Docker" Version="*" />

Add Docker Compose environment resource

The following example demonstrates how to add a Docker Compose environment to your app model using the AddDockerComposeEnvironment method:

var builder = DistributedApplication.CreateBuilder(args);

var compose = builder.AddDockerComposeEnvironment("compose");

var cache = builder.AddRedis("cache")
                   .PublishAsDockerComposeService();

var api = builder.AddProject<Projects.Api>("api")
                 .WithReference(cache)
                 .PublishAsDockerComposeService();

var web = builder.AddProject<Projects.Web>("web")
                 .WithReference(cache)
                 .WithReference(api)
                 .PublishAsDockerComposeService();

builder.Build().Run();

The preceding code:

Creates a Docker Compose environment named compose
Adds a Redis cache service that will be included in the Docker Compose deployment
Adds an API service project that will be containerized and included in the deployment
Adds a web application that references both the cache and API service
Configures all services to be published as Docker Compose services using PublishAsDockerComposeService

Add Docker Compose environment resource with properties

You can configure various properties of the Docker Compose environment using the WithProperties method:

builder.AddDockerComposeEnvironment("compose")
       .WithProperties(env =>
       {
           env.DefaultContainerRegistry = "myregistry.azurecr.io";
           env.DefaultNetworkName = "my-network";
           env.BuildContainerImages = true;
       });

Add Docker Compose environment resource with compose file

You can customize the generated Docker Compose file using the ConfigureComposeFile method:

builder.AddDockerComposeEnvironment("compose")
       .ConfigureComposeFile(composeFile =>
       {
           composeFile.Networks.Add("custom-network", new()
           {
               Driver = "bridge"
           });
       });

Add Aspire dashboard resource to environment

The Docker hosting integration includes an Aspire dashboard for telemetry visualization. You can configure or disable it using the WithDashboard method:

// Enable dashboard with custom configuration
builder.AddDockerComposeEnvironment("compose")
       .WithDashboard(dashboard =>
       {
           dashboard.WithHostPort(8080)
                    .WithForwardedHeaders(enabled: true);
       });

// Disable dashboard
builder.AddDockerComposeEnvironment("compose")
       .WithDashboard(enabled: false);

The WithHostPort method configures the port used to access the Aspire dashboard from a browser. The WithForwardedHeaders method enables forwarded headers processing when the dashboard is accessed through a reverse proxy or load balancer.

Publishing and deployment

Aspire provides a progressive deployment workflow for Docker Compose, allowing you to publish, prepare environments, and deploy in separate steps or all at once.

Step 1: Publish the Application

To generate Docker Compose files and artifacts without building container images, use the aspire publish command:

aspire publish

This command:

Generates a docker-compose.yaml from the app host
Generates a .env file with expected parameters (unfilled)
Outputs everything to the aspire-output directory

Step 2: Prepare Environment Configurations

To prepare environment-specific configurations and build container images, use the aspire do prepare-{resource-name} command, where {resouce-name} is the name of the Docker Compose environment resource:

# For staging environment
aspire do prepare-compose --environment staging

# For production environment
aspire do prepare-compose --environment production

These commands:

Generate a docker-compose.yaml from the app host
Generate environment-specific .env files with filled-in values
Generate container images
Outputs everything to the aspire-output directory

Step 3: Deploy to Docker Compose

To perform the complete deployment workflow in one step, use the aspire deploy command:

aspire deploy

This command:

Generates a docker-compose.yaml from the app host
Generates environment-specific .env files with filled-in values
Generates container images
Outputs everything to the aspire-output directory
Runs docker compose up against the generated files

Cleaning Up Deployment (Optional)

To clean up a running Docker Compose deployment, use the aspire do docker-compose-down-{resource-name} command:

aspire do docker-compose-down-compose

This command stops and removes all containers, networks, and volumes created by the Docker Compose deployment.

Environment variables

The Docker hosting integration captures environment variables from your app model and includes them in a .env file. This ensures that all configuration is properly passed to the containerized services.

Customize environment file

For advanced scenarios, use ConfigureEnvFile to customize the generated .env file:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddDockerComposeEnvironment("compose")
    .ConfigureEnvFile(env =>
    {
        env["CUSTOM_VAR"] = new CapturedEnvironmentVariable
        {
            Name = "CUSTOM_VAR",
            DefaultValue = "my-value"
        };
    });

This is useful when you need to add custom environment variables to the generated .env file or modify how environment variables are captured.

Customize container image push options

When deploying containers, you can customize how container images are named and tagged when pushed to a registry. This is useful when you need to:

Use different image names for different environments
Apply custom tagging strategies (e.g., semantic versioning, Git commit hashes)
Push to different registries or namespaces

Set remote image name and tag

Use WithRemoteImageName and WithRemoteImageTag to customize the image reference:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.Api>("api")
    .PublishAsDockerComposeService()
    .WithRemoteImageName("myorg/myapi")
    .WithRemoteImageTag("v1.0.0");

// After adding all resources, run the app...

Advanced customization with callbacks

For more complex scenarios, use WithImagePushOptions to register a callback that can dynamically configure push options:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.Api>("api")
    .PublishAsDockerComposeService()
    .WithImagePushOptions(context =>
    {
        // Customize the image name based on the resource
        // Note: Ensure resource names are valid for container image names
        var imageName = context.Resource.Name.ToLowerInvariant();
        context.Options.RemoteImageName = $"myorg/{imageName}";

        // Apply a custom tag based on environment or version
        var version = Environment.GetEnvironmentVariable("APP_VERSION") ?? "latest";
        context.Options.RemoteImageTag = version;
    });

// After adding all resources, run the app...

For asynchronous operations (such as retrieving configuration from external sources), use the async overload:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.Api>("api")
    .PublishAsDockerComposeService()
    .WithImagePushOptions(async context =>
    {
        // Retrieve configuration asynchronously
        var config = await LoadConfigurationAsync();
        context.Options.RemoteImageName = config.ImageName;
        context.Options.RemoteImageTag = config.ImageTag;
    });

// After adding all resources, run the app...

Multiple callbacks can be registered on the same resource, and they will be invoked in the order they were added.