Asp.NetCore源码学习[1-2]：配置[Option]
- 2019 年 10 月 3 日
- 筆記
Asp.NetCore源码学习[1-2]：配置[Option]
在上一篇文章中，我们知道了可以通过
IConfiguration访问到注入的ConfigurationRoot，但是这样只能通过索引器IConfiguration["配置名"]访问配置。这篇文章将一下如何将IConfiguration映射到强类型。
本系列源码地址
一、使用强类型访问Configuration的用法
指定需要配置的强类型MyOptions和对应的IConfiguration
public void ConfigureServices(IServiceCollection services) { //使用Configuration配置Option services.Configure<MyOptions>(Configuration.GetSection("MyOptions")); //载入Configuration后再次进行配置 services.PostConfigure<MyOptions>(options=> { options.FilePath = "/"; }); }在控制器中通过DI访问强类型配置,一共有三种方法可以访问到强类型配置MyOptions，分别是IOptions、IOptionsSnapshot、IOptionsMonitor。先大概了解一下这三种方法的区别：
public class ValuesController : ControllerBase { private readonly MyOptions _options1; private readonly MyOptions _options2; private readonly MyOptions _options3; private readonly IConfiguration _configurationRoot; public ValuesController(IConfiguration configurationRoot, IOptionsMonitor<MyOptions> options1, IOptionsSnapshot<MyOptions> options2, IOptions<MyOptions> options3 ) { //IConfiguration(ConfigurationRoot)随着配置文件进行更新(需要IConfigurationProvider监听配置源的更改) _configurationRoot = configurationRoot; //单例，监听IConfiguration的IChangeToken，在配置源发生改变时，自动删除缓存 //生成新的Option实例并绑定，加入缓存 _options1 = options1.CurrentValue; //scoped，每次请求重新生成Option实例并从IConfiguration获取数据进行绑定 _options2 = options2.Value; //单例，从IConfiguration获取数据进行绑定，只绑定一次 _options3 = options3.Value; } }二、源码解读
首先看看Configure扩展方法，方法很简单，通过DI注入了Options需要的依赖。这里注入了了三种访问强类型配置的方法所需的所有依赖，接下来我们按照这三种方法去分析源码。
public static IServiceCollection Configure<TOptions>(this IServiceCollection services, IConfiguration config) where TOptions : class => services.Configure<TOptions>(Options.Options.DefaultName, config, _ => { }); public static IServiceCollection Configure<TOptions>(this IServiceCollection services, string name, IConfiguration config, Action<BinderOptions> configureBinder) where TOptions : class { services.AddOptions(); services.AddSingleton<IOptionsChangeTokenSource<TOptions>>(new ConfigurationChangeTokenSource<TOptions>(name, config)); return services.AddSingleton<IConfigureOptions<TOptions>>(new NamedConfigureFromConfigurationOptions<TOptions>(name, config, configureBinder)); }/// 为IConfigurationSection实例注册需要绑定的TOptions public static IServiceCollection AddOptions(this IServiceCollection services) { services.TryAdd(ServiceDescriptor.Singleton(typeof(IOptions<>), typeof(OptionsManager<>))); //创建以客户端请求为范围的作用域 services.TryAdd(ServiceDescriptor.Scoped(typeof(IOptionsSnapshot<>), typeof(OptionsManager<>))); services.TryAdd(ServiceDescriptor.Singleton(typeof(IOptionsMonitor<>), typeof(OptionsMonitor<>))); services.TryAdd(ServiceDescriptor.Transient(typeof(IOptionsFactory<>), typeof(OptionsFactory<>))); services.TryAdd(ServiceDescriptor.Singleton(typeof(IOptionsMonitorCache<>), typeof(OptionsCache<>))); return services; }1. 通过IOptions访问强类型配置
与其有关的注入只有三个:
services.TryAdd(ServiceDescriptor.Singleton(typeof(IOptions<>), typeof(OptionsManager<>))); services.TryAdd(ServiceDescriptor.Transient(typeof(IOptionsFactory<>), typeof(OptionsFactory<>))); services.AddSingleton<IConfigureOptions<TOptions>>(new NamedConfigureFromConfigurationOptions<TOptions>(name, config, configureBinder));从以上代码我们知道，通过IOptions访问到的其实是OptionsManager实例。
1.1 OptionsManager 的实现
通过IOptionsFactory<>创建TOptions实例，并使用OptionsCache<>充当缓存。OptionsCache<>实际上是通过ConcurrentDictionary实现了IOptionsMonitorCache接口的缓存实现，相关代码没有展示。
public class OptionsManager<TOptions> : IOptions<TOptions>, IOptionsSnapshot<TOptions> where TOptions : class { private readonly IOptionsFactory<TOptions> _factory; // 单例OptionsManager的私有缓存，通过ConcurrentDictionary实现了 IOptionsMonitorCache接口 // Di中注入的单例OptionsCache<> 是给 OptionsMonitor<>使用的 private readonly OptionsCache<TOptions> _cache = new OptionsCache<TOptions>(); // Note: this is a private cache public OptionsManager(IOptionsFactory<TOptions> factory) { _factory = factory; } public TOptions Value { get { return Get(Options.DefaultName); } } public virtual TOptions Get(string name) { name = name ?? Options.DefaultName; return _cache.GetOrAdd(name, () => _factory.Create(name)); } }1.2 IOptionsFactory 的实现
首先通过Activator创建TOptions的实例，然后通过IConfigureNamedOptions.Configure()方法配置实例。该工厂类依赖于注入的一系列IConfigureOptions，在Di中注入的实现为NamedConfigureFromConfigurationOptions，其通过委托保存了配置源和绑定的方法
/// Options工厂类 生命周期:Transient /// 单例OptionsManager和单例OptionsMonitor持有不同的工厂实例 public class OptionsFactory<TOptions> : IOptionsFactory<TOptions> where TOptions : class { private readonly IEnumerable<IConfigureOptions<TOptions>> _setups; private readonly IEnumerable<IPostConfigureOptions<TOptions>> _postConfigures; public OptionsFactory(IEnumerable<IConfigureOptions<TOptions>> setups, IEnumerable<IPostConfigureOptions<TOptions>> postConfigures) { _setups = setups; _postConfigures = postConfigures; } public TOptions Create(string name) { var options = CreateInstance(name); foreach (var setup in _setups) { if (setup is IConfigureNamedOptions<TOptions> namedSetup) { namedSetup.Configure(name, options); } else if (name == Options.DefaultName) { setup.Configure(options); } } foreach (var post in _postConfigures) { post.PostConfigure(name, options); } return options; } protected virtual TOptions CreateInstance(string name) { return Activator.CreateInstance<TOptions>(); } }1.3 NamedConfigureFromConfigurationOptions 的实现
在内部通过Action委托，保存了IConfiguration.Bind()方法。该方法实现了从IConfiguration到TOptions实例的赋值。
此处合并了NamedConfigureFromConfigurationOptions和ConfigureNamedOptions的代码。
public class NamedConfigureFromConfigurationOptions<TOptions> : ConfigureNamedOptions<TOptions> where TOptions : class { public NamedConfigureFromConfigurationOptions(string name, IConfiguration config) : this(name, config, _ => { }) { } public NamedConfigureFromConfigurationOptions(string name, IConfiguration config, Action<BinderOptions> configureBinder) : this(name, options => config.Bind(options, configureBinder)) { } public ConfigureNamedOptions(string name, Action<TOptions> action) { Name = name; Action = action; } public string Name { get; } public Action<TOptions> Action { get; } public virtual void Configure(string name, TOptions options) { if (Name == null || name == Name) { Action?.Invoke(options); } } public void Configure(TOptions options) => Configure(string.Empty, options); }由于
OptionsManager<>是单例模式，只会从IConfiguration中获取一次数据，在配置发生更改后，OptionsManager<>返回的TOptions实例不会更新。
2. 通过IOptionsSnapshot访问强类型配置
该方法和第一种相同，唯一不同的是，在注入DI系统的时候，其生命周期为scoped，每次请求重新创建OptionsManager<>。这样每次获取TOptions实例时，会新建实例并从IConfiguration重新获取数据对其赋值，那么TOptions实例的值自然就是最新的。
3. 通过IOptionsMonitor访问强类型配置
与其有关的注入有五个:
services.TryAdd(ServiceDescriptor.Singleton(typeof(IOptionsMonitor<>), typeof(OptionsMonitor<>))); services.TryAdd(ServiceDescriptor.Transient(typeof(IOptionsFactory<>), typeof(OptionsFactory<>))); services.TryAdd(ServiceDescriptor.Singleton(typeof(IOptionsMonitorCache<>), typeof(OptionsCache<>))); services.AddSingleton<IOptionsChangeTokenSource<TOptions>>(new ConfigurationChangeTokenSource<TOptions>(name, config)); services.AddSingleton<IConfigureOptions<TOptions>>(new NamedConfigureFromConfigurationOptions<TOptions>(name, config, configureBinder));第二种方法在每次请求时，都新建实例进行绑定，对性能会有影响。如何监测IConfiguration的变化，在变化的时候进行重新获取TOptions实例呢？答案是通过IChangeToken去监听配置源的改变。从上一篇知道，当使用FileProviders监听文件更改时，会返回一个IChangeToken,在FileProviders中监听返回的IChangeToken可以得知文件发生了更改并进行重新加载文件数据。所以使用IConfiguration 访问到的ConfigurationRoot 永远都是最新的。在IConfigurationProvider和IConfigurationRoot中也维护了IChangeToken字段，这是用于向外部一层层的传递更改通知。下图为更改通知的传递方向：
graph LR A["FileProviders"]--IChangeToken-->B B["IConfigurationProvider"]--IChangeToken-->C["IConfigurationRoot"]由于NamedConfigureFromConfigurationOptions没有直接保存IConfiguration字段，所以没办法通过它获取IConfiguration.GetReloadToken()。在源码中通过注入ConfigurationChangeTokenSource实现获取IChangeToken的目的
3.1 ConfigurationChangeTokenSource的实现
该类保存IConfiguration，并实现IOptionsChangeTokenSource接口
public class ConfigurationChangeTokenSource<TOptions> : IOptionsChangeTokenSource<TOptions> { private IConfiguration _config; public ConfigurationChangeTokenSource(IConfiguration config) : this(string.Empty, config) { } public ConfigurationChangeTokenSource(string name, IConfiguration config) { _config = config; Name = name ?? string.Empty; } public string Name { get; } public IChangeToken GetChangeToken() { return _config.GetReloadToken(); } }3.2 OptionsMonitor的实现
该类通过IOptionsChangeTokenSource获取IConfiguration的IChangeToken。通过监听更改通知，在配置源发生改变时，删除缓存，重新绑定强类型配置，并加入到缓存中。IOptionsMonitor接口还有一个OnChange()方法，可以注册更改通知发生时候的回调方法，在TOptions实例发生更改的时候，进行回调。值得一提的是，该类有一个内部类ChangeTrackerDisposable,在注册回调方法时，返回该类型，在需要取消回调时，通过ChangeTrackerDisposable.Dispose()取消刚刚注册的方法。
public class OptionsMonitor<TOptions> : IOptionsMonitor<TOptions>, IDisposable where TOptions : class { private readonly IOptionsMonitorCache<TOptions> _cache; private readonly IOptionsFactory<TOptions> _factory; private readonly IEnumerable<IOptionsChangeTokenSource<TOptions>> _sources; private readonly List<IDisposable> _registrations = new List<IDisposable>(); internal event Action<TOptions, string> _onChange; public OptionsMonitor(IOptionsFactory<TOptions> factory, IEnumerable<IOptionsChangeTokenSource<TOptions>> sources, IOptionsMonitorCache<TOptions> cache) { _factory = factory; _sources = sources; _cache = cache; foreach (var source in _sources) { var registration = ChangeToken.OnChange( () => source.GetChangeToken(), (name) => InvokeChanged(name), source.Name); _registrations.Add(registration); } } private void InvokeChanged(string name) { name = name ?? Options.DefaultName; _cache.TryRemove(name); var options = Get(name); if (_onChange != null) { _onChange.Invoke(options, name); } } public TOptions CurrentValue { get => Get(Options.DefaultName); } public virtual TOptions Get(string name) { name = name ?? Options.DefaultName; return _cache.GetOrAdd(name, () => _factory.Create(name)); } public IDisposable OnChange(Action<TOptions, string> listener) { var disposable = new ChangeTrackerDisposable(this, listener); _onChange += disposable.OnChange; return disposable; } public void Dispose() { foreach (var registration in _registrations) { registration.Dispose(); } _registrations.Clear(); } internal class ChangeTrackerDisposable : IDisposable { private readonly Action<TOptions, string> _listener; private readonly OptionsMonitor<TOptions> _monitor; public ChangeTrackerDisposable(OptionsMonitor<TOptions> monitor, Action<TOptions, string> listener) { _listener = listener; _monitor = monitor; } public void OnChange(TOptions options, string name) => _listener.Invoke(options, name); public void Dispose() => _monitor._onChange -= OnChange; } }4. 测试代码
本篇文章中，由于Option依赖于自带的注入系统，而本项目中Di部分还没有完成，所以，这篇文章的测试代码直接new依赖的对象。
public class ConfigurationTest { public static void Run() { var builder = new ConfigurationBuilder(); builder.AddJsonFile(null, $@"C:WorkStationCodeGitHubCodeCoreAppCoreWebAppappsettings.json", true,true); var configuration = builder.Build(); Task.Run(() => { ChangeToken.OnChange(() => configuration.GetReloadToken(), () => { Console.WriteLine("Configuration has changed"); }); }); var optionsChangeTokenSource = new ConfigurationChangeTokenSource<MyOption>(configuration); var configureOptions = new NamedConfigureFromConfigurationOptions<MyOption>(string.Empty, configuration); var optionsFactory = new OptionsFactory<MyOption>(new List<IConfigureOptions<MyOption>>() { configureOptions },new List<IPostConfigureOptions<MyOption>>()); var optionsMonitor = new OptionsMonitor<MyOption>(optionsFactory,new List<IOptionsChangeTokenSource<MyOption>>() { optionsChangeTokenSource },new OptionsCache<MyOption>()); optionsMonitor.OnChange((option,name) => { Console.WriteLine($@"optionsMonitor Detected Configuration has changed,current Value is {option.TestOption}"); }); Thread.Sleep(600000); } }测试结果
回调会触发两次，这是由于FileSystemWatcher造成的，可以通过设置一个后台线程，在检测到文件变化时，主线程将标志位置true，后台线程轮询标志位
—
结语
至此，从IConfiguration到TOptions强类型的映射已经完成。
