.NET Aspire: What is it and how to use it

.NET Aspire is a Microsoft framework designed to simplify the development, local testing, and deployment of cloud-native, distributed applications in the .NET ecosystem. Released in 2023, Aspire acts as an orchestrator across your entire application stack, providing an opinionated, code-first approach to model, develop, and run complex multi-service apps with enhanced productivity and observability.

What is .NET Aspire?

• Cloud-native focused: Aspire is tailored for microservices and distributed systems, helping manage dependencies across services like databases, caches, APIs, and message queues.
• Application Modeling in C#: Rather than using YAML/Docker Compose, Aspire lets you define your entire application topology — services, containers, external dependencies — directly in C# code, making it natural for .NET developers.
• Orchestration & Local Development: Aspire provides a “run mode” which orchestrates your full app stack locally with one command (or F5), including starting containers, databases, caches, and services, mimicking production environments to enable fast iterative development.
• Multi-mode support: It also supports “publish mode” that generates platform-specific deployment artifacts (like Kubernetes YAML, cloud templates) from your app model, allowing reuse of the same definition for local dev and production deployment.
• Extensibility and Integrations: Aspire has NuGet package integrations for services such as Redis, PostgreSQL, Azure services, and Orleans. This provides standardized interfaces, telemetry, health checks, and seamless service discovery.
• Testing support: It can be combined with test frameworks to spin up and tear down entire app stacks for integration testing, improving end-to-end test reliability.

How to Use .NET Aspire

1. Create an AppHost Project:
   You start by adding a special AppHost project to your solution where you model the application composition in C# using the Aspire SDK.Example Program.cs modeling a web API with SQL Server and Redis cache:

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql").AddDatabase("db");
var cache = builder.AddRedis("cache");

builder.AddProject<Projects.WebApi>("api")
    .WithReference(sql).WaitFor(sql)
    .WithReference(cache).WaitFor(cache)
    .WithExternalHttpEndpoints();

await builder.Build().RunAsync();

This code models dependencies and startup order declaratively.

2. Project File Setup:
The .csproj references the Aspire SDK and integration packages:

<Project Sdk="Microsoft.NET.Sdk">
  <Sdk Name="Aspire.AppHost.Sdk" Version="9.2.0" />
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <UserSecretsId>{GUID}</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\WebApi.csproj" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.2.0" />
    <PackageReference Include="Aspire.Hosting.Redis" Version="9.2.0" />
    <PackageReference Include="Aspire.Hosting.SqlServer" Version="9.2.0" />
  </ItemGroup>
</Project>

This project orchestrates the full distributed app locally and for deployment.

3. Running Locally:
Use Visual Studio or the .NET CLI to launch the AppHost. Aspire will start all services (containers, databases, APIs) automatically, enabling debugging across the full stack with minimal setup.

4. Publishing:
You define “publish mode” to convert the C# model into platform-specific artifacts (like Kubernetes YAML or native cloud configs), allowing you to deploy the same app definition to your target environment easily.

5. Extending and Integrating:
You can add new resource types or custom integrations as needed. Aspire supports extensibility for resource transformations, validations, and output customizing, making it adaptable to various infrastructure setups.

Summary

Aspect	Description
Purpose	Framework for building and orchestrating cloud-native, distributed .NET applications
Application Modeling	C# code-first, declarative modeling of services, resources, dependencies
Local Dev	Single-command orchestration of entire multi-project app stack locally
Deployment	Generates deployment artifacts for cloud/container platforms using the same app model
Integrations	NuGet SDKs for common services (Redis, PostgreSQL, Azure etc.) with telemetry and health checks
Testing	Supports spinning up full app stack for integration and functional tests
Extensibility	Supports custom resource types, transformations, and outputs

In essence, .NET Aspire simplifies complex distributed app development by unifying modeling, local orchestration, and deployment workflows within a consistent . NET-native experience. It improves developer productivity by reducing configuration, providing powerful runtime orchestration, and producing production-ready artifacts from a single source of truth—your C# code