渴望配置
- 作者仓库星标 0
- 作者更新于 2026年8月7日 18:11
- 作者仓库 dotnet-skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @Aaronontheweb · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 需要 · Vendor-specific
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
// 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();
# Aspire Configuration
## When to Use This Skill
Use this skill when:
- Wiring AppHost resources to application configuration in Aspire-based repos
- Ensuring production configuration is transparent and portable outside of Aspire
- Avoiding Aspire client/service-discovery packages inside application code
- Designing feature toggles for dev/test without changing app code paths
---
## Core Principles
1. **AppHost owns Aspire infrastructure packages**
- Aspire Hosting packages belong in AppHost only.
- App projects should not reference Aspire client/service-discovery packages.
2. **Explicit configuration only**
- AppHost must translate resource outputs into explicit config keys (env vars).
- App code binds to `IOptions<T>` or `Configuration` only.
3. **Production parity and transparency**
- Every value injected by AppHost must be representable in production as env vars
or config files without Aspire.
- Avoid opaque service discovery and implicit configuration.
---
## Configuration Flow
```
AppHost resource -> WithEnvironment(...) -> app config keys -> IOptions<T> in app
```
The AppHost is responsible for turning Aspire resources into explicit app settings.
The application never consumes Aspire clients or service discovery directly.
---
## AppHost Patterns (Explicit Mapping)
### Example: Database + Blob Storage
```csharp
// 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();
```
**Key points**
- `WithReference(db, "Postgres")` sets `ConnectionStrings__Postgres` explicitly.
- Every external dependency is represented via explicit config keys.
- The API project only reads `Configuration` values.
---
## App Code Pattern (No Aspire Clients)
Application code binds to options and initializes SDKs directly. It never depends
on Aspire client packages or service discovery.
```csharp
// 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
});
```
**Do not** add Aspire client packages (or `AddServiceDiscovery`) to the app.
Those are orchestration concerns and should stay in AppHost.
---
## Feature Toggles and Test Overrides
Keep toggles in config and drive them through AppHost and test fixtures. This
maintains parity between dev/test and production configuration.
```csharp
// 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());
```
See `skills/aspire/integration-testing/SKILL.md` for patterns on passing
configuration overrides into `DistributedApplicationTestingBuilder`.
---
## Do / Don’t Checklist
**Do**
- Map every Aspire resource output to explicit configuration keys
- Use `IOptions<T>` with validation for all infrastructure settings
- Keep AppHost as the only place that references Aspire hosting packages
- Ensure any AppHost-injected value can be set in production env vars
**Don’t**
- Reference Aspire client/service-discovery packages in application projects
- Rely on opaque service discovery that cannot be mirrored in production
- Hide configuration behind Aspire-only abstractions
---
## Related Skills
- `skills/aspire/service-defaults/SKILL.md`
- `skills/aspire/integration-testing/SKILL.md`
- `skills/akka/aspire-configuration/SKILL.md`
---
## Resources
- Aspire AppHost environment configuration: https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/app-host
- Configuration in .NET: https://learn.microsoft.com/en-us/dotnet/core/extensions/configuration
章节与文件索引
按说明文件中的顺序排列。
何时使用此技能
核心原则
配置流程
示例:数据库 + Blob 存储
应用程序代码模式(无 Aspire 客户端)
文件/命令 -> IOptions<T> · Configuration · WithReference(db, "Postgres") · ConnectionStrings__Postgres · AddServiceDiscovery · skills/aspire/integration-testing/SKILL.md · DistributedApplicationTestingBuilder · skills/aspire/service-defaults/SKILL.md
内容校验值 -> 92b1bdba7ed9
当前原文的自动摘译,尚未人工审校。
何时使用此技能
在以下情况下使用此技能: 将 AppHost 资源连接到基于 Aspire 的存储库中的应用程序配置 确保生产配置在 Aspire 外部透明且可移植 避免在应用程序代码内使用 Aspire 客户端/服务发现包 设计用于开发/测试的功能切换而不更改应用程序代码路径
核心原则
AppHost 拥有 Aspire 基础设施包 Aspire Hosting 包仅属于 AppHost。应用程序项目不应引用 Aspire 客户端/服务发现包。仅显式配置 AppHost 必须将资源输出转换为显式配置键(环境变量)。
配置流程
AppHost 负责将 Aspire 资源转换为显式应用程序设置。该应用程序从不直接使用 Aspire 客户端或服务发现。
示例:数据库 + Blob 存储
关键点
WithReference(db, "Postgres")显式设置ConnectionStrings__Postgres。每个外部依赖项都通过显式配置键表示。 API项目仅读取Configuration值。应用程序代码模式(无 Aspire 客户端)
应用程序代码绑定到选项并直接初始化 SDK。它从不依赖于 Aspire 客户端包或服务发现。请勿将 Aspire 客户端包(或
AddServiceDiscovery)添加到应用程序中。这些都是编排问题,应该保留在 AppHost 中。