Building Production-Ready Microservices with .NET Aspire: A Complete E-Commerce Demo

var frontend = builder.AddNpmApp("frontend", "../frontend")
    .WithReference(apiService)
    .WithHttpEndpoint(port: 3000, env: "PORT")
    .WithExternalHttpEndpoints();

var pythonApi = builder.AddPythonApp("analytics", "../analytics-service", "main.py")
    .WithReference(postgres)
    .WithHttpEndpoint(port: 8000);

// appsettings.json - Service A
{
  "ConnectionStrings": {
    "Database": "Host=localhost;Port=5432;Database=serviceA;Username=postgres;Password=secret"
  }
}

// appsettings.json - Service B (copy-paste, change database name)
// appsettings.json - Service C (copy-paste again...)
// appsettings.Development.json - different values
// Environment variables in production - completely different

// How does Service A find Service B?
// Option 1: Hardcode URLs (bad)
var client = new HttpClient { BaseAddress = new Uri("http://localhost:5001") };

// Option 2: Configuration (better, but still manual)
var serviceUrl = configuration["Services:ServiceB:Url"];

// Option 3: Service registry (complex setup required)
// Install Consul, configure agents, write health checks...

// Distributed tracing? That requires:
// - OpenTelemetry SDK in each service
// - Jaeger or Zipkin deployment
// - Correlation ID propagation
// - Custom instrumentation
// - Hours of configuration

using Microsoft.Extensions.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

// ============================================
// INFRASTRUCTURE LAYER
// ============================================

// PostgreSQL with PgAdmin for database management
var postgres = builder.AddPostgres("postgres")
    .WithPgAdmin();  // Adds web-based admin UI automatically!

// Create isolated databases for each service
var catalogDb = postgres.AddDatabase("catalogdb");
var usersDb = postgres.AddDatabase("usersdb");
var ordersDb = postgres.AddDatabase("ordersdb");
var inventoryDb = postgres.AddDatabase("inventorydb");
var notificationsDb = postgres.AddDatabase("notificationsdb");

// Redis with Commander for cache inspection
var redis = builder.AddRedis("redis")
    .WithRedisCommander();  // Visual tool to inspect cache

// RabbitMQ with Management Plugin
var rabbitMq = builder.AddRabbitMQ("rabbitmq")
    .WithManagementPlugin();  // Web UI at port 15672

// ============================================
// MICROSERVICES LAYER
// ============================================

// Product Catalog - needs database and cache
var productCatalogApi = builder.AddProject<Projects.ECommerce_ProductCatalog_Api>("productcatalogapi")
    .WithReference(catalogDb)
    .WithReference(redis)
    .WaitFor(catalogDb)
    .WaitFor(redis);

// User Management - needs database only
var userManagementApi = builder.AddProject<Projects.ECommerce_UserManagement_Api>("usermanagementapi")
    .WithReference(usersDb)
    .WaitFor(usersDb);

// Inventory - needs database, cache, and message queue
var inventoryApi = builder.AddProject<Projects.ECommerce_Inventory_Api>("inventoryapi")
    .WithReference(inventoryDb)
    .WithReference(redis)
    .WithReference(rabbitMq)
    .WaitFor(inventoryDb)
    .WaitFor(redis)
    .WaitFor(rabbitMq);

// Orders - needs database, message queue, and other services
var ordersApi = builder.AddProject<Projects.ECommerce_Orders_Api>("ordersapi")
    .WithReference(ordersDb)
    .WithReference(rabbitMq)
    .WithReference(inventoryApi)      // Service-to-service reference!
    .WithReference(userManagementApi)
    .WithReference(productCatalogApi)
    .WaitFor(ordersDb)
    .WaitFor(rabbitMq);

// Notifications - consumes events from message queue
var notificationsApi = builder.AddProject<Projects.ECommerce_Notifications_Api>("notificationsapi")
    .WithReference(notificationsDb)
    .WithReference(rabbitMq)
    .WithReference(userManagementApi)
    .WaitFor(notificationsDb)
    .WaitFor(rabbitMq);

// ============================================
// PRESENTATION LAYER
// ============================================

// Blazor Web Frontend
builder.AddProject<Projects.ECommerce_Web>("webfrontend")
    .WithExternalHttpEndpoints()  // Expose to browser
    .WithReference(productCatalogApi)
    .WithReference(userManagementApi)
    .WithReference(ordersApi)
    .WithReference(inventoryApi)
    .WaitFor(productCatalogApi)
    .WaitFor(userManagementApi)
    .WaitFor(ordersApi)
    .WaitFor(inventoryApi);

builder.Build().Run();

var postgres = builder.AddPostgres("postgres")
    .WithPgAdmin();

var catalogDb = postgres.AddDatabase("catalogdb");
var usersDb = postgres.AddDatabase("usersdb");

var productCatalogApi = builder.AddProject<Projects.ECommerce_ProductCatalog_Api>("productcatalogapi")
    .WithReference(catalogDb)
    .WithReference(redis);

.WaitFor(catalogDb)
.WaitFor(redis);

.WithPgAdmin()        // Database management
.WithRedisCommander() // Cache inspection
.WithManagementPlugin() // RabbitMQ dashboard

var client = new HttpClient { BaseAddress = new Uri("http://localhost:5001") };
// Breaks in different environments, can't scale

// Requires Consul/Eureka setup, health check configuration,
// service registration code, DNS or client-side discovery...
// Significant infrastructure overhead

// In Program.cs - Register HttpClient with service name
builder.Services.AddHttpClient("inventoryapi", client =>
{
    client.BaseAddress = new Uri("https+http://inventoryapi");
});

// The "inventoryapi" name matches the AppHost registration

builder.AddServiceDefaults();

public static class Extensions
{
    public static IHostApplicationBuilder AddServiceDefaults(this IHostApplicationBuilder builder)
    {
        // Configure OpenTelemetry for tracing and metrics
        builder.ConfigureOpenTelemetry();

        // Add health check endpoints
        builder.AddDefaultHealthChecks();

        // Enable service discovery
        builder.Services.AddServiceDiscovery();

        // Configure HttpClient with resilience and service discovery
        builder.Services.ConfigureHttpClientDefaults(http =>
        {
            http.AddStandardResilienceHandler();  // Retries, circuit breaker
            http.AddServiceDiscovery();            // Resolve service names
        });

        return builder;
    }

    public static IHostApplicationBuilder ConfigureOpenTelemetry(this IHostApplicationBuilder builder)
    {
        builder.Logging.AddOpenTelemetry(logging =>
        {
            logging.IncludeFormattedMessage = true;
            logging.IncludeScopes = true;
        });

        builder.Services.AddOpenTelemetry()
            .WithMetrics(metrics =>
            {
                metrics.AddAspNetCoreInstrumentation()
                    .AddHttpClientInstrumentation()
                    .AddRuntimeInstrumentation();
            })
            .WithTracing(tracing =>
            {
                tracing.AddSource(builder.Environment.ApplicationName)
                    .AddAspNetCoreInstrumentation()
                    .AddHttpClientInstrumentation();
            });

        builder.AddOpenTelemetryExporters();

        return builder;
    }
}

[webfrontend] POST /checkout → 245ms
  └── [ordersapi] POST /api/orders → 180ms
        ├── [inventoryapi] POST /api/inventory/check → 45ms
        │     └── [Redis] GET inventory:product:1 → 2ms
        └── [RabbitMQ] Publish order.created → 5ms
              ├── [inventoryapi] Consume order.created → 30ms
              └── [notificationsapi] Consume order.created → 50ms

sequenceDiagram
    participant Orders as Orders API
    participant MQ as RabbitMQ
    participant Inventory as Inventory API
    participant Notifications as Notifications API

    Orders->>MQ: Publish OrderCreated Event

    par Parallel Processing
        MQ->>Inventory: OrderCreated Event
        Inventory->>Inventory: Deduct Stock
        Inventory->>Inventory: Create Reservation
    and
        MQ->>Notifications: OrderCreated Event
        Notifications->>Notifications: Send Email
    end

public class OrderEventConsumer : BackgroundService
{
    private readonly IServiceProvider _serviceProvider;
    private readonly IConnection _rabbitConnection;  // Injected by Aspire!
    private readonly ILogger<OrderEventConsumer> _logger;

    public OrderEventConsumer(
        IServiceProvider serviceProvider,
        IConnection rabbitConnection,  // Auto-configured connection
        ILogger<OrderEventConsumer> logger)
    {
        _serviceProvider = serviceProvider;
        _rabbitConnection = rabbitConnection;
        _logger = logger;
    }

    protected override Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("OrderEventConsumer starting...");

        var channel = _rabbitConnection.CreateModel();

        // Declare exchange with topic routing
        channel.ExchangeDeclare(
            exchange: "orders.exchange",
            type: ExchangeType.Topic,
            durable: true,
            autoDelete: false);

        // Declare queue for inventory service
        channel.QueueDeclare(
            queue: "orders.inventory",
            durable: true,
            exclusive: false,
            autoDelete: false);

        // Bind queue to exchange with routing key
        channel.QueueBind(
            queue: "orders.inventory",
            exchange: "orders.exchange",
            routingKey: "order.created");

        var consumer = new EventingBasicConsumer(channel);
        consumer.Received += (sender, args) =>
        {
            try
            {
                var body = Encoding.UTF8.GetString(args.Body.ToArray());
                var orderEvent = JsonSerializer.Deserialize<OrderCreatedEvent>(body);

                if (orderEvent != null)
                {
                    _logger.LogInformation("Processing order: {OrderId}", orderEvent.OrderId);

                    // Create scope for scoped services
                    using var scope = _serviceProvider.CreateScope();
                    var inventoryService = scope.ServiceProvider
                        .GetRequiredService<InventoryService>();

                    // Deduct inventory for all items in the order
                    inventoryService.DeductInventoryAsync(
                        orderEvent.OrderId,
                        orderEvent.Items
                    ).GetAwaiter().GetResult();
                }

                // Acknowledge successful processing
                channel.BasicAck(args.DeliveryTag, multiple: false);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error processing order event");
                // Requeue for retry
                channel.BasicNack(args.DeliveryTag, multiple: false, requeue: true);
            }
        };

        channel.BasicConsume(
            queue: "orders.inventory",
            autoAck: false,  // Manual acknowledgment
            consumer: consumer);

        _logger.LogInformation("Waiting for order events...");

        // Keep running until cancellation
        stoppingToken.Register(() =>
        {
            channel.Close();
            channel.Dispose();
        });

        return Task.CompletedTask;
    }
}

// In Program.cs - One line!
builder.AddRabbitMQClient("rabbitmq");

// The IConnection is now available for dependency injection
// Connection string, credentials - all handled automatically

// In ECommerce.Shared.Contracts project
public record OrderCreatedEvent
{
    public Guid OrderId { get; init; }
    public string OrderNumber { get; init; }
    public string UserId { get; init; }
    public decimal TotalAmount { get; init; }
    public List<OrderItemEvent> Items { get; init; }
    public DateTime CreatedAt { get; init; }
}

public record OrderItemEvent
{
    public int ProductId { get; init; }
    public string ProductName { get; init; }
    public int Quantity { get; init; }
    public decimal UnitPrice { get; init; }
}

// In AppHost
var redis = builder.AddRedis("redis")
    .WithRedisCommander();  // Visual inspection tool

// In Product Catalog API
builder.AddRedisClient("redis");

// In Program.cs
builder.AddRedisClient("redis");

// In ProductCatalogService
public class ProductCatalogService
{
    private readonly CatalogDbContext _context;
    private readonly IConnectionMultiplexer _redis;
    private readonly ILogger<ProductCatalogService> _logger;
    private static readonly TimeSpan CacheExpiry = TimeSpan.FromMinutes(5);

    public ProductCatalogService(
        CatalogDbContext context,
        IConnectionMultiplexer redis,  // Injected by Aspire
        ILogger<ProductCatalogService> logger)
    {
        _context = context;
        _redis = redis;
        _logger = logger;
    }

    public async Task<IEnumerable<ProductDto>> GetProductsAsync()
    {
        var cacheKey = "products:all";
        var db = _redis.GetDatabase();

        // 1. Check cache first
        var cached = await db.StringGetAsync(cacheKey);

        if (!cached.IsNullOrEmpty)
        {
            _logger.LogDebug("Cache hit for {CacheKey}", cacheKey);
            return JsonSerializer.Deserialize<IEnumerable<ProductDto>>(cached!);
        }

        // 2. Cache miss - query database
        _logger.LogDebug("Cache miss for {CacheKey}, querying database", cacheKey);

        var products = await _context.Products
            .Include(p => p.Category)
            .Where(p => p.IsActive)
            .Select(p => new ProductDto
            {
                Id = p.Id,
                Name = p.Name,
                Description = p.Description,
                Price = p.Price,
                ImageUrl = p.ImageUrl,
                CategoryName = p.Category.Name
            })
            .ToListAsync();

        // 3. Store in cache for next request
        await db.StringSetAsync(
            cacheKey,
            JsonSerializer.Serialize(products),
            CacheExpiry);

        return products;
    }

    public async Task InvalidateCacheAsync()
    {
        var db = _redis.GetDatabase();
        await db.KeyDeleteAsync("products:all");
        _logger.LogInformation("Product cache invalidated");
    }
}

sequenceDiagram
    actor User
    participant Web as Blazor Web UI
    participant Catalog as Product Catalog API
    participant Users as User Management API
    participant Orders as Orders API
    participant Inventory as Inventory API
    participant Notifications as Notifications API
    participant Cache as Redis Cache
    participant DB as PostgreSQL
    participant MQ as RabbitMQ

    Note over User,MQ: Phase 1: Browse Products
    User->>Web: Browse Products
    Web->>Catalog: GET /api/products
    Catalog->>Cache: Check Cache
    alt Cache Hit
        Cache-->>Catalog: Return Cached Data
    else Cache Miss
        Catalog->>DB: Query catalogdb
        DB-->>Catalog: Product Data
        Catalog->>Cache: Store in Cache
    end
    Catalog-->>Web: Product List
    Web-->>User: Display Products

    Note over User,MQ: Phase 2: User Authentication
    User->>Web: Login
    Web->>Users: POST /api/auth/login
    Users->>DB: Validate Credentials
    DB-->>Users: User Data
    Users-->>Web: JWT Token

    Note over User,MQ: Phase 3: Checkout
    User->>Web: Place Order
    Web->>Inventory: POST /api/inventory/check
    Inventory-->>Web: Stock Available
    Web->>Orders: POST /api/orders (JWT)
    Orders->>DB: Create Order
    Orders->>MQ: Publish OrderCreated

    par Async Processing
        MQ->>Inventory: Deduct Stock
        MQ->>Notifications: Send Email
    end

    Orders-->>Web: Order Confirmation
    Web-->>User: Display Order Number

var postgres = builder.AddPostgres("postgres");

var catalogDb = postgres.AddDatabase("catalogdb");
var usersDb = postgres.AddDatabase("usersdb");
var ordersDb = postgres.AddDatabase("ordersdb");
var inventoryDb = postgres.AddDatabase("inventorydb");
var notificationsDb = postgres.AddDatabase("notificationsdb");

1. Pulling PostgreSQL image...
2. Pulling Redis image...
3. Pulling RabbitMQ image...
4. Starting PostgreSQL container...
5. Creating databases: catalogdb, usersdb, ordersdb, inventorydb, notificationsdb
6. Starting Redis container...
7. Starting RabbitMQ container...
8. Waiting for health checks...
9. Starting productcatalogapi...
10. Starting usermanagementapi...
11. Starting inventoryapi...
12. Starting ordersapi...
13. Starting notificationsapi...
14. Starting webfrontend...
15. Aspire Dashboard available at: https://localhost:17198

// Program.cs - ONE file, ~50 lines total
var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres").WithPgAdmin();
var catalogDb = postgres.AddDatabase("catalogdb");
var redis = builder.AddRedis("redis").WithRedisCommander();
var rabbitMq = builder.AddRabbitMQ("rabbitmq").WithManagementPlugin();

var catalogApi = builder.AddProject<Projects.CatalogApi>("catalogapi")
    .WithReference(catalogDb)
    .WithReference(redis)
    .WaitFor(catalogDb);

// ... other services

builder.Build().Run();

aspire-Microservices/
├── ECommerce.sln                    # Solution file
├── docs/
│   ├── architecture-overview.md     # Architecture diagram
│   ├── data-flow-diagram.md         # Sequence diagrams
│   └── blog-article.md              # This article
└── src/
    ├── ECommerce.AppHost/           # Aspire orchestration
    │   └── Program.cs               # All infrastructure defined here
    ├── ECommerce.ServiceDefaults/   # Shared configuration
    │   └── Extensions.cs            # OpenTelemetry, health checks
    ├── ECommerce.ProductCatalog.Api/ # Products microservice
    ├── ECommerce.UserManagement.Api/ # Users microservice
    ├── ECommerce.Orders.Api/        # Orders microservice
    ├── ECommerce.Inventory.Api/     # Inventory microservice
    ├── ECommerce.Notifications.Api/ # Notifications microservice
    ├── ECommerce.Web/               # Blazor frontend
    └── Shared/
        └── ECommerce.Shared.Contracts/ # Event contracts