name: aspire-configuration description: 配置 Aspire AppHost，通过环境变量显式输出应用配置；保持应用代码不包含 Aspire 客户端和服务发现。 invocable: false

Aspire 配置

何时使用此技能

在以下情况下使用此技能：

在基于 Aspire 的仓库中，将 AppHost 资源连接到应用程序配置时
确保生产配置透明且可在 Aspire 之外移植
避免在应用程序代码内部使用 Aspire 客户端/服务发现包
为开发/测试设计功能开关，而无需更改应用程序代码路径

核心原则

AppHost 拥有 Aspire 基础设施包
- Aspire Hosting 包应仅存在于 AppHost 中。
- 应用程序项目不应引用 Aspire 客户端/服务发现包。
仅使用显式配置
- AppHost 必须将资源输出转换为显式配置键（环境变量）。
- 应用程序代码仅绑定到 IOptions<T> 或 Configuration。
生产环境对等性和透明度
- AppHost 注入的每个值都必须能够在生产环境中表示为环境变量或配置文件，而无需 Aspire。
- 避免不透明的服务发现和隐式配置。

配置流程

AppHost 资源 -> WithEnvironment(...) -> 应用程序配置键 -> 应用程序中的 IOptions<T>

AppHost 负责将 Aspire 资源转换为显式的应用程序设置。应用程序从不直接使用 Aspire 客户端或服务发现。

AppHost 模式（显式映射）

示例：数据库 + 对象存储

// 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 hosting 包的地方
确保任何 AppHost 注入的值都可以在生产环境变量中设置

不应做

在应用程序项目中引用 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

Aspire应用配置管理 aspire-configuration