.NET Aspire is an application framework for building observable, production-ready, cloud-native applications with .NET. It provides a consistent way to manage your application's dependencies, configuration, and deployment.

Think of Aspire as a layer that sits on top of your application and orchestrates how everything works together. It handles service discovery, configuration, health checks, and telemetry out of the box.

Starting from version 13, .NET Aspire was rebranded to Aspire and is now a multi-language application platform.

While Aspire continues to provide best-in-class support for .NET applications, version 13.0 brings support for Python and JavaScript. It provides comprehensive support for running, debugging, and deploying applications written in these languages.

Today, I want to show you how to build and run a .NET application with Aspire 13 and .NET 10.

In this post, we will explore:

• Getting Started with Aspire 13
• Configuring PostgreSQL and Redis in Aspire
• Exploring Aspire Dashboard
• Configuring OpenTelemetry
• Deploying Aspire Application to Docker Compose

Let's dive in.

I have built a product API that has the following integrations:

• PostgreSQL database
• HybridCache with Redis

To add Aspire to your project, we need to do the following steps:

Step 1:

Install the Aspire project templates:

bash
1dotnet new install Aspire.ProjectTemplates

Step 2:

Install the Aspire CLI:

bash
1dotnet tool install --global aspire.cli

Step 3:

Add the Aspire support for the Products.Api project in Visual Studio or Rider:

Aspire introduces two new project types to your solution:

• AppHost: The orchestrator that defines your application's architecture and dependencies.
• ServiceDefaults: Shared configuration and observability setup applied to all services.

By default, the AppHost project has the entry file name AppHost.cs with the following content:

csharp
1var builder = DistributedApplication.CreateBuilder(args);
2
3builder
4    .AddProject<Projects.Products_Api>("products-api");
5
6builder.Build().Run();

The only dependency declared in the AppHost project is Products.Api, which contains our Web API.

Step 4:

Install the following NuGet packages in the AppHost project:

bash
1dotnet add package Aspire.Hosting.PostgreSQL
2dotnet add package Aspire.Hosting.Redis

Step 5:

Configure all the dependencies in the AppHost.cs:

csharp
1var builder = DistributedApplication.CreateBuilder(args);
2
3var cache = builder.AddRedis("cache");
4
5var postgres = builder.AddPostgres("postgres");
6
7builder
8    .AddProject<Projects.Products_Api>("products-api")
9    .WithReference(cache)
10    .WithReference(postgres);
11
12builder.Build().Run();

The WithReference(cache) and WithReference(postgres) methods inject connection strings for Redis and PostgreSQL into the API project. Aspire automatically sets environment variables that the API can read to connect to these resources.

Step 6:

Configure the connection strings in the Products.Api project to connect to the PostgreSQL database:

csharp
1using Microsoft.EntityFrameworkCore;
2using Products.Domain.Products;
3using Products.Infrastructure.Database;
4using Products.Infrastructure.Repositories;
5
6namespace Microsoft.Extensions.DependencyInjection;
7
8public static class HostDiExtensions
9{
10    private static IServiceCollection AddEfCore(
11        this IServiceCollection services, 
12        IConfiguration configuration)
13    {
14        var connectionString = configuration.GetConnectionString("postgres");
15
16        services.AddDbContext<ProductDbContext>((_, options) =>
17        {
18            options.UseNpgsql(connectionString);
19        });
20
21        return services;
22    }
23}

The key part is configuration.GetConnectionString("postgres"). This reads the connection string that Aspire injected when we called WithReference(postgres) in AppHost.cs. Aspire automatically sets an environment variable with the PostgreSQL connection string, and the configuration system reads it.

This way, you don't need to hardcode connection strings in appsettings.json or your own environment variables.

In this project, I use the regular EF Core NuGet packages for Npgsql:

• Microsoft.EntityFrameworkCore 10.0.0
• Microsoft.EntityFrameworkCore.Design 10.0.0
• Npgsql.EntityFrameworkCore.PostgreSQL 10.0.0

Step 7:

Configure the connection string in the Products.Api project to connect to the Redis cache:

csharp
1public static IServiceCollection AddWebHostInfrastructure(
2    this IServiceCollection services, 
3    IConfiguration configuration)
4{
5    services.AddHybridCache(options =>
6    {
7        options.DefaultEntryOptions = new HybridCacheEntryOptions
8        {
9            Expiration = TimeSpan.FromMinutes(10),
10            LocalCacheExpiration = TimeSpan.FromMinutes(10)
11        };
12    });
13
14    return services;
15}
16
17private static IServiceCollection AddRedis(
18    this IServiceCollection services, 
19    IConfiguration configuration)
20{
21    var redisConnectionString = configuration.GetConnectionString("cache")!;
22
23    services.AddMemoryCache();
24    
25    services
26        .AddStackExchangeRedisCache(options =>
27        {
28            options.Configuration = redisConnectionString;
29        });
30
31    return services;
32}

The AddHybridCache method registers HybridCache with default expiration settings. The AddRedis method registers StackExchangeRedisCache as the L2 cache.

Just like with PostgreSQL, Aspire injects the Redis connection string via configuration.GetConnectionString("cache").

In this project, I use the following NuGet packages for Redis cache:

• Microsoft.Extensions.Caching.Hybrid 10.1.0
• Microsoft.Extensions.Caching.StackExchangeRedis 10.0.1

Step 8:

Let's run our application locally with Visual Studio or Rider:

Aspire dashboard

The Aspire dashboard opens automatically in your web browser (the port may vary). The dashboard shows:

• Resources - All running services (postgres, cache, products-api)
• Console logs - Real-time logs from each service
• Structured logs - Filterable and searchable logs
• Traces - Distributed traces across services
• Metrics - Performance metrics and health checks

The first run may take a few minutes while Docker pulls the container images. Subsequent runs will be much faster.

The dashboard shows all running services, their health status, logs, and distributed traces.

In Aspire, you can easily configure PostgreSQL and Redis resources with available options.

Redis resource with RedisInsight

csharp
1var cache = builder.AddRedis("cache")
2    .WithRedisInsight();

This declares a Redis resource named "cache". The WithRedisInsight() method adds RedisInsight, a web-based GUI for inspecting Redis data.

When you run the app, Aspire starts a Redis container and a RedisInsight container. You can browse to RedisInsight from the Aspire dashboard to view cached keys and values.

PostgreSQL resource with pgAdmin

csharp
1var postgres = builder.AddPostgres("postgres")
2    .WithPgAdmin()
3    .WithDataVolume(isReadOnly: false);

This declares a PostgreSQL resource named "postgres". The WithPgAdmin() method adds pgAdmin, a web-based database management tool.

The WithDataVolume(isReadOnly: false) method creates a Docker volume to persist database data across container restarts.

We can use pgAdmin to explore the database and run queries:

To access RedisInsight and pgAdmin, you can click on the corresponding links in the Aspire dashboard:

Explore the official documentation for more customization options:

• Aspire.Hosting.PostgreSQL
• Aspire.Hosting.Redis

Here is what the Aspire dashboard looks like after running the application locally:

How Aspire wires everything together

When you run the AppHost, Aspire does the following:

1. Starts the PostgreSQL container and pgAdmin container
2. Starts the Redis container and RedisInsight container
3. Waits for all containers to be healthy
4. Injects connection strings into the Products.Api project via environment variables
5. Starts the Products.Api project
6. Opens the Aspire dashboard in your browser

Here you can manage containers: start, stop, and view their logs.

You can also switch to the Graph view to see the dependencies between services:

On the Console tab you can see the logs from each service. You can view all the console logs or select a specific service to filter them:

On the Structured Logs tab you can filter and search structured logs:

Before we explore the Traces tab, let's configure OpenTelemetry in our solution.

The ServiceDefaults project defines the observability configuration for all services.

This project is automatically added to the Products.Api project when adding the Aspire support for the solution:

csharp
1var builder = WebApplication.CreateBuilder(args);
2
3builder.AddServiceDefaults();

Here is how OpenTelemetry is configured in the ServiceDefaults project:

csharp
1public static TBuilder ConfigureOpenTelemetry<TBuilder>(this TBuilder builder)
2    where TBuilder : IHostApplicationBuilder
3{
4    builder.Logging.AddOpenTelemetry(logging =>
5    {
6        logging.IncludeFormattedMessage = true;
7        logging.IncludeScopes = true;
8    });
9
10    builder.Services.AddOpenTelemetry()
11        .WithMetrics(metrics =>
12        {
13            metrics.AddAspNetCoreInstrumentation()
14                .AddHttpClientInstrumentation()
15                .AddRuntimeInstrumentation();
16        })
17        .WithTracing(tracing =>
18        {
19            tracing.AddSource(builder.Environment.ApplicationName)
20                .AddAspNetCoreInstrumentation()
21                .AddHttpClientInstrumentation();
22        });
23
24    builder.AddOpenTelemetryExporters();
25
26    return builder;
27}

By default, Aspire configures OpenTelemetry to send logs and metrics to the dashboard. But you can configure to send logs and traces to any other destination, such as Jaeger, Seq, Grafana or any other observability tool.

By default, OpenTelemetry is configured with AspNetCore and HttpClient instrumentation.

For our project, we need to add instrumentation for the PostgreSQL and Redis integrations.

We need to install the following NuGet packages:

bash
1dotnet add package Npgsql.OpenTelemetry
2dotnet add package OpenTelemetry.Instrumentation.StackExchangeRedis

Note: OpenTelemetry.Instrumentation.StackExchangeRedis package is still in the preview

Next, we need to register the instrumentation from the installed packages:

csharp
1tracing.AddSource(builder.Environment.ApplicationName)
2    .AddAspNetCoreInstrumentation()
3    .AddHttpClientInstrumentation()
4    .AddNpgsql()
5    .AddRedisInstrumentation();

Here is what the Traces tab looks like in the Aspire dashboard:

What I like about the Aspire is how easy it is to deploy your application to various locations. Let's explore how we can deploy our app to Docker Compose.

First, we need to install the following NuGet package into the AppHost project:

bash
1dotnet add package Aspire.Hosting.Docker

Second, we need to add the following code to the AppHost.cs:

csharp
1builder.AddDockerComposeEnvironment("env");
2
3builder
4    .AddProject<Projects.Products_Api>("products-api")
5    .WithExternalHttpEndpoints()
6    .WithReference(cache)
7    .WithReference(postgres);

AddDockerComposeEnvironment tells Aspire to use a Docker Compose environment named "env".

The WithExternalHttpEndpoints() method makes the API accessible from outside the Aspire environment. This is needed to run the application in Docker from the created Docker Compose file.

With a single Aspire CLI command, we can deploy our application to a Docker Compose YAML file:

bash
1aspire publish -o docker-compose-artifacts

As a result, Aspire will generate two files in the docker-compose-artifacts folder:

• .env - Environment variables for the Docker Compose environment
• docker-compose.yaml - Docker Compose file that defines the services and their dependencies

Here is what the generated docker-compose.yaml file looks like:

yml
1services:
2  env-dashboard:
3    image: "mcr.microsoft.com/dotnet/nightly/aspire-dashboard:latest"
4    expose:
5      - "18888"
6      - "18889"
7    networks:
8      - "aspire"
9    restart: "always"
10  cache:
11    image: "docker.io/library/redis:8.2"
12    command:
13      - "-c"
14      - "redis-server --requirepass $$REDIS_PASSWORD"
15    entrypoint:
16      - "/bin/sh"
17    environment:
18      REDIS_PASSWORD: "${CACHE_PASSWORD}"
19    expose:
20      - "6379"
21    networks:
22      - "aspire"
23  postgres:
24    image: "docker.io/library/postgres:17.6"
25    environment:
26      POSTGRES_HOST_AUTH_METHOD: "scram-sha-256"
27      POSTGRES_INITDB_ARGS: "--auth-host=scram-sha-256 --auth-local=scram-sha-256"
28      POSTGRES_USER: "postgres"
29      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
30    expose:
31      - "5432"
32    volumes:
33      - type: "volume"
34        target: "/var/lib/postgresql/data"
35        source: "dotnetaspire13.apphost-878e181760-postgres-data"
36        read_only: false
37    networks:
38      - "aspire"
39  products-api:
40    image: "${PRODUCTS_API_IMAGE}"
41    environment:
42      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES: "true"
43      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES: "true"
44      OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY: "in_memory"
45      ASPNETCORE_FORWARDEDHEADERS_ENABLED: "true"
46      HTTP_PORTS: "${PRODUCTS_API_PORT}"
47      ConnectionStrings__cache: "cache:6379,password=${CACHE_PASSWORD}"
48      CACHE_HOST: "cache"
49      CACHE_PORT: "6379"
50      CACHE_PASSWORD: "${CACHE_PASSWORD}"
51      CACHE_URI: "redis://:${CACHE_PASSWORD}@cache:6379"
52      ConnectionStrings__postgres: "Host=postgres;Port=5432;Username=postgres;Password=${POSTGRES_PASSWORD}"
53      POSTGRES_HOST: "postgres"
54      POSTGRES_PORT: "5432"
55      POSTGRES_USERNAME: "postgres"
56      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
57      POSTGRES_URI: "postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432"
58      POSTGRES_JDBCCONNECTIONSTRING: "jdbc:postgresql://postgres:5432"
59      OTEL_EXPORTER_OTLP_ENDPOINT: "http://env-dashboard:18889"
60      OTEL_EXPORTER_OTLP_PROTOCOL: "grpc"
61      OTEL_SERVICE_NAME: "products-api"
62    ports:
63      - "${PRODUCTS_API_PORT}"
64    networks:
65      - "aspire"
66networks:
67  aspire:
68    driver: "bridge"
69volumes:
70  dotnetaspire13.apphost-878e181760-postgres-data:
71    driver: "local"

So much work is done for us in a single command. This is really cool!

You can find more information on Aspire apps deployment in the Aspire documentation.

Here are the key benefits of using Aspire:

• Simplified local development: Run all your services, databases, and dependencies with a single command.
• Built-in observability: OpenTelemetry integration for logs, metrics, and traces comes preconfigured.
• Service discovery: Services automatically discover each other without hardcoded URLs.
• Configuration management: Centralized configuration that works locally and in the cloud.
• Easy deployment to Docker Compose and Cloud: Deploy your entire application stack to Docker, Azure or AWS with minimal setup.
• Consistent developer experience: New team members can get the entire application running in minutes.

Aspire 13 makes it easy to deploy your application to Azure. You can use the azd (Azure Developer CLI) tool to provision Azure resources and deploy your app to Azure Container Apps.

Aspire automatically generates the necessary infrastructure-as-code files (Bicep templates) based on your AppHost configuration.

Simply run azd init to initialize the Azure deployment configuration, then azd up to provision resources and deploy your application. Aspire will create Azure Container Apps for your API, Azure Database for PostgreSQL, and Azure Cache for Redis, all wired together with the same connection strings and service discovery you used locally.

If you want to learn more about how to deploy your .NET applications to Azure, I recommend reading this article.

Hope you find this newsletter useful. See you next time.