配置热更新是.NET应用里一个高频需求。比如线上功能开关想随时切换、限流阈值需要动态调整、接口地址临时变更，如果每次改配置都要重启服务，代价显然太大。.NET从早期就提供了完整的配置体系，配合IOptionsMonitor接口，可以实现配置文件一变动、代码立刻感知的效果。这篇文章会从配置体系的结构讲起，逐步深入到IOptionsMonitor的用法、监听回调的实现，以及单例服务中容易踩坑的地方。
一、先弄清楚三种Options接口的区别
在讲热更新之前，必须先分清IOptions、IOptionsSnapshot和IOptionsMonitor这三兄弟。很多人配置不生效，根源就是选错了接口。IOptions是最基础的一种，它以单例方式注册，配置在首次读取后被缓存，之后无论配置文件怎么改，拿到的永远是旧值，天生不支持热更新。
IOptionsSnapshot则不同，它以Scoped方式注册，每一次请求范围内会重新计算一次配置。当配置源发生变更后，下一个请求拿到的就是新值。它的局限在于生命周期：如果在单例服务里注入IOptionsSnapshot，会直接抛出异常，因为Scoped服务不能被单例服务捕获。
IOptionsMonitor是三者中唯一既能支持热更新，又能安全用于单例服务的接口。它本身就是单例，内部维护了配置的缓存，并在配置源变化时自动刷新缓存值。简单总结：一次性读取用IOptions，请求级刷新用IOptionsSnapshot，需要实时监听变化就用IOptionsMonitor。
二、基础环境搭建与实体定义
假设我们的appsettings.json中有这样一段配置，用于描述一个支付网关的参数：
"PaySettings": {
"ApiUrl": "https://api.ipipp.com/pay",
"AppId": "app_10001",
"Enabled": true,
"TimeoutSeconds": 30
}
对应定义一个强类型配置实体类，属性名和配置键保持一致：
public class PaySettings
{
public string ApiUrl { get; set; }
public string AppId { get; set; }
public bool Enabled { get; set; }
public int TimeoutSeconds { get; set; }
}
接着在Program.cs中完成两步注册。第一步是AddJsonFile时开启ReloadOnChange，这是热更新的总开关，不开启的话后面一切监听都不会触发。第二步是调用Configure<PaySettings>把配置节绑定到实体上：
var builder = WebApplication.CreateBuilder(args);
// 这个ReloadOnChange参数是关键，开启后文件变动会自动触发重载
builder.Configuration.AddJsonFile("appsettings.json",
optional: true, reloadOnChange: true);
builder.Services.Configure<PaySettings>(
builder.Configuration.GetSection("PaySettings"));
builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();
ReloadOnChange的实现原理值得一提。底层是通过FileSystemWatcher监听配置文件的变更事件，文件被保存时触发重载，配置树会被重新构建，并且所有已注册的IOptionsMonitor实例都会收到变更通知。这也解释了为什么开发时用VS保存文件能立即生效，因为保存动作触发了文件写入事件。
三、IOptionsMonitor的核心用法：CurrentValue与OnChange
IOptionsMonitor提供两个核心能力。第一个是CurrentValue属性，每次访问都返回当前最新的配置值。第二个是OnChange方法，注册一个回调，配置一旦变化就执行。先看一个最小化示例：
[ApiController]
[Route("api/[controller]")]
public class PayController : ControllerBase
{
private readonly IOptionsMonitor<PaySettings> _payOptions;
public PayController(IOptionsMonitor<PaySettings> payOptions)
{
_payOptions = payOptions;
}
[HttpGet("current")]
public IActionResult GetCurrent()
{
// 每次请求都拿到最新配置，改完json立刻生效
var settings = _payOptions.CurrentValue;
return Ok(new
{
settings.ApiUrl,
settings.Enabled,
settings.TimeoutSeconds
});
}
}
CurrentValue适合“用时再取”的场景，比如每次发起支付请求前读取一次配置。而OnChange适合需要主动响应的场景，比如配置变更后需要重建HTTP客户端、刷新连接池、打日志通知运维等：
public class PayClient : IHostedService
{
private readonly IOptionsMonitor<PaySettings> _options;
private readonly ILogger<PayClient> _logger;
public PayClient(IOptionsMonitor<PaySettings> options,
ILogger<PayClient> logger)
{
_options = options;
_logger = logger;
}
public Task StartAsync(CancellationToken ct)
{
_options.OnChange((newSettings, name) =>
{
_logger.LogWarning("支付配置已变更，AppId={AppId}, ApiUrl={ApiUrl}",
newSettings.AppId, newSettings.ApiUrl);
// 这里可以执行重置HTTP客户端、重连等操作
});
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken ct) => Task.CompletedTask;
}
有一个细节需要特别注意：OnChange的回调在某些情况下可能被触发多次。这是因为文件监听事件可能在一个事务内被触发了不止一次，或者存在多个配置提供者。生产环境建议在回调里做防抖处理，比如记录上次触发时间，间隔小于500毫秒的重复通知直接忽略，避免重复执行重连逻辑。
private DateTime _lastChange = DateTime.MinValue;
private readonly object _lock = new();
_options.OnChange(newSettings =>
{
lock (_lock)
{
if ((DateTime.UtcNow - _lastChange).TotalMilliseconds < 500)
return;
_lastChange = DateTime.UtcNow;
}
// 真正的处理逻辑
});
四、单例服务中的坑点与验证方式
最常见的坑是：在单例服务里缓存了配置值，导致热更新失效。看下面这段有问题的代码：
public class BadSingleton
{
private readonly PaySettings _settings;
public BadSingleton(IOptionsMonitor<PaySettings> options)
{
// 错误做法：把值拷贝出来长期持有
_settings = options.CurrentValue;
}
public void DoWork()
{
// 即使json改了，这里永远是启动时的旧值
Console.WriteLine(_settings.ApiUrl);
}
}
问题在于_settings只在构造时赋值一次，之后和IOptionsMonitor的内部缓存彻底脱钩。正确的做法是持有IOptionsMonitor本身，在使用时再通过CurrentValue取值。如果确实需要在配置变化时更新内部状态，就结合OnChange来做。
另一个坑是把IOptionsSnapshot注入到单例服务中，运行时会抛出InvalidOperationException，提示无法从根提供程序解析Scoped服务。遇到这个错误，直接换成IOptionsMonitor即可。
验证热更新是否生效非常简单：启动程序后调用一次接口记下返回值，然后打开appsettings.json修改TimeoutSeconds并保存，不重启程序再次调用接口，观察值是否变化。如果没变化，先检查AddJsonFile有没有传reloadOnChange: true，再检查是不是把配置值缓存到了字段里。注意在Linux容器环境中，某些文件挂载方式（比如挂载单个文件）会导致文件监听失效，此时需要挂载目录而不是挂载文件，或者借助轮询方式重新加载。
五、进阶技巧与选型建议
除了本地json文件，IOptionsMonitor对环境变量、Azure Key Vault、Consul、Nacos等配置源同样有效，只要配置源实现了变更通知机制。以环境变量为例，虽然进程内环境变量本身不会变，但在Kubernetes中Pod重建时会加载新值，配合IOptionsMonitor的用法完全一致，代码无需修改。
再补充一个命名配置的技巧。通过Get(name)方法可以读取同一配置节下按名称区分的多组配置，比如多个租户各自一套支付参数：
var tenantA = _options.Get("TenantA");
var tenantB = _options.Get("TenantB");
对应的json结构是在PaySettings下再按租户名分组。这种方式在多租户系统中比维护多个配置类更灵活。
选型上给出一个简单结论：默认情况下推荐直接使用IOptionsMonitor，它几乎没有额外成本，既兼容单例又支持热更新；只有确定配置永不变化的场景才用IOptions；IOptionsSnapshot主要用于Scoped服务中希望每次请求重新计算配置的高开销绑定场景。把这三个接口的生命周期和刷新机制记牢，配置相关的疑难杂症基本都能迎刃而解。
C#配置热更新IOptionsMonitor.NET配置监听修改时间：2026-09-07 07:42:38