.NET Aspire の深層 — クラウドネイティブアプリケーション開発の裏側を徹底解剖

// AppHost の Program.cs
var builder = DistributedApplication.CreateBuilder(args);
 
// リソースの追加
var cache = builder.AddRedis("cache");
var postgres = builder.AddPostgres("pg")
    .AddDatabase("catalogdb");
var rabbit = builder.AddRabbitMQ("messaging");
 
// プロジェクトリソースとその依存関係
var catalogApi = builder.AddProject<Projects.CatalogApi>("catalog-api")
    .WithReference(postgres)
    .WithReference(cache);
 
var orderProcessor = builder.AddProject<Projects.OrderProcessor>("order-processor")
    .WithReference(rabbit)
    .WithReference(postgres);
 
var webFrontend = builder.AddProject<Projects.WebFrontend>("web-frontend")
    .WithReference(catalogApi)
    .WithReference(cache)
    .WithExternalHttpEndpoints();
 
builder.Build().Run();

<ProjectReference Include="..\CatalogApi\CatalogApi.csproj" />

namespace Projects;
 
// ビルド時に自動生成される（手書きではない）
public class CatalogApi : IProjectMetadata
{
    public string ProjectPath => @"C:\src\CatalogApi\CatalogApi.csproj";
}

public static IResourceBuilder<ProjectResource> AddProject<TProject>(
    this IDistributedApplicationBuilder builder,
    string name)
    where TProject : IProjectMetadata, new()

// IResource の定義
public interface IResource
{
    string Name { get; }
    ResourceAnnotationCollection Annotations { get; }
}
 
// ContainerResource の例
public class RedisResource : ContainerResource, IResourceWithConnectionString
{
    public RedisResource(string name) : base(name) { }
 
    public ReferenceExpression ConnectionStringExpression =>
        ReferenceExpression.Create(
            $"{PrimaryEndpoint.Property(EndpointProperty.Host)}:{PrimaryEndpoint.Property(EndpointProperty.Port)}");
}

// アノテーションの例
public record EndpointAnnotation(
    string Name,
    string? Transport = null,
    string? Scheme = null,
    int? Port = null,
    int? TargetPort = null,
    bool IsExternal = false,
    bool IsProxied = true) : IResourceAnnotation;
 
public record EnvironmentCallbackAnnotation(
    Func<EnvironmentCallbackContext, Task> Callback)
    : IResourceAnnotation;
 
// WithReference() が内部で行っていること
public static IResourceBuilder<T> WithReference<T>(
    this IResourceBuilder<T> builder,
    IResourceBuilder<IResourceWithConnectionString> source)
    where T : IResourceWithEnvironment
{
    // 環境変数コールバックアノテーションを追加
    return builder.WithEnvironment(context =>
    {
        var connectionString = source.Resource
            .ConnectionStringExpression;
        context.EnvironmentVariables[$"ConnectionStrings__{source.Resource.Name}"]
            = connectionString;
    });
}

// WaitFor() による明示的な起動順序制御
var postgres = builder.AddPostgres("pg")
    .AddDatabase("catalogdb");
 
var migration = builder.AddProject<Projects.DbMigration>("migration")
    .WithReference(postgres)
    .WaitFor(postgres); // PostgreSQL の準備完了を待つ
 
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(postgres)
    .WaitFor(migration); // マイグレーション完了を待つ

// この宣言から...
var cache = builder.AddRedis("cache");
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(cache);
 
// 以下のような環境変数が api プロセスに注入される:
// ConnectionStrings__cache = "localhost:63241"

// サービスディスカバリの使用例（ServiceDefaults プロジェクト）
builder.Services.AddServiceDiscovery();
builder.Services.ConfigureHttpClientDefaults(http =>
{
    http.AddServiceDiscovery(); // すべての HttpClient にサービスディスカバリを適用
});
 
// 利用側：論理名でリクエスト
app.MapGet("/products", async (HttpClient client) =>
{
    // "https://catalog-api" は実際のエンドポイントに解決される
    var products = await client.GetFromJsonAsync<Product[]>(
        "https://catalog-api/api/products");
    return products;
});

// Aspire が注入する環境変数の実際の値
// services__catalog-api__https__0 = "https://localhost:7234"
// services__catalog-api__http__0 = "http://localhost:5234"
 
// これが ServiceDiscovery によって解決される:
// "https://catalog-api" → "https://localhost:7234"

// レプリカを設定
var api = builder.AddProject<Projects.Api>("api")
    .WithReplicas(3); // 3インスタンス起動
 
// ServiceDiscovery は Round-robin で各インスタンスに分散
// services__api__https__0 = "https://localhost:7234"
// services__api__https__1 = "https://localhost:7235"
// services__api__https__2 = "https://localhost:7236"

// AddRedisClient() の内部実装（簡略化）
public static void AddRedisClient(
    this IHostApplicationBuilder builder,
    string connectionName,
    Action<AspireRedisSettings>? configureSettings = null)
{
    // 1. 設定のバインド
    var settings = new AspireRedisSettings();
    builder.Configuration
        .GetSection($"Aspire:StackExchange:Redis:{connectionName}")
        .Bind(settings);
    configureSettings?.Invoke(settings);
 
    // 2. 接続文字列の取得
    var connectionString = settings.ConnectionString
        ?? builder.Configuration.GetConnectionString(connectionName);
 
    // 3. IConnectionMultiplexer の登録
    builder.Services.AddSingleton<IConnectionMultiplexer>(sp =>
    {
        var options = ConfigurationOptions.Parse(connectionString!);
        return ConnectionMultiplexer.Connect(options);
    });
 
    // 4. ヘルスチェックの登録
    if (!settings.DisableHealthChecks)
    {
        builder.Services.AddHealthChecks()
            .AddRedis(connectionString!,
                name: $"Redis_{connectionName}",
                tags: ["ready"]);
    }
 
    // 5. テレメトリの設定
    if (!settings.DisableTracing)
    {
        builder.Services.AddOpenTelemetry()
            .WithTracing(tracing =>
                tracing.AddRedisInstrumentation());
    }
}

// ServiceDefaults/Extensions.cs の全体構造
public static IHostApplicationBuilder AddServiceDefaults(
    this IHostApplicationBuilder builder)
{
    // 1. OpenTelemetry の構成
    builder.ConfigureOpenTelemetry();
 
    // 2. ヘルスチェックエンドポイントの追加
    builder.AddDefaultHealthChecks();
 
    // 3. サービスディスカバリの登録
    builder.Services.AddServiceDiscovery();
 
    // 4. HttpClient のデフォルト設定
    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()  // HTTP メトリクス
                   .AddHttpClientInstrumentation()   // HttpClient メトリクス
                   .AddRuntimeInstrumentation();     // .NET ランタイムメトリクス
        })
        .WithTracing(tracing =>
        {
            tracing.AddAspNetCoreInstrumentation()   // HTTP トレース
                   .AddGrpcClientInstrumentation()    // gRPC トレース
                   .AddHttpClientInstrumentation();   // HttpClient トレース
        });
 
    // OTLP エクスポーターの構成
    builder.AddOpenTelemetryExporters();
 
    return builder;
}
 
private static IHostApplicationBuilder AddOpenTelemetryExporters(
    this IHostApplicationBuilder builder)
{
    // OTEL_EXPORTER_OTLP_ENDPOINT が設定されていれば OTLP エクスポーターを使用
    // Aspire Dashboard が自動的にこの環境変数を設定する
    var otlpEndpoint = builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"];
    if (!string.IsNullOrWhiteSpace(otlpEndpoint))
    {
        builder.Services.AddOpenTelemetry()
            .UseOtlpExporter(); // gRPC over HTTP/2 で Dashboard に送信
    }
 
    return builder;
}

docker run --rm -it -d \
  -p 18888:18888 \
  -p 4317:18889 \
  -p 4318:18890 \
  --name aspire-dashboard \
  mcr.microsoft.com/dotnet/aspire-dashboard:9.0

// ServiceDefaults で設定されるヘルスチェック
public static IHostApplicationBuilder AddDefaultHealthChecks(
    this IHostApplicationBuilder builder)
{
    builder.Services.AddHealthChecks()
        // Liveness: アプリケーションプロセスが応答するか
        .AddCheck("self", () => HealthCheckResult.Healthy(),
            tags: ["live"]);
 
    return builder;
}
 
public static WebApplication MapDefaultEndpoints(
    this WebApplication app)
{
    // Readiness endpoint: すべてのヘルスチェックを評価
    app.MapHealthChecks("/health");
 
    // Liveness endpoint: "live" タグのチェックのみ
    app.MapHealthChecks("/alive", new()
    {
        Predicate = r => r.Tags.Contains("live")
    });
 
    return app;
}

// カスタマイズ例
builder.Services.ConfigureHttpClientDefaults(http =>
{
    http.AddStandardResilienceHandler(options =>
    {
        options.Retry.MaxRetryAttempts = 5;
        options.Retry.BackoffType = DelayBackoffType.Exponential;
        options.Retry.Delay = TimeSpan.FromMilliseconds(500);
 
        options.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(60);
        options.CircuitBreaker.FailureRatio = 0.2;
 
        options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(60);
    });
});

# マニフェストの生成
dotnet run --project AppHost -- --publisher manifest --output-path manifest.json

{
  "resources": {
    "cache": {
      "type": "container.v0",
      "connectionString": "{cache.bindings.tcp.host}:{cache.bindings.tcp.port}",
      "image": "docker.io/library/redis:7.4",
      "bindings": {
        "tcp": {
          "scheme": "tcp",
          "protocol": "tcp",
          "transport": "tcp",
          "targetPort": 6379
        }
      }
    },
    "catalog-api": {
      "type": "project.v0",
      "path": "../CatalogApi/CatalogApi.csproj",
      "env": {
        "ConnectionStrings__cache": "{cache.connectionString}"
      },
      "bindings": {
        "http": { "scheme": "http", "protocol": "tcp", "transport": "http" },
        "https": { "scheme": "https", "protocol": "tcp", "transport": "http" }
      }
    }
  }
}

// 1. リソースクラスの定義
public class MailDevResource : ContainerResource, IResourceWithConnectionString
{
    public MailDevResource(string name) : base(name) { }
 
    // SMTP エンドポイント
    private EndpointReference? _smtpEndpoint;
    public EndpointReference SmtpEndpoint =>
        _smtpEndpoint ??= new(this, "smtp");
 
    // Web UI エンドポイント
    private EndpointReference? _httpEndpoint;
    public EndpointReference HttpEndpoint =>
        _httpEndpoint ??= new(this, "http");
 
    // 接続文字列の式
    public ReferenceExpression ConnectionStringExpression =>
        ReferenceExpression.Create(
            $"smtp://{SmtpEndpoint.Property(EndpointProperty.Host)}:{SmtpEndpoint.Property(EndpointProperty.Port)}");
}
 
// 2. ビルダー拡張メソッドの定義
public static class MailDevResourceExtensions
{
    public static IResourceBuilder<MailDevResource> AddMailDev(
        this IDistributedApplicationBuilder builder,
        string name,
        int? smtpPort = null,
        int? httpPort = null)
    {
        return builder.AddResource(new MailDevResource(name))
            .WithImage("maildev/maildev", "2.1.0")
            .WithHttpEndpoint(
                port: httpPort,
                targetPort: 1080,
                name: "http")
            .WithEndpoint(
                port: smtpPort,
                targetPort: 1025,
                name: "smtp",
                scheme: "tcp")
            .WithHealthCheck("smtp"); // ヘルスチェックの追加
    }
}
 
// 3. AppHost での使用
var maildev = builder.AddMailDev("mail");
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(maildev); // ConnectionStrings__mail が注入される

// IDistributedApplicationLifecycleHook でリソースライフサイクルに介入
public class DatabaseSeederHook : IDistributedApplicationLifecycleHook
{
    public async Task AfterResourcesCreatedAsync(
        DistributedApplicationModel appModel,
        CancellationToken cancellationToken)
    {
        // 全リソース起動後に実行
        var dbResource = appModel.Resources
            .OfType<PostgresDatabaseResource>()
            .FirstOrDefault();
 
        if (dbResource != null)
        {
            // シードデータの投入 etc.
        }
    }
}
 
// 登録
builder.Services
    .AddLifecycleHook<DatabaseSeederHook>();

public class AppHostTests
{
    [Fact]
    public async Task CatalogApiReturnsProducts()
    {
        // AppHost 全体を起動
        var appHost = await DistributedApplicationTestingBuilder
            .CreateAsync<Projects.AppHost>();
 
        await using var app = await appHost.BuildAsync();
        await app.StartAsync();
 
        // catalog-api の HttpClient を取得
        var httpClient = app.CreateHttpClient("catalog-api");
 
        // API にリクエスト
        var response = await httpClient.GetAsync("/api/products");
        response.EnsureSuccessStatusCode();
 
        var products = await response.Content
            .ReadFromJsonAsync<List<Product>>();
        Assert.NotEmpty(products);
    }
 
    [Fact]
    public async Task WebFrontendIsHealthy()
    {
        var appHost = await DistributedApplicationTestingBuilder
            .CreateAsync<Projects.AppHost>();
 
        await using var app = await appHost.BuildAsync();
        await app.StartAsync();
 
        // ヘルスチェックエンドポイントを確認
        var httpClient = app.CreateHttpClient("web-frontend");
        var response = await httpClient.GetAsync("/health");
        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
    }
}

var appHost = await DistributedApplicationTestingBuilder
    .CreateAsync<Projects.AppHost>(args =>
    {
        // テスト用の設定を上書き
        args.Configuration["Parameters:pgPassword"] = "test-password";
    });
 
// テスト用の HttpClient 設定
appHost.Services.ConfigureHttpClientDefaults(http =>
{
    http.AddStandardResilienceHandler();
});

// リソースイベントの購読
var cache = builder.AddRedis("cache");
 
builder.Eventing.Subscribe<ResourceReadyEvent>(
    cache.Resource,
    async (evt, ct) =>
    {
        // Redis が起動完了した時に実行
        Console.WriteLine($"{evt.Resource.Name} is ready!");
    });
 
builder.Eventing.Subscribe<BeforeResourceStartedEvent>(
    cache.Resource,
    async (evt, ct) =>
    {
        // Redis が起動する前に実行
        Console.WriteLine($"{evt.Resource.Name} is about to start");
    });

// コンテナの永続化（再起動しても維持）
var postgres = builder.AddPostgres("pg")
    .WithLifetime(ContainerLifetime.Persistent) // デフォルトは Session
    .AddDatabase("catalogdb");
 
// Session: AppHost 停止時にコンテナも停止
// Persistent: AppHost 停止後もコンテナが残る（高速な再起動）