faysilalshareef/aspire-orchestration

Aspire Orchestration — Local Development

Core Principles

• .NET Aspire orchestrates all microservices for local development
• AppHost project defines the service topology
• ServiceDefaults project provides shared configuration (OpenTelemetry, health checks)
• Service discovery replaces hardcoded URLs locally
• Aspire Dashboard provides observability out of the box
• Resource provisioning: SQL Server, Cosmos DB emulator, Service Bus emulator

Key Patterns

AppHost Project

// {Company}.{Domain}.AppHost/Program.cs

var builder = DistributedApplication.CreateBuilder(args);

// Infrastructure resources
var sqlServer = builder.AddSqlServer("sql")
    .WithDataVolume("sql-data");

var commandDb = sqlServer.AddDatabase("command-db");
var queryDb = sqlServer.AddDatabase("query-db");

var serviceBus = builder.AddAzureServiceBus("servicebus")
    .RunAsEmulator();

// Command service
var commandService = builder.AddProject<Projects.{Company}_{Domain}_Command>("command")
    .WithReference(commandDb)
    .WithReference(serviceBus);

// Query service
var queryService = builder.AddProject<Projects.{Company}_{Domain}_Query>("query")
    .WithReference(queryDb)
    .WithReference(serviceBus);

// Processor service
var processor = builder.AddProject<Projects.{Company}_{Domain}_Processor>("processor")
    .WithReference(serviceBus)
    .WithReference(commandService)
    .WithReference(queryService);

// Gateway
var gateway = builder.AddProject<Projects.{Company}_{Domain}_Gateway>("gateway")
    .WithReference(commandService)
    .WithReference(queryService)
    .WithExternalHttpEndpoints();

builder.Build().Run();

Service Defaults Project

// {Company}.{Domain}.ServiceDefaults/Extensions.cs

public static class Extensions
{
    public static IHostApplicationBuilder AddServiceDefaults(
        this IHostApplicationBuilder builder)
    {
        builder.ConfigureOpenTelemetry();
        builder.AddDefaultHealthChecks();
        builder.Services.AddServiceDiscovery();

        builder.Services.ConfigureHttpClientDefaults(http =>
        {
            http.AddStandardResilienceHandler();
            http.AddServiceDiscovery();
        });

        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.AddAspNetCoreInstrumentation()
                    .AddGrpcClientInstrumentation()
                    .AddHttpClientInstrumentation();
            });

        builder.AddOpenTelemetryExporters();
        return builder;
    }

    public static IHostApplicationBuilder AddDefaultHealthChecks(
        this IHostApplicationBuilder builder)
    {
        builder.Services.AddHealthChecks()
            .AddCheck("self", () => HealthCheckResult.Healthy());

        return builder;
    }
}

Using ServiceDefaults in a Service

// Program.cs of any service
var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();

// ... service-specific configuration ...

var app = builder.Build();

app.MapDefaultEndpoints(); // Maps /health/ready and /health/live

Cosmos DB with Aspire

// In AppHost
var cosmos = builder.AddAzureCosmosDB("cosmos")
    .RunAsEmulator();

var cosmosDb = cosmos.AddDatabase("domain-db");

builder.AddProject<Projects.CosmosQuery>("cosmos-query")
    .WithReference(cosmosDb);

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Hardcoded connection strings locally | Use Aspire service discovery | | Running infrastructure manually | Use Aspire to provision resources | | Separate observability setup per service | Use ServiceDefaults project | | Missing health endpoints | Call AddServiceDefaults() + MapDefaultEndpoints() |

Detect Existing Patterns

# Find AppHost project
find . -name "*AppHost*" -type d

# Find ServiceDefaults
find . -name "*ServiceDefaults*" -type d

# Find Aspire references
grep -r "AddServiceDefaults\|DistributedApplication" --include="*.cs" src/

# Find Aspire packages
grep -r "Aspire" --include="*.csproj" src/

Adding to Existing Project

1. Check for existing AppHost project before creating one
2. Reference existing ServiceDefaults project from new services
3. Add new service with AddProject<T> and appropriate references
4. Use Aspire dashboard for local observability and debugging
5. Run emulators for Service Bus and Cosmos DB locally