引言
随着微服务架构的普及，应用配置的集中化、动态化管理变得愈发重要。.NET Aspire 作为微软推出的云原生应用开发框架，为构建分布式应用提供了开箱即用的可观测性、服务发现与资源编排能力。而 AgileConfig 是一个轻量级、开源的 .NET 配置中心，支持配置热更新、多环境管理、客户端拉取等特性。
本文将详细介绍 如何在 .NET Aspire 项目中集成 AgileConfig，实现跨服务的统一配置管理，并利用 Aspire 的声明式资源模型简化部署流程。
技术背景
✅ .NET Aspire 简介
Aspire 是一套用于构建云原生 .NET 应用的工具链，包含：
- AppHost：定义应用拓扑和依赖（如数据库、缓存、配置中心）；
- ServiceDefaults：共享服务配置（健康检查、日志、OpenTelemetry）；
- Dashboard：运行时监控面板。
✅ AgileConfig 特点
- 基于 ASP.NET Core 构建，支持 REST API；
- 客户端通过长轮询或 WebSocket 实时获取配置变更；
- 支持 AppId + 环境（dev/test/prod）隔离；
- 提供 Web UI 管理界面；
- 轻量、无外部依赖（可使用 SQLite 或 MySQL 存储）。
整体架构设计
+------------------+ +---------------------+
| Aspire AppHost |------>| AgileConfig Server |
+------------------+ +----------+----------+
|
+-----------------------------+-----------------------------+
| | |
+-------v------+ +-------v------+ +-------v------+
| Service A | | Service B | | Frontend |
| (AgileConfig | | (AgileConfig | | (AgileConfig |
| Client) | | Client) | | Client) |
+--------------+ +--------------+ +--------------+所有服务通过 AgileConfig 客户端连接到统一的配置中心，Aspire 负责编排 AgileConfig Server 的生命周期。
步骤一：部署 AgileConfig Server（通过 Aspire AppHost）
- 添加 AgileConfig Server 到 AppHost
在 AppHost 项目的 Program.cs 中，将 AgileConfig 作为容器资源注册：
var agileConfig = builder.AddContainer("agileconfig", "kailing/agileconfig")
.WithHttpEndpoint(port: 5000, targetPort: 5000)
.WithEnvironment("ADMIN_USERNAME", "admin")
.WithEnvironment("ADMIN_PASSWORD", "123456")
.WithEnvironment("DB_PROVIDER", "sqlite");💡 使用官方 Docker 镜像
kailing/agileconfig，也可自行构建。
-
暴露配置中心地址给其他服务
// 供其他服务引用
builder.Services.AddKeyedSingleton("AgileConfigUrl", agileConfig.GetEndpoint("http"));
步骤二：在业务服务中集成 AgileConfig Client
以 OrderService 为例：
-
安装 NuGet 包
dotnet add package AgileConfig.Client
-
在
Program.cs中初始化客户端// Program.cs (OrderService)
var builder = WebApplication.CreateBuilder(args);// 从 Aspire 注入配置中心地址（可通过环境变量或服务发现）
var configServerUrl = builder.Configuration["AgileConfig:ServerUrl"]
?? "http://localhost:5000"; // 开发默认值// 初始化 AgileConfig 客户端
var client = new ConfigClient(configServerUrl, "OrderService", "dev");
client.Load();// 将 AgileConfig 配置源加入 ConfigurationBuilder
builder.Configuration.AddAgileConfig(client);var app = builder.Build();
app.UseServiceDefaults(); // Aspire 默认中间件
app.Run(); -
在 Aspire AppHost 中传递配置中心地址
在 AppHost 中为服务设置环境变量：
var orderService = builder.AddProject<Projects.OrderService>("orderservice")
.WithReference(agileConfig)
.WithEnvironment("AgileConfig__ServerUrl",
agileConfig.GetEndpoint("http").ToString());这样，OrderService 启动时就能自动连接到由 Aspire 管理的 AgileConfig 实例。
步骤三：使用配置（支持热更新）
在服务中通过 IOptions<T> 或直接读取 IConfiguration 获取配置：
// 定义配置类
public class FeatureSettings
{
public bool EnableDiscount { get; set; }
}
// 注册
builder.Services.Configure<FeatureSettings>(
builder.Configuration.GetSection("Feature"));
// 在 Controller 中使用
[ApiController]
public class OrderController : ControllerBase
{
private readonly FeatureSettings _settings;
public OrderController(IOptionsSnapshot<FeatureSettings> options)
{
_settings = options.Value; // IOptionsSnapshot 支持热更新
}
[HttpGet]
public IActionResult Get()
{
return Ok(new { DiscountEnabled = _settings.EnableDiscount });
}
}✅ 使用
IOptionsSnapshot或IOptionsMonitor可监听配置变更，实现热更新。
步骤四：初始化配置（可选）
可通过 AgileConfig Web UI（访问 http://<agileconfig-host>:5000）手动添加配置，或在 AppHost 启动后通过脚本自动初始化：
// 在 AppHost 中添加初始化任务（仅示例）
builder.AddExecutable("init-config", "dotnet", "InitConfig.dll")
.WithReference(agileConfig);优势总结
| 能力 | 说明 |
|---|---|
| 统一配置 | 所有 Aspire 服务共享同一配置中心 |
| 动态更新 | 无需重启服务即可生效新配置 |
| 环境隔离 | dev/test/prod 环境配置独立 |
| 声明式部署 | AgileConfig Server 由 Aspire 自动编排 |
| 轻量无侵入 | 客户端仅需几行代码集成 |
注意事项
- AgileConfig 默认使用 SQLite，生产环境建议切换为 MySQL/PostgreSQL；
- 确保网络策略允许服务访问 AgileConfig Server（Aspire 默认在同一网络）；
- 敏感配置（如密码）应结合 Aspire 的 Secrets Management 或 Azure Key Vault 使用；
- 客户端需处理连接失败的降级逻辑（如使用本地缓存配置）。
结语
通过将 AgileConfig 与 .NET Aspire 结合，我们不仅获得了云原生应用的现代化开发体验，还实现了配置的集中化与动态化管理。这种组合特别适合中小型团队快速构建可维护、可扩展的微服务系统。
未来，随着 Aspire 对更多第三方组件的支持增强，类似集成将变得更加标准化和自动化。