Edit

Share via

Docker Compose to Aspire AppHost API reference

This reference provides systematic mappings from Docker Compose YAML syntax to equivalent Aspire C# API calls. Use these tables as a quick reference when converting your existing Docker Compose files to Aspire application host configurations. Each section covers a specific aspect of container orchestration, from basic service definitions to advanced networking and resource management.

Service definitions

Docker Compose Aspire Notes
services: var builder = DistributedApplication.CreateBuilder(args) Root application builder used for adding and representing resources.
service_name: builder.Add*("service_name") Service name becomes resource name.

Related links:

Images and builds

Docker Compose Aspire Notes
image: nginx:latest builder.AddContainer("name", "nginx:latest") Direct image reference.
build: . builder.AddDockerfile("name", ".") Build from Dockerfile.
build: ./path builder.AddDockerfile("name", "./path") Build from specific path.
build.context: ./app builder.AddDockerfile("name", "./app") Build context.
build.dockerfile: Custom.dockerfile builder.Add*("name").WithDockerfile("Custom.dockerfile") Custom Dockerfile name.

Related links:

.NET projects

Docker Compose Aspire Notes
build: ./MyApi (for .NET) builder.AddProject<Projects.MyApi>("myapi") Direct .NET project reference.

Related links:

Port mappings

Docker Compose Aspire Notes
ports: ["8080:80"] .WithHttpEndpoint(port: 8080, targetPort: 80) HTTP endpoint mapping. Ports are optional; dynamic ports are used if omitted.
ports: ["443:443"] .WithHttpsEndpoint(port: 443, targetPort: 443) HTTPS endpoint mapping. Ports are optional; dynamic ports are used if omitted.
expose: ["8080"] .WithEndpoint(port: 8080) Internal port exposure. Ports are optional; dynamic ports are used if omitted.

Related links:

Environment variables

Docker Compose Aspire Notes
environment: KEY=value .WithEnvironment("KEY", "value") Static environment variable.
environment: KEY=${HOST_VAR} .WithEnvironment(context => context.EnvironmentVariables["KEY"] = hostVar) Environment variable with callback context.
env_file: .env Not supported Environment file (custom implementation).

Related links:

Volumes and storage

Docker Compose Aspire Notes
volumes: ["data:/app/data"] .WithVolume("data", "/app/data") Named volume.
volumes: ["./host:/container"] .WithBindMount("./host", "/container") Bind mount.
volumes: ["./config:/app:ro"] .WithBindMount("./config", "/app", isReadOnly: true) Read-only bind mount.

Related links:

Dependencies and ordering

Docker Compose Aspire Notes
depends_on: [db] .WithReference(db) Service dependency with connection.
depends_on: db: condition: service_started .WaitFor(db) Wait for service start.
depends_on: db: condition: service_healthy .WaitForCompletion(db) Wait for health check.

Related links:

Networks

Docker Compose Aspire Notes
networks: [backend] Automatic Aspire handles networking automatically.
Custom networks Not needed Service discovery handles inter-service communication.

Related links:

Resource limits

Docker Compose Aspire Notes
deploy.resources.limits.memory: 512m Not supported Resource limits aren't supported in Aspire.
deploy.resources.limits.cpus: 0.5 Not supported Resource limits aren't supported in Aspire.

Related links:

Health checks

Docker Compose Aspire Notes
healthcheck.test: ["CMD", "curl", "http://localhost/health"] Built-in for integrations. Aspire integrations include health checks.
healthcheck.interval: 30s Configurable in integration. Health check configuration varies by resource type.

Related links:

Restart policies

Docker Compose Aspire Notes
restart: unless-stopped Not supported Restart policies aren't supported in Aspire.
restart: always Not supported Restart policies aren't supported in Aspire.
restart: no Default No restart policy.

Related links:

Logging

Docker Compose Aspire Notes
logging.driver: json-file Built-in Aspire provides integrated logging.
logging.options.max-size: 10m Dashboard configuration Managed through Aspire dashboard.

Related links:

Database services

Docker Compose Aspire Notes
image: postgres:15 builder.AddPostgres("name") PostgreSQL with automatic configuration.
image: mysql:8 builder.AddMySql("name") MySQL with automatic configuration.
image: redis:7 builder.AddRedis("name") Redis with automatic configuration.
image: mongo:latest builder.AddMongoDB("name") MongoDB with automatic configuration.

Related links:

See also