aspire-configuration

Aspire Configuration

このスキルを使用するタイミング

以下の場合にこのスキルを使用します：

• Aspire ベースのリポジトリで AppHost リソースをアプリケーション構成に配線する場合
• 本番環境の構成を透過的かつ Aspire の外部に移植可能にしたい場合
• アプリケーションコード内で Aspire クライアント/サービスディスカバリパッケージを避けたい場合
• アプリケーションのコードパスを変更せずに開発/テスト用の機能トグルを設計する場合

---

基本原則

1. AppHost が Aspire インフラストラクチャパッケージを管理する

   • Aspire ホスティングパッケージは AppHost のみに属します。
   • アプリケーションプロジェクトは Aspire クライアントやサービスディスカバリパッケージを参照すべきではありません。

2. 明示的な構成のみを使用する

   • AppHost はリソースの出力を明示的な構成キー (環境変数) に変換する必要があります。
   • アプリケーションコードは IOptions<T> または Configuration にのみバインドします。

3. 本番環境との同等性と透過性を確保する

   • AppHost によって注入されるすべての値は、Aspire なしで本番環境の環境変数または設定ファイルとして表現可能である必要があります。
   • 不透明なサービスディスカバリや暗黙的な構成は避けてください。

---

構成フロー

AppHost リソース -> WithEnvironment(...) -> アプリ構成キー -> アプリの IOptions<T>

AppHost は Aspire リソースを明示的なアプリ設定に変換する責任を持ちます。 アプリケーションは Aspire クライアントやサービスディスカバリを直接使用することはありません。

---

AppHost のパターン (明示的なマッピング)

例: データベース + Blob ストレージ

// AppHost/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var db = postgres.AddDatabase("appdb");

var minio = builder.AddContainer("minio", "minio/minio")
    .WithArgs("server", "/data")
    .WithHttpEndpoint(targetPort: 9000, name: "http")
    .WithHttpEndpoint(targetPort: 9001, name: "console")
    .WithEnvironment("MINIO_ROOT_USER", "minioadmin")
    .WithEnvironment("MINIO_ROOT_PASSWORD", "minioadmin");

var api = builder.AddProject<Projects.MyApp_Api>("api")
    .WithReference(db, "Postgres")
    .WithEnvironment("BlobStorage__Enabled", "true")
    .WithEnvironment("BlobStorage__ServiceUrl", minio.GetEndpoint("http"))
    .WithEnvironment("BlobStorage__AccessKey", "minioadmin")
    .WithEnvironment("BlobStorage__SecretKey", "minioadmin")
    .WithEnvironment("BlobStorage__Bucket", "attachments")
    .WithEnvironment("BlobStorage__ForcePathStyle", "true");

builder.Build().Run();

重要なポイント

• WithReference(db, "Postgres") は ConnectionStrings__Postgres を明示的に設定します。
• すべての外部依存関係は明示的な構成キーを介して表現されます。
• API プロジェクトは Configuration 値のみを読み取ります。

---

アプリケーションコードのパターン (Aspire クライアントなし)

アプリケーションコードはオプションにバインドし、SDK を直接初期化します。Aspire クライアントパッケージやサービスディスカバリに依存してはいけません。

// Api/Program.cs
builder.Services
    .AddOptions<BlobStorageOptions>()
    .BindConfiguration("BlobStorage")
    .ValidateDataAnnotations()
    .ValidateOnStart();

builder.Services.AddSingleton<IBlobStorageService>(sp =>
{
    var options = sp.GetRequiredService<IOptions<BlobStorageOptions>>().Value;
    return new S3BlobStorageService(options); // 明示的なオプションのみを使用
});

Aspire クライアントパッケージ (または AddServiceDiscovery) をアプリに追加しないでください。 これらはオーケストレーションの関心事であり、AppHost に留めるべきです。

---

機能トグルとテストオーバーライド

トグルは設定に保持し、AppHost とテストフィクスチャを介して駆動します。これにより、開発/テスト環境と本番環境の設定にパリティが維持されます。

// AppHost: テストでは設定オーバーライドを使用して永続化を無効にする
var config = builder.Configuration.GetSection("App")
    .Get<AppHostConfiguration>() ?? new AppHostConfiguration();

if (!config.UseVolumes)
{
    postgres.WithDataVolume(false);
}

api.WithEnvironment("BlobStorage__Enabled", config.EnableBlobStorage.ToString());

構成オーバーライドを DistributedApplicationTestingBuilder に渡すパターンについては、skills/aspire/integration-testing/SKILL.md を参照してください。

---

すべきこと / してはいけないこと チェックリスト

すべきこと

• すべての Aspire リソースの出力を明示的な構成キーにマッピングする
• すべてのインフラストラクチャ設定に検証付きの IOptions<T> を使用する
• AppHost を Aspire ホスティングパッケージを参照する唯一の場所にする
• AppHost が注入するすべての値が本番環境の環境変数で設定可能であることを確認する

してはいけないこと

• アプリケーションプロジェクトで Aspire クライアントやサービスディスカバリパッケージを参照する
• 本番環境でミラーリングできない不透明なサービスディスカバリに依存する
• 構成を Aspire 限定の抽象化の背後に隠す

---

関連スキル

• skills/aspire/service-defaults/SKILL.md
• skills/aspire/integration-testing/SKILL.md
• skills/akka/aspire-configuration/SKILL.md

---

リソース

• Aspire AppHost 環境構成: https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/app-host
• .NET の構成: https://learn.microsoft.com/en-us/dotnet/core/extensions/configuration