aspire-configuration

Aspire の構成

このスキルを使用する場面

次の場合にこのスキルを使用します。

• Aspire ベースのリポジトリで、AppHost のリソースをアプリケーションの構成に接続する
• Aspire の外部でも、本番環境の構成が明確で移植可能であることを確保する
• アプリケーションコードで Aspire クライアント／サービス検出パッケージを使用しないようにする
• アプリケーションコードの処理経路を変えずに、開発／テスト用の機能トグルを設計する

---

基本原則

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

   • Aspire Hosting パッケージを使用するのは AppHost のみにします。
   • アプリケーションプロジェクトから Aspire クライアント／サービス検出パッケージを参照しないでください。

2. 構成は明示的に指定する

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

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

   • AppHost から渡されるすべての値は、Aspire を使わずに環境変数または構成ファイルで設定できる必要があります。
   • 不透明なサービス検出や暗黙的な構成は避けてください。

---

構成の流れ

AppHost resource -> WithEnvironment(...) -> app config keys -> IOptions<T> in app

Aspire リソースを明示的なアプリケーション設定に変換するのは AppHost の役割です。 アプリケーションが 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); // uses explicit options only
});

アプリケーションに Aspire クライアントパッケージ（または AddServiceDiscovery）を追加しないでください。 これらはオーケストレーション上の関心事であり、AppHost にとどめる必要があります。

---

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

トグルは構成に保持し、AppHost とテストフィクスチャを通じて設定します。これにより、開発／テストと本番環境の構成の同等性を維持できます。

// AppHost: disable persistence in tests via config overrides
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> を使用する
• Aspire Hosting パッケージを参照する場所を AppHost のみにする
• 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