aspire-configuration

用途

Aspire Configuration 用于在基于 Aspire 的仓库中，把 AppHost 资源与应用程序配置连接起来。它适用于以下场景：

在 Aspire 仓库中把 AppHost 资源接入应用配置
确保生产配置透明，并且脱离 Aspire 也能移植
避免在应用代码中引入 Aspire 客户端/服务发现包
为开发/测试设计特性开关，而不改变应用代码路径

核心原则

AppHost 独占 Aspire 基础设施包

Aspire Hosting 包只应放在 AppHost 中。
应用项目不应引用 Aspire 客户端/服务发现包。

仅使用显式配置

AppHost 必须把资源输出转换为显式的配置键（环境变量）。
应用代码只绑定到 IOptions<T> 或 Configuration。

生产一致性与透明性

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

Do / Don't 检查清单

把每个 Aspire 资源输出映射到显式配置键
对所有基础设施设置使用带验证的 IOptions<T>
让 AppHost 成为唯一引用 Aspire hosting 包的地方
确保任何 AppHost 注入的值都能在生产环境变量中设置

Don't

在应用项目中引用 Aspire 客户端/服务发现包
依赖无法在生产中镜像的不透明服务发现
把配置隐藏在仅 Aspire 可用的抽象之后

资源

Aspire AppHost 环境配置：https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/app-host
.NET 中的配置：https://learn.microsoft.com/en-us/dotnet/core/extensions/configuration

技能介绍

用途