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);

# Install PostgreSQL locally... or use Docker?
docker pull postgres:15
docker run -d --name postgres -e POSTGRES_PASSWORD=secret -p 5432:5432 postgres:15

# Wait, I also need Redis
docker pull redis:7
docker run -d --name redis -p 6379:6379 redis:7

# And RabbitMQ with the management plugin
docker pull rabbitmq:3-management
docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management

// 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

# Install the Aspire project templates
dotnet new install Aspire.ProjectTemplates

# To install a specific version
dotnet new install Aspire.ProjectTemplates::9.4.0

# Create a new Aspire Starter Application
dotnet new aspire-starter -n MyFirstAspireApp

# Navigate to the AppHost project
cd MyFirstAspireApp/MyFirstAspireApp.AppHost

# Run the application
dotnet run

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

// appsettings.json
{ "Services": { "InventoryApi": "http://localhost:5001" } }

// Program.cs
var url = configuration["Services:InventoryApi"];
// Manual configuration for every environment

// 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

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");
    }
}

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. Clone the repository
git clone https://github.com/nitin27may/aspire-Microservices.git
cd aspire-Microservices

# 2. Navigate to AppHost
cd src/ECommerce.AppHost

# 3. Run the application
dotnet run

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