Orchestrating .NET Multi-Service Apps: Manual Setup vs .NET Aspire vs Docker Compose

Running a single API against a single database is simple. Add a second service. Add a cache. Add a message broker. Add a worker. Suddenly you have five processes that need to find each other, share secrets, emit consistent telemetry, and start in the right order.

That coordination problem is what orchestration solves.

There are three mainstream approaches for .NET teams. This guide explains each one at depth — what it does internally, what it costs you, and the exact conditions that make it the right call.

The Problem Space

Before comparing tools, let's be precise about what we're orchestrating:

A typical .NET distributed system at development time:

  ┌──────────────────────────────────────────────────────────────────┐
  │  What needs to run:                                              │
  │                                                                  │
  │  Process 1: Web API          → localhost:5001                   │
  │  Process 2: Worker Service   → background, no port              │
  │  Process 3: Blazor Frontend  → localhost:5002                   │
  │                                                                  │
  │  Infrastructure:                                                 │
  │  PostgreSQL                  → localhost:5432                   │
  │  Redis                       → localhost:6379                   │
  │  RabbitMQ                    → localhost:5672 (amqp)            │
  │                              → localhost:15672 (management UI)  │
  └──────────────────────────────────────────────────────────────────┘

  What each service needs to know:
  - Where is PostgreSQL? (host, port, username, password, database name)
  - Where is Redis?
  - Where is RabbitMQ?
  - Where are the other services? (for service-to-service HTTP calls)

  What can go wrong:
  - Developer A has Postgres on port 5432, Developer B has it on 5433
  - Config differs between dev machines → "works on my machine"
  - Service starts before its dependency is ready → crash on startup
  - No unified logs → debugging requires 5 terminal windows
  - No health checks → a crashed worker isn't noticed until orders are lost

Orchestration answers: how do all these pieces find each other, and who starts them?

Approach 1: Manual Setup

The manual approach means each service reads its own appsettings.json, each developer manages their own local infrastructure, and nothing coordinates startup order.

┌──────────────────────────────────────────────────────────────────┐
│  Manual Setup — each service manages itself                      │
│                                                                  │
│  ┌─────────────────┐   ┌─────────────────┐   ┌───────────────┐  │
│  │   Web API        │   │  Worker Service  │   │    Blazor     │  │
│  │                  │   │                  │   │               │  │
│  │ appsettings.json │   │ appsettings.json │   │appsettings    │  │
│  │ (its own config) │   │ (its own config) │   │.json          │  │
│  └────────┬─────────┘   └────────┬─────────┘   └───────┬───────┘  │
│           │                      │                      │          │
│           └──────────────┬───────┘──────────────────────┘          │
│                          │                                          │
│                          ▼                                          │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │  Local infrastructure — started manually by each developer    │ │
│  │  PostgreSQL  Redis  RabbitMQ                                  │ │
│  │  (brew services start / docker run / installed locally)       │ │
│  └───────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘

What It Looks Like

Each service has its own appsettings.Development.json:

JSON

// WebApi/appsettings.Development.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=myapp;Username=postgres;Password=dev"
  },
  "Redis": {
    "ConnectionString": "localhost:6379"
  },
  "RabbitMq": {
    "Host": "localhost",
    "Port": 5672,
    "Username": "guest",
    "Password": "guest"
  },
  "Services": {
    "WorkerBaseUrl": "http://localhost:5003"
  }
}

JSON

// Worker/appsettings.Development.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=myapp;Username=postgres;Password=dev"
  },
  "RabbitMq": {
    "Host": "localhost",
    "Port": 5672,
    "Username": "guest",
    "Password": "guest"
  }
  // RabbitMQ config duplicated here — must stay in sync manually
}

The README.md becomes the orchestrator:

## Getting started

1. Install PostgreSQL 16 locally (or run: docker run -p 5432:5432 -e POSTGRES_PASSWORD=dev postgres:16)
2. Install Redis (or run: docker run -p 6379:6379 redis:alpine)
3. Install RabbitMQ (or run: docker run -p 5672:5672 -p 15672:15672 rabbitmq:3-management)
4. cd src/WebApi && dotnet run
5. cd src/Worker && dotnet run
6. cd src/Blazor && dotnet run

If the API crashes on startup, check that Postgres is running and the connection string matches.

The Config Drift Problem

  Week 1:
    Developer A: Postgres password = "dev"
    Developer B: Postgres password = "dev"   ← in sync

  Week 6 (after a security review):
    Developer A updates password to "dev_secure_2026" in their appsettings
    Developer B is on holiday
    Developer B returns → Worker crashes with auth failure
    Developer B checks the API config → "oh there's a different password now"
    
  Week 12:
    WebApi appsettings.Development.json:
      RabbitMq port: 5672
    Worker appsettings.Development.json:
      RabbitMq port: 5673  ← someone changed this to avoid a conflict
    Worker can't connect to API's RabbitMQ instance
    Debugging takes 45 minutes

  This is config drift. It's the real cost of manual setup at scale.

When Manual Setup Is Right

✅ Single API + one database
✅ Team of 1–2 developers who own every config file
✅ No shared infrastructure between services
✅ Greenfield project where you want zero overhead

❌ 2+ services sharing databases, caches, or brokers
❌ Team of 3+ developers (config drift becomes inevitable)
❌ New developers joining (onboarding becomes a config debugging session)

Approach 2: Docker Compose

Docker Compose defines your entire environment in a single YAML file. Every service, every infrastructure component, every network and volume — one source of truth, run with one command.

┌──────────────────────────────────────────────────────────────────┐
│  Docker Compose — YAML describes the entire environment          │
│                                                                  │
│  docker-compose.yml                                              │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  services:                                               │   │
│  │    api:    image or build context                        │   │
│  │    worker: image or build context                        │   │
│  │    web:    image or build context                        │   │
│  │    postgres: image: postgres:16                          │   │
│  │    redis:    image: redis:alpine                         │   │
│  │    rabbitmq: image: rabbitmq:3-management                │   │
│  └──────────────────────────────────────────────────────────┘   │
│            │                                                     │
│            ▼ docker compose up                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  Docker network: myapp_default                           │   │
│  │                                                          │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐               │   │
│  │  │   api    │  │  worker  │  │   web    │               │   │
│  │  │ :8080    │  │          │  │ :3000    │               │   │
│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘               │   │
│  │       │             │             │                       │   │
│  │       └─────────────┴─────────────┘                       │   │
│  │                     │                                     │   │
│  │       ┌─────────────┴─────────────┐                       │   │
│  │       ▼             ▼             ▼                       │   │
│  │  ┌─────────┐  ┌──────────┐  ┌──────────┐                │   │
│  │  │postgres │  │  redis   │  │ rabbitmq │                │   │
│  │  └─────────┘  └──────────┘  └──────────┘                │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  Services reach each other by container name:                    │
│  api → "http://worker:80" (not localhost)                        │
│  api → "Host=postgres;Port=5432;..."                             │
└──────────────────────────────────────────────────────────────────┘

The docker-compose.yml

YAML

# docker-compose.yml
version: "3.9"

services:
  api:
    build:
      context: ./src/WebApi
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__DefaultConnection=Host=postgres;Port=5432;Database=myapp;Username=postgres;Password=dev
      - Redis__ConnectionString=redis:6379
      - RabbitMq__Host=rabbitmq
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
      rabbitmq:
        condition: service_healthy
    networks:
      - myapp

  worker:
    build:
      context: ./src/Worker
      dockerfile: Dockerfile
    environment:
      - ConnectionStrings__DefaultConnection=Host=postgres;Port=5432;Database=myapp;Username=postgres;Password=dev
      - RabbitMq__Host=rabbitmq
    depends_on:
      postgres:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
    networks:
      - myapp

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: dev
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - myapp

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - myapp

  rabbitmq:
    image: rabbitmq:3.12-management-alpine
    environment:
      RABBITMQ_DEFAULT_USER: guest
      RABBITMQ_DEFAULT_PASS: guest
    ports:
      - "15672:15672"  # management UI accessible from host
    healthcheck:
      test: rabbitmq-diagnostics -q ping
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - myapp

volumes:
  postgres_data:
  redis_data:

networks:
  myapp:
    driver: bridge

What Docker Compose Solves

Config drift:        ✅ Fixed — one file, all config in one place
Startup order:       ✅ Fixed — depends_on with health checks
Network discovery:   ✅ Fixed — services reach each other by name
Onboarding:          ✅ Fixed — new dev runs docker compose up, done
Polyglot support:    ✅ Fixed — Node.js, Python, .NET, Go — doesn't care

What Docker Compose Doesn't Solve

Inner loop speed:    ❌ Every code change requires docker build → slow
                     (unless you mount source + use dotnet watch inside container)

Observability:       ❌ No built-in tracing, metrics, or log aggregation
                     You need to add Prometheus + Grafana + Jaeger manually

.NET integration:    ❌ YAML doesn't know about .NET projects
                     Ports, connection strings — all manual

Debugging:           ❌ Attaching a debugger to a container requires
                     additional configuration (VSDBG, SSH tunneling, etc.)

The Dockerfile Every .NET Service Needs

DOCKERFILE

# Dockerfile — multi-stage build for minimal image size
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src

# Copy project files first — layer cache optimization
COPY *.csproj .
RUN dotnet restore

# Copy everything else and publish
COPY . .
RUN dotnet publish -c Release -o /app/publish

FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS runtime
WORKDIR /app
COPY --from=build /app/publish .

# Non-root user — security best practice
RUN adduser --disabled-password --gecos "" appuser
USER appuser

EXPOSE 8080
ENTRYPOINT ["dotnet", "WebApi.dll"]

When Docker Compose Is Right

✅ Polyglot stack: .NET API + Node.js frontend + Python ML service
✅ Need production-like environment locally
✅ CI/CD pipelines: docker compose up for integration tests
✅ Infrastructure-heavy: multiple databases, caches, brokers
✅ Team uses multiple languages across services

❌ Pure .NET shop with fast inner loop requirement
❌ Team wants C# config instead of YAML
❌ Need built-in observability without manual wiring

Approach 3: .NET Aspire

.NET Aspire is Microsoft's answer to the orchestration problem specifically for .NET-heavy solutions. It replaces YAML with C# and replaces manual connection string wiring with automatic service discovery.

┌──────────────────────────────────────────────────────────────────┐
│  .NET Aspire — AppHost orchestrates everything in C#             │
│                                                                  │
│  AppHost (C# project)                                            │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  var postgres  = builder.AddPostgres("postgres")         │   │
│  │               .AddDatabase("myapp");                     │   │
│  │                                                          │   │
│  │  var redis     = builder.AddRedis("redis");              │   │
│  │                                                          │   │
│  │  var rabbitmq  = builder.AddRabbitMQ("rabbitmq");        │   │
│  │                                                          │   │
│  │  var api       = builder.AddProject()   │   │
│  │               .WithReference(postgres)                   │   │
│  │               .WithReference(redis)                      │   │
│  │               .WithReference(rabbitmq);                  │   │
│  │                                                          │   │
│  │  var worker    = builder.AddProject()   │   │
│  │               .WithReference(postgres)                   │   │
│  │               .WithReference(rabbitmq);                  │   │
│  └──────────────────────────────────────────────────────────┘   │
│            │                                                     │
│            ▼ dotnet run (AppHost)                                │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  Aspire Dashboard  :18888                                │   │
│  │  ┌──────────────────────────────────────────────────┐   │   │
│  │  │  Resources    Logs    Traces    Metrics           │   │   │
│  │  │                                                   │   │   │
│  │  │  ● api     running  :5001  view logs / traces     │   │   │
│  │  │  ● worker  running         view logs / traces     │   │   │
│  │  │  ● postgres running :5432                         │   │   │
│  │  │  ● redis   running  :6379                         │   │   │
│  │  │  ● rabbitmq running :5672  management: :15672     │   │   │
│  │  └──────────────────────────────────────────────────┘   │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  .NET projects run as processes (no Docker for your code)        │
│  Infrastructure runs as Docker containers (Postgres, Redis, etc) │
│  Connection strings auto-injected via environment variables      │
└──────────────────────────────────────────────────────────────────┘

AppHost: The C# Orchestrator

// AppHost/Program.cs — the entire dev environment in C#
var builder = DistributedApplication.CreateBuilder(args);

// Infrastructure resources — run as Docker containers automatically
var postgres = builder.AddPostgres("postgres")
    .WithPgAdmin()                           // optional: pgAdmin UI
    .AddDatabase("myapp");

var redis = builder.AddRedis("redis")
    .WithRedisInsight();                     // optional: RedisInsight UI

var rabbitmq = builder.AddRabbitMQ("rabbitmq")
    .WithManagementPlugin();                 // RabbitMQ management UI

// .NET projects — run as processes, not containers
var worker = builder.AddProject<Projects.Worker>("worker")
    .WithReference(postgres)                 // injects connection string
    .WithReference(rabbitmq);               // injects RabbitMQ config

var api = builder.AddProject<Projects.WebApi>("api")
    .WithReference(postgres)
    .WithReference(redis)
    .WithReference(rabbitmq)
    .WithReference(worker);                  // injects worker's URL for service-to-service calls

builder.AddProject<Projects.Blazor>("web")
    .WithReference(api);                     // Blazor knows where the API is

builder.Build().Run();

What "WithReference" Actually Does

This is the part that saves the most time. When you call .WithReference(postgres), Aspire injects a connection string as an environment variable into the target project at runtime:

Without Aspire:
  Developer must manually write:
    "Host=localhost;Port=5432;Database=myapp;Username=postgres;Password=???"
  And update it in every service that uses Postgres.
  And keep it in sync across the team.

With Aspire + WithReference:
  Aspire generates the connection string automatically.
  Injects it as: ConnectionStrings__myapp=Host=localhost;Port=5432;...
  Your service reads it with the standard IConfiguration pattern.
  It's always correct. No manual sync needed.

// WebApi/Program.cs — service doesn't know or care where Postgres lives
// It just reads the connection string Aspire injected
builder.AddNpgsqlDbContext<AppDbContext>("myapp"); // "myapp" matches the database name in AppHost

// Aspire sets this automatically:
// ConnectionStrings__myapp = Host=localhost;Port=65432;Database=myapp;Username=postgres;Password=<generated>
// Port is randomly assigned — no port conflicts between developers

Service Discovery

// Worker needs to call the API. Without Aspire:
// → hardcode "http://localhost:5001" in appsettings
// → breaks when the API moves or the port changes

// With Aspire:
// AppHost: .WithReference(api) injects the API's URL
// Worker/Program.cs:
builder.Services.AddHttpClient<IOrderApiClient, OrderApiClient>(
    static client => client.BaseAddress = new Uri("http://api")); // "api" = the resource name
// Aspire resolves "http://api" to the actual running address at runtime

The Built-In Dashboard

When you run dotnet run in the AppHost project, the Aspire dashboard starts automatically at http://localhost:18888:

┌──────────────────────────────────────────────────────────────────┐
│  Aspire Dashboard                                                │
│                                                                  │
│  Resources tab:                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ Name      Type      State    Endpoints        Logs        │   │
│  │ ─────────────────────────────────────────────────────     │   │
│  │ api       Project   Running  http://+:5001    [view]      │   │
│  │ worker    Project   Running  (none)            [view]     │   │
│  │ web       Project   Running  http://+:5002    [view]      │   │
│  │ postgres  Container Running  localhost:65432   [view]     │   │
│  │ redis     Container Running  localhost:65379   [view]     │   │
│  │ rabbitmq  Container Running  localhost:65672   [view]     │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  Traces tab (OpenTelemetry — built-in):                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ TraceId         Service   Duration   Spans               │   │
│  │ ─────────────────────────────────────────────────────     │   │
│  │ abc123...       api       142ms      5 spans  [view]     │   │
│  │   └─ GET /orders           api        1ms                │   │
│  │      └─ SELECT orders      postgres   38ms               │   │
│  │      └─ GET cache          redis      2ms                │   │
│  │      └─ publish event      rabbitmq   4ms                │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  Logs tab: structured logs from all services, unified           │
│  Metrics tab: request rates, durations, DB pool stats           │
└──────────────────────────────────────────────────────────────────┘

This is OpenTelemetry wired up automatically — distributed traces that show exactly which service called what, how long each leg took, and where slowdowns are. No Jaeger to install. No Prometheus to configure. It's there from day one.

Adding Aspire to an Existing Solution

Bash

# Install the workload
dotnet workload install aspire

# Add the AppHost project to your existing solution
dotnet new aspire-apphost -n AppHost -o src/AppHost
dotnet sln add src/AppHost/AppHost.csproj

# Add the ServiceDefaults project (shared OpenTelemetry config, health checks)
dotnet new aspire-servicedefaults -n ServiceDefaults -o src/ServiceDefaults
dotnet sln add src/ServiceDefaults/ServiceDefaults.csproj

# Reference ServiceDefaults from each service
# Then add one line to each service's Program.cs:
builder.AddServiceDefaults(); // wires up health checks, OpenTelemetry, service discovery

What ServiceDefaults Wires Up Automatically

// ServiceDefaults/Extensions.cs (generated)
public static IHostApplicationBuilder AddServiceDefaults(this IHostApplicationBuilder builder)
{
    builder.ConfigureOpenTelemetry();        // tracing + metrics → Aspire dashboard
    builder.AddDefaultHealthChecks();        // /health and /alive endpoints
    builder.Services.AddServiceDiscovery();  // resolves "http://api" to actual address
    // ...
    return builder;
}

One line in each service. All observability infrastructure configured. No per-service boilerplate.

When .NET Aspire Is Right

✅ Pure .NET stack (Web API + Worker + Blazor + etc.)
✅ 2+ services sharing Postgres, Redis, or a message broker
✅ Fast inner loop matters — dotnet watch works, no Docker rebuild
✅ Want distributed tracing and structured logs without manual setup
✅ Team wants config in C# instead of YAML
✅ Want service discovery without a service mesh

❌ Stack includes non-.NET services (Python, Node, Go)
   (Aspire can run arbitrary containers, but the DX is better for .NET projects)
❌ Need production-like containerized environment locally
   (Aspire runs .NET projects as processes — not the same as running in Docker)
❌ Deploying to a non-Azure environment without a custom manifest adapter

Side-by-Side Comparison

Feature                  Manual Setup    Docker Compose   .NET Aspire
──────────────────────────────────────────────────────────────────────
Config location          Per-service     docker-compose   AppHost C#
                         appsettings     YAML             project

Startup command          5 terminals     docker compose   dotnet run
                                         up               (AppHost)

Service discovery        Manual URLs     Container DNS    WithReference()
                         in appsettings  (service name)   auto-injects

Connection strings       Manually        YAML env vars    Auto-generated
                         maintained      manually         + injected

Inner loop speed         Fast            Slow             Fast
                         (native run)    (Docker build)   (native run)

Polyglot support         N/A             ✅ Any language   .NET-first
                                                          (containers ok)

Built-in observability   None            None             ✅ Dashboard,
                                                          traces, logs,
                                                          metrics

Debugging                Easy            Requires setup   Easy
                         (native)        (VSDBG etc.)     (native)

Production parity        Low             High             Medium
                                                          (.NET as procs)

Onboarding effort        High            Low              Low
                         (README-based)  (one command)    (one command)

Learning curve           None            Docker + YAML    C# + Aspire API

Team size fit            1–2 devs        Any              Any (.NET teams)

The Decision Framework

                    How many services do you have?
                              │
                   ┌──────────┴──────────┐
                  1 API + 1 DB           2+ services
                   │                      │
                   ▼                      ▼
            Manual setup          Is your stack
            (zero overhead)       all .NET?
                                          │
                               ┌──────────┴──────────┐
                              Yes                     No
                               │                      │
                               ▼                      ▼
                     .NET Aspire              Docker Compose

                     Unless:
                     - You need production
                       parity in containers
                     - You're deploying to
                       non-Azure with no
                       Aspire manifest support
                     → then: Docker Compose

In practice:

Single API + DB           → Manual setup
.NET API + Worker + Redis → Aspire
.NET API + Node frontend  → Docker Compose
Full microservices stack  → Docker Compose (or Kubernetes for prod)
.NET services, fast DX    → Aspire (switch to Compose for CI)

Using Both: Aspire for Dev, Compose for CI

A common pattern in mature .NET teams:

Development:  dotnet run (AppHost)
              → Fast inner loop, native debugger, Aspire dashboard
              → .NET code runs as processes, infra as Docker containers

CI/CD:        docker compose up
              → Production-like containers for integration tests
              → Every service in a container, exact deployment environment

Production:   Kubernetes (or Azure Container Apps)
              → Aspire can export a deployment manifest:
                dotnet run --publisher manifest
              → Generates docker-compose.yaml or Azure Container Apps YAML
                from your AppHost C# definitions

Bash

# Generate a deployment manifest from your AppHost
dotnet run --project src/AppHost --publisher manifest --output-path ./manifests

# Output:
# manifests/aspire-manifest.json  → describes all resources and their relationships
# manifests/docker-compose.yaml  → usable for Docker Compose deployments

Getting Started With Aspire

Bash

# Prerequisites
dotnet workload install aspire

# New solution with Aspire from scratch
dotnet new aspire-starter -n MyApp

# Structure created:
# MyApp.AppHost/       ← orchestrator, references all other projects
# MyApp.ServiceDefaults/ ← shared config: OpenTelemetry, health checks
# MyApp.ApiService/    ← sample Web API
# MyApp.Web/           ← sample Blazor frontend

# Run everything
dotnet run --project MyApp.AppHost

# Open dashboard
# http://localhost:18888

// MyApp.AppHost/Program.cs — add Postgres + Redis in 3 lines
var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres").AddDatabase("myappdb");
var redis = builder.AddRedis("cache");

var api = builder.AddProject<Projects.MyApp_ApiService>("api")
    .WithReference(postgres)
    .WithReference(redis);

builder.AddProject<Projects.MyApp_Web>("web")
    .WithReference(api);

builder.Build().Run();

// MyApp.ApiService/Program.cs — two lines wires everything up
var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();                // health checks, OpenTelemetry, service discovery
builder.AddNpgsqlDbContext<AppDbContext>("myappdb"); // Aspire injects the connection string
builder.AddRedisDistributedCache("cache");   // Aspire injects Redis connection

var app = builder.Build();
app.MapDefaultEndpoints();                   // maps /health and /alive
// your routes here...
app.Run();

That's the entire setup. No appsettings.Development.json for Postgres or Redis. No connection string management. No observability wiring. One AppHost project coordinates everything.

Summary

Don't add orchestration overhead until you need it.

A single API with one database doesn't need Docker Compose or Aspire. Adding them to a solo project is complexity without benefit.

When you hit two or more .NET services that share infrastructure — that's when Aspire pays for itself in the first hour. Auto-wired connection strings, built-in distributed tracing, and a unified log stream across every service, all from dotnet run.

When your stack is polyglot, or when production parity in containers is non-negotiable, Docker Compose is the more appropriate tool — language-agnostic, production-faithful, and familiar to any developer who knows Docker.

The orchestration problem is real. Pick the tool that matches the scale of the problem you actually have.

Orchestrating .NET Multi-Service Apps: Manual Setup vs .NET Aspire vs Docker Compose

The Problem Space

Approach 1: Manual Setup

What It Looks Like

The Config Drift Problem

When Manual Setup Is Right

Approach 2: Docker Compose

The docker-compose.yml

What Docker Compose Solves

What Docker Compose Doesn't Solve

The Dockerfile Every .NET Service Needs

When Docker Compose Is Right

Approach 3: .NET Aspire

AppHost: The C# Orchestrator

What "WithReference" Actually Does

Service Discovery

The Built-In Dashboard

Adding Aspire to an Existing Solution

What ServiceDefaults Wires Up Automatically

When .NET Aspire Is Right

Side-by-Side Comparison

The Decision Framework

Using Both: Aspire for Dev, Compose for CI

Getting Started With Aspire

Summary

Enjoyed this article?

Leave a comment