Aspireify an existing app with a C# AppHost

This guide shows you how to add Aspire orchestration to an existing application while using a C# AppHost (AppHost.cs or apphost.cs). Choose the app stack you're bringing to Aspire, then initialize the AppHost, register your resources, and run everything locally with Aspire.

[!NOTE] Definition Aspireify (verb): To transform an existing application into a distributed, observable, and orchestrated system by adding Aspire—no cape required, just a few commands!

Why add Aspire to an existing app?

As distributed applications grow, coordinating multiple services becomes a tangled web of configuration files, hard-coded URLs, and fragile startup scripts. You're juggling connection strings across environments, manually wiring service dependencies, and struggling to trace issues across your microservices. Development setup becomes a ritual of precision—start the database, then the cache, then service A before service B—and any misstep sends you back to square one.

Aspire cuts through this complexity with a unified orchestration layer that treats your entire application as a cohesive system. Define your services and their relationships once in code (the AppHost), and Aspire handles service discovery, injects configuration automatically, and provides a dashboard with logs, traces, and metrics out of the box. Whether you're orchestrating C#, Python, or JavaScript services—or all three together—you get the same consistent experience from development through deployment.

The best part? You can adopt Aspire incrementally. Start with orchestration, add observability when you're ready, integrate external services as needed. Your existing codebase stays largely unchanged, and you can reverse course if Aspire isn't the right fit.

Prerequisites

Before you begin, ensure you have the following prerequisites installed based on your application's language:

Common requirements

• .NET SDK 10.0 or later — Required for the Aspire AppHost, regardless of your application's language.
• Aspire CLI installed — For orchestration and deployment commands.
• An existing application to add Aspire to.

Language-specific requirements

[!TIP] Multi-language applications If your application uses multiple languages, ensure you have all the relevant prerequisites installed. The Aspire AppHost can orchestrate services across different languages simultaneously.

Overview of the process

Adding Aspire to an existing application follows these key steps:

Initialize Aspire support

The aspire init command is the starting point for adding Aspire to your existing application. This command analyzes your project structure and adds an AppHost that orchestrates your services.

What does aspire init create?

This is your starting point. In the next section, you'll add your applications and configure their relationships.

Add your applications to the AppHost

Once you have an AppHost, you need to register your existing applications. First, install the appropriate hosting packages for your application types, then add your resources to the AppHost.

Install hosting packages

Add C# project references

Model your resources in the AppHost

Connect services

The WithReference calls establish service dependencies and enable service discovery:

When you call WithReference, you're declaring a dependency between resources. Aspire handles the rest—automatically injecting configuration at runtime and during deployment so your services can communicate seamlessly, whether running locally or in production.

Add telemetry configuration (optional)

Add integrations (optional)

Aspire provides integration libraries that simplify working with common services like Redis, PostgreSQL, RabbitMQ, and more. These integrations handle configuration, health checks, and telemetry automatically.

When you add a hosting integration (like Redis) to your AppHost and reference it from a dependent resource, Aspire automatically injects the necessary configuration. This includes connection strings, URLs, environment variables, and other service-specific settings—eliminating manual connection string management across your services.

Run and verify

Now that you've added Aspire to your application, it's time to run it and see the orchestration in action.

Bonus content

If you're currently using Docker Compose to orchestrate your services, Aspire can replace it while providing additional benefits:

Docker Compose approach

services:
   postgres:
      image: postgres:latest
      environment:
         - POSTGRES_PASSWORD=postgres
         - POSTGRES_DB=mydb
      ports:
         - "5432:5432"
  
   api:
      build: ./api
      ports:
         - "8080:8080"
      environment:
         - DATABASE_URL=postgres://postgres:postgres@postgres:5432/mydb
      depends_on:
         - postgres
  
   web:
      build: ./web
      ports:
         - "3000:3000"
      environment:
         - API_URL=http://api:8080
      depends_on:
         - api

Aspire's approach

var builder = DistributedApplication.CreateBuilder(args);
  
var db = builder.AddPostgres("postgres")
    .AddDatabase("mydb");
  
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(db);
  
var web = builder.AddProject<Projects.Web>("web")
    .WithExternalHttpEndpoints()
    .WithReference(api)
    .WaitFor(api);
  
builder.Build().Run();

Key advantages of Aspire over Docker Compose:

• Literally, less verbose — Yet, more expressive and powerful.
• No manual URL configuration — Services discover each other automatically.
• Type-safe references — Compile-time checking for service dependencies.
• Built-in dashboard — Observability without additional tools like Prometheus/Grafana.
• Development and deployment — Same orchestration code works locally and can generate Docker Compose or deploy anywhere.
• Integration libraries — Pre-built support for databases, caches, message queues with best practices.
• Language-agnostic — Works with C#, Python, JavaScript, many more, and containerized services.

Next steps

Congratulations! You've successfully added Aspire to your existing application. Here are some recommended next steps:

• Add more integrations — Explore Aspire integrations to simplify working with databases, caches, and message queues
• Configure observability — Enhance your application's telemetry:
  • Deploy your app — Follow the Deploy your first app tutorial to deploy your Aspire application
• Use the VS Code extension — Run, debug, and manage integrations from within VS Code with the Aspire extension
• Explore the dashboard — Learn more about the Aspire dashboard and its features
• Learn about multi-language features:
  • Python support in Aspire
  • JavaScript support in Aspire