What is the AppHost?

Aspire’s AppHost is the code-first place where you declare your application’s services and their relationships. Instead of managing scattered configuration files, you describe the architecture in code. Aspire then handles local orchestration so you can focus on building features.

Select your API platform

C# Python Node.js Go Java

Defining your architecture

Consider a simple three-tier architecture where the front end talks to an API, and the API talks to a database:

architecture-beta

  service db(logos:postgresql)[PostgreSQL]
  service api(logos:dotnet)[API service]
  service frontend(logos:react)[React front end]

  api:R --> L:db
  frontend:R --> L:api

This architecture demonstrates a .NET API connecting to a PostgreSQL database, with a React front end consuming the API. The .NET API uses ASP.NET Core and connects to PostgreSQL using Entity Framework or a connection string. The React front end is built with Vite and communicates with the API over HTTP.

To build this architecture step-by-step, see the Build your first app quickstart.

architecture-beta

  service db(logos:postgresql)[PostgreSQL]
  service api(logos:python)[API service]
  service frontend(logos:react)[React front end]

  api:R --> L:db
  frontend:R --> L:api

This architecture demonstrates a Python API (using FastAPI/Uvicorn) connecting to a PostgreSQL database, with a React front end consuming the API. The Python API uses frameworks like FastAPI or Flask and connects to PostgreSQL using libraries like psycopg2 or SQLAlchemy. The React front end is built with Vite and communicates with the API over HTTP.

To build this architecture step-by-step, see the Build your first app quickstart.

Tip

The Python integration is provided by the CommunityToolkit.Aspire.Hosting.Python.Extensions NuGet package. Learn more in the Python integration documentation.

architecture-beta

  service db(logos:postgresql)[PostgreSQL]
  service api(logos:nodejs-icon)[API service]
  service frontend(logos:react)[React front end]

  api:R --> L:db
  frontend:R --> L:api

This architecture demonstrates a Node.js API connecting to a PostgreSQL database, with a React front end consuming the API. The Node.js API uses frameworks like Express or Fastify and connects to PostgreSQL using libraries like pg or Prisma. The React front end is built with Vite and communicates with the API over HTTP.

Tip

The JavaScript/Node.js integration is provided by the Aspire.Hosting.JavaScript NuGet package. Learn more in the JavaScript integration documentation.

architecture-beta

  service db(logos:postgresql)[PostgreSQL]
  service api(logos:go)[API service]
  service frontend(logos:react)[React front end]

  api:R --> L:db
  frontend:R --> L:api

This architecture demonstrates a Go API connecting to a PostgreSQL database, with a React front end consuming the API. The Go API uses the standard library’s net/http package or frameworks like Gin or Echo and connects to PostgreSQL using libraries like pgx or database/sql. The React front end is built with Vite and communicates with the API over HTTP.

Tip

The Go integration is provided by the CommunityToolkit.Aspire.Hosting.Golang NuGet package. Learn more in the Go integration documentation.

architecture-beta

  service db(logos:postgresql)[PostgreSQL]
  service api(logos:java)[API service]
  service frontend(logos:react)[React front end]

  api:R --> L:db
  frontend:R --> L:api

This architecture demonstrates a Java API (using Spring Boot) connecting to a PostgreSQL database, with a React front end consuming the API. The Java API uses Spring Boot with Spring Data JPA and connects to PostgreSQL using JDBC or Spring Data. The React front end is built with Vite and communicates with the API over HTTP.

Tip

The Java integration is provided by the CommunityToolkit.Aspire.Hosting.Java NuGet package. Learn more in the Java integration documentation.

You can represent that architecture in an AppHost like this:

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddUvicornApp("api", "../api", "main:app")
    .WithUv()
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddNodeApp("api", "../api", "server.js")
    .WithNpm()
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddGolangApp("api", "../api")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddSpringApp("api", "../api", "otel.jar")
    .WithHttpEndpoint(port: 8080)
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

The AppHost models your distributed application declaratively. Each tab above shows the same three-tier architecture—PostgreSQL database, API service, and React front end—but with different API implementations. Switching tabs changes only the API resource type:

Uses AddProject<Projects.Api>() to reference a .NET project.

Uses AddUvicornApp() with WithUv() for ASGI apps like FastAPI.

Uses AddNodeApp() with WithNpm() for Node.js applications.

Uses AddGolangApp() for Go applications.

Uses AddSpringApp() for Spring Boot applications.

In all cases, the PostgreSQL database and React front end remain identical. Aspire’s WithReference() method establishes dependencies between resources, and WaitFor() ensures services start in the correct order.

Aspire presents the same, consistent model regardless of the language or framework used: services, resources, and the connections between them.

Dissecting the AppHost code

Below we highlight the key parts of a typical AppHost to explain what each step does.

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

14 collapsed lines
// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

15 collapsed lines
// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddUvicornApp("api", "../api", "main:app")
    .WithUv()
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

15 collapsed lines
// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddNodeApp("api", "../api", "server.js")
    .WithNpm()
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

15 collapsed lines
// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddGolangApp("api", "../api")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

15 collapsed lines
// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddSpringApp("api", "../api", "otel.jar")
    .WithHttpEndpoint(port: 8080)
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

In the non-collapsed lines you:

1. Create the distributed application builder with DistributedApplication.CreateBuilder(args).
2. Call Build() to materialize the configuration into a runnable AppHost.
3. Call Run() to start orchestration; services launch in dependency order.

The AppHost is the blueprint for your distributed application—Aspire manages the rest.

Adding a PostgreSQL resource

With the builder ready, define resources and services. The snippet below shows how to add a PostgreSQL server and a database:

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

10 collapsed lines
// Add API service and reference the database
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

11 collapsed lines
// Add API service and reference the database
var api = builder.AddUvicornApp("api", "../api", "main:app")
    .WithUv()
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

11 collapsed lines
// Add API service and reference the database
var api = builder.AddNodeApp("api", "../api", "server.js")
    .WithNpm()
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

11 collapsed lines
// Add API service and reference the database
var api = builder.AddGolangApp("api", "../api")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

11 collapsed lines
// Add API service and reference the database
var api = builder.AddSpringApp("api", "../api", "otel.jar")
    .WithHttpEndpoint(port: 8080)
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

How this works:

• AddPostgres("db") registers a PostgreSQL container named db.
  • This returns an IResourceBuilder<PostgresServerResource> so you can chain configuration fluent-style.
• .AddDatabase("appdata") creates a database named appdata on that server.
• .WithDataVolume() provisions a volume so data persists across container restarts.

Learn more about the official PostgreSQL integration.

Adding an API resource and declaring a dependency

Next, register the API service and wire it to the PostgreSQL resource:

AppHost.cs

6 collapsed lines
var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(postgres)
    .WaitFor(postgres);

5 collapsed lines
// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

6 collapsed lines
var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddUvicornApp("api", "../api", "main:app")
    .WithUv()
    .WithReference(postgres)
    .WaitFor(postgres);

5 collapsed lines
// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

6 collapsed lines
var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddNodeApp("api", "../api", "server.js")
    .WithNpm()
    .WithReference(postgres)
    .WaitFor(postgres);

5 collapsed lines
// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

6 collapsed lines
var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddGolangApp("api", "../api")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(postgres)
    .WaitFor(postgres);

5 collapsed lines
// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

6 collapsed lines
var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddSpringApp("api", "../api", "otel.jar")
    .WithHttpEndpoint(port: 8080)
    .WithReference(postgres)
    .WaitFor(postgres);

5 collapsed lines
// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

What this does:

• AddProject<Projects.Api>("api") registers the API project as a service named api.
• WithReference(postgres) injects connection details (host, port, credentials, connection string) into the API configuration.
• WaitFor(postgres) delays the API startup until PostgreSQL is healthy, avoiding brittle startup timing issues.

• AddUvicornApp("api", "../api", "main:app") registers a Uvicorn-based Python app as a service named api, pointing to the main:app entry point.
• WithUv() configures the app to use the uv package manager for dependency installation.
• WithReference(postgres) injects connection details into the API configuration.
• WaitFor(postgres) delays the API startup until PostgreSQL is healthy.

• AddNodeApp("api", "../api", "server.js") registers a Node.js app as a service named api, with server.js as the entry point.
• WithNpm() configures the app to use npm for dependency installation.
• WithReference(postgres) injects connection details into the API configuration.
• WaitFor(postgres) delays the API startup until PostgreSQL is healthy.

• AddGolangApp("api", "../api") registers a Go app as a service named api.
• WithHttpEndpoint(env: "PORT") configures the port and sets the PORT environment variable.
• WithReference(postgres) injects connection details into the API configuration.
• WaitFor(postgres) delays the API startup until PostgreSQL is healthy.

• AddSpringApp("api", "../api", "../agents/opentelemetry-javaagent.jar") registers a Spring Boot app as a service named api, specifying the OpenTelemetry agent path.
• WithHttpEndpoint(port: 8080) exposes the Spring Boot app on port 8080.
• WithReference(postgres) injects connection details into the API configuration.
• WaitFor(postgres) delays the API startup until PostgreSQL is healthy.

Now that the api service is defined, you can attach the front end.

Adding a front end resource

Register the front end project, declare its dependency on the API, and let the AppHost provide the API address automatically.

Note

This example uses a Node.js (React) front end, but Aspire treats front ends as executable services—any language or framework works.

AppHost.cs

11 collapsed lines
var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

12 collapsed lines
var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddUvicornApp("api", "../api", "main:app")
    .WithUv()
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

12 collapsed lines
var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddNodeApp("api", "../api", "server.js")
    .WithNpm()
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

12 collapsed lines
var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddGolangApp("api", "../api")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

AppHost.cs

12 collapsed lines
var builder = DistributedApplication.CreateBuilder(args);

// Add database resource
var postgres = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// Add API service and reference the database
var api = builder.AddSpringApp("api", "../api", "otel.jar")
    .WithHttpEndpoint(port: 8080)
    .WithReference(postgres)
    .WaitFor(postgres);

// Add frontend service and reference the API
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

Key points:

• .AddViteApp("front end", "../frontend") registers the (Vite-based) front end project as a service named front end.
• .WithHttpEndpoint(env: "PORT", targetPort: 3000) exposes the app on port 3000; the PORT environment variable can override it.
• .WithReference(api) injects the API base address into the front end configuration.

In short: define the backend first (DB → API), then point the UI at the API. The AppHost captures the dependency graph, connection flows, and startup order.

Configuration and networking

These dependencies and connections are automatically managed by Aspire. The AppHost generates configuration values like connection strings and endpoints, injecting them into services as needed. in the AppHost when you add resources, you name them (e.g., db, api, front end); Aspire uses these names for DNS resolution, so services can communicate using predictable addresses. Consuming services also rely on these names for configuration injection.

architecture-beta

  service db(logos:postgresql)[pg]
  service epr(iconoir:server-connection)[Endpoint Reference]
  service api(logos:dotnet)[api]
  service ctr(iconoir:server-connection)[Connection String Reference]
  service frontend(logos:react)[front end]

  db:L <-- R:ctr
  ctr:L <-- R:api
  api:L <-- R:epr
  epr:L <-- R:frontend

The .NET API receives a ConnectionStringReference from PostgreSQL and publishes an EndpointReference that the React front end consumes. This creates a clear dependency chain: PostgreSQL → .NET API → React front end.

architecture-beta

  service db(logos:postgresql)[pg]
  service epr(iconoir:server-connection)[Endpoint Reference]
  service api(logos:python)[api]
  service ctr(iconoir:server-connection)[Connection String Reference]
  service frontend(logos:react)[front end]

  db:L <-- R:ctr
  ctr:L <-- R:api
  api:L <-- R:epr
  epr:L <-- R:frontend

The Python API receives a ConnectionStringReference from PostgreSQL and publishes an EndpointReference that the React front end consumes. This creates a clear dependency chain: PostgreSQL → Python API → React front end.

architecture-beta

  service db(logos:postgresql)[pg]
  service epr(iconoir:server-connection)[Endpoint Reference]
  service api(logos:nodejs-icon)[api]
  service ctr(iconoir:server-connection)[Connection String Reference]
  service frontend(logos:react)[front end]

  db:L <-- R:ctr
  ctr:L <-- R:api
  api:L <-- R:epr
  epr:L <-- R:frontend

The Node.js API receives a ConnectionStringReference from PostgreSQL and publishes an EndpointReference that the React front end consumes. This creates a clear dependency chain: PostgreSQL → Node.js API → React front end.

architecture-beta

  service db(logos:postgresql)[pg]
  service epr(iconoir:server-connection)[Endpoint Reference]
  service api(logos:go)[api]
  service ctr(iconoir:server-connection)[Connection String Reference]
  service frontend(logos:react)[front end]

  db:L <-- R:ctr
  ctr:L <-- R:api
  api:L <-- R:epr
  epr:L <-- R:frontend

The Go API receives a ConnectionStringReference from PostgreSQL and publishes an EndpointReference that the React front end consumes. This creates a clear dependency chain: PostgreSQL → Go API → React front end.

architecture-beta

  service db(logos:postgresql)[pg]
  service epr(iconoir:server-connection)[Endpoint Reference]
  service api(logos:java)[api]
  service ctr(iconoir:server-connection)[Connection String Reference]
  service frontend(logos:react)[front end]

  db:L <-- R:ctr
  ctr:L <-- R:api
  api:L <-- R:epr
  epr:L <-- R:frontend

The Java API receives a ConnectionStringReference from PostgreSQL and publishes an EndpointReference that the React front end consumes. This creates a clear dependency chain: PostgreSQL → Java API → React front end.

How these resources communicate

1. pg publishes a ConnectionStringReference (host, port, database, user, password)—a strongly typed bundle Aspire understands.
2. api declares a dependency on that reference; Aspire injects the connection string into its config with a unique configuration-flow process that injects settings values, including secrets, parameters, and connection strings for both local runs and deployments.
3. api then publishes an EndpointReference (its base URL) after its HTTP endpoint is allocated.
4. front end depends on that endpoint; Aspire injects the API base URL so no hard-coded addresses are needed.

Tip

Aspire replaces ad-hoc run scripts, scattered environment variables, and fragile copy-pasted connection strings with a single, declarative source of truth. By modeling services, resources, and their dependencies in code, it delivers typed configuration (endpoints, credentials, connection strings) directly where needed—reducing setup drift, accelerating onboarding, and letting you evolve the architecture without rewriting glue.

How the AppHost works

When you run the AppHost, Aspire performs these core responsibilities:

1. Service discovery: Aspire discovers services and resources declared in the AppHost.
2. Dependency resolution: Services start in the correct order based on declared dependencies.
3. Configuration injection: Connection strings, endpoints, and other config values are injected automatically.
4. Health monitoring: Aspire observes service health and can restart services when necessary.

Dive deeper into Aspire’s orchestration and the Resource model.

AppHost structure

The template AppHost is structured in the following ways:

File-based AppHost

• DirectoryAspireApp.AppHost

  • apphost.cs dev-time orchestrator
  • apphost.run.json

Project-based AppHost

• DirectoryAspireApp.AppHost

  • DirectoryProperties

    • launchSettings.json
  • appsettings.Development.json
  • appsettings.json
  • AspireApp.AppHost.csproj
  • AppHost.cs dev-time orchestrator

AppHost lifecycle events

You can hook into lifecycle events to run custom logic during startup and resource allocation.

1. BeforeStartEvent: Raised before the AppHost begins starting services.
2. AfterEndpointsAllocatedEvent: Raised after endpoints are allocated for services.
3. AfterResourcesCreatedEvent: Raised after all resources are created.

For finer-grained lifecycle control, see the well-known lifecycle events.

Best practices

• Keep the AppHost minimal to start; add complexity only as required.
• Define explicit dependencies with .WithReference(...) to make wiring obvious.
• Use separate configurations for development, testing, and production.
• Pick clear, descriptive names for resources to make debugging and logging easier.