- A+
所属分类：.NET技术
选项用来提供对相关设置的强类型访问，读取配置首选使用选项模式。选项无法脱离容器使用，依赖容器，实现了选项不同的访问方式。选项模式使用了泛型包装器，因此具备了如下优点：
- 不需要显示注册选项具体类型，只需要将泛型包装器注入到容器中；
- 对于选项实例的评估推迟到获取IOptions.Value时进行，而不是在注入时进行，这样就可以获取不同生命周期的选项；
- 可以对选项进行泛型约束；
选项注入
选项模式向容器中注入了三种类型的选项泛型包装器：IOptions<>，IOptionsSnapshot<>，IOptionsMonitor<>。其中IOptionsSnapshot<>被注册为Scoped。注入了IOptionsFactory<>泛型选项工厂，用来创建选项实例。注入了IOptionsMonitorCache<>，由IOptionsMonitor<>用于缓存泛型实例。
public static IServiceCollection AddOptions(this IServiceCollection services) { if (services == null) throw new ArgumentNullException(nameof(services)); services.TryAdd(ServiceDescriptor.Singleton(typeof(IOptions<>), typeof(UnnamedOptionsManager<>))); 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; } 选项不同生命周期
不同类型的选项接口功能不同：
- IOptions<>：实现类为UnnamedOptionsManager，其中TOptions字段保存选项实例（不支持命名选项）。在首次获取Value时，会调用工厂创建选项实例。因为被注册为单例，因此无法识别配置修改。
- IOptionsSnapshot<>：实现类为OptionsManager，其中OptionsCache字段（私有，非容器获取）保存选项实例（支持命名选项）。被注册为范围，在范围内首次获取Value时，会调用工厂创建选项实例，并将其保存到私有的OptionsCache中，在范围内选项值不变，不同范围内选项值根据获取时配置文件的不同而不同。
- IOptionsMonitor<>：实现类为OptionsMonitor，其中IOptionsMonitorCache字段，该字段的值是从容器中解析的，用来缓存选项实例。OptionsMonitor还注入了IOptionsChangeTokenSource列表，可以监听配置源的修改。当监听到修改时，调用工厂重新创建选项以刷新选项值。
internal sealed class UnnamedOptionsManager<[DynamicallyAccessedMembers( Options.DynamicallyAccessedMembers)] TOptions> : IOptions<TOptions> where TOptions : class { private readonly IOptionsFactory<TOptions> _factory; private volatile object _syncObj; private volatile TOptions _value; public UnnamedOptionsManager(IOptionsFactory<TOptions> factory) => _factory = factory; public TOptions Value { get { if (_value is TOptions value) return value; lock (_syncObj ?? Interlocked.CompareExchange(ref _syncObj, new object(), null) ?? _syncObj) { return _value ??= _factory.Create(Options.DefaultName); } } } } public class OptionsManager<[DynamicallyAccessedMembers(Options.DynamicallyAccessedMembers)] TOptions> : IOptions<TOptions>, IOptionsSnapshot<TOptions> where TOptions : class { private readonly IOptionsFactory<TOptions> _factory; private readonly OptionsCache<TOptions> _cache = new OptionsCache<TOptions>(); public OptionsManager(IOptionsFactory<TOptions> factory) { _factory = factory; } public TOptions Value => Get(Options.DefaultName); public virtual TOptions Get(string name) { name = name ?? Options.DefaultName; if (!_cache.TryGetValue(name, out TOptions options)) { IOptionsFactory<TOptions> localFactory = _factory; string localName = name; options = _cache.GetOrAdd(name, () => localFactory.Create(localName)); } return options; } } public class OptionsMonitor<[DynamicallyAccessedMembers(Options.DynamicallyAccessedMembers)] TOptions> : IOptionsMonitor<TOptions>, IDisposable where TOptions : class { private readonly IOptionsMonitorCache<TOptions> _cache; private readonly IOptionsFactory<TOptions> _factory; 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; _cache = cache; void RegisterSource(IOptionsChangeTokenSource<TOptions> source) { IDisposable registration = ChangeToken.OnChange( () => source.GetChangeToken(), (name) => InvokeChanged(name), source.Name); _registrations.Add(registration); } // 此处简写 foreach (IOptionsChangeTokenSource<TOptions> source in sources) { RegisterSource(source); } } private void InvokeChanged(string name) { name = name ?? Options.DefaultName; _cache.TryRemove(name); TOptions 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 (IDisposable registration in _registrations) { registration.Dispose(); } _registrations.Clear(); } } 选项配置
选项模式提供了IConfigureOptions<>、IConfigureNamedOptions<>和IPostConfigureOptions<>接口，用来对选项进行配置。IConfigureNamedOptions<>继承了IConfigureOptions<>接口，增加了命名选项配置功能。这三个接口中都有一个对选项配置的方法，将接口注入到容器中，当调用工厂创建选项时，会调用接口中的配置方法对选项进行配置。首先会调用IConfigureOptions<>、IConfigureNamedOptions<>接口中的配置方法，然后调用IPostConfigureOptions<>接口中的配置方法。
// OptionsFactory<> public TOptions Create(string name) { TOptions options = CreateInstance(name); foreach (IConfigureOptions<TOptions> setup in _setups) { if (setup is IConfigureNamedOptions<TOptions> namedSetup) namedSetup.Configure(name, options); else if (name == Options.DefaultName) setup.Configure(options); } foreach (IPostConfigureOptions<TOptions> post in _postConfigures) { post.PostConfigure(name, options); } // 选项验证... return options; } protected virtual TOptions CreateInstance(string name) { return Activator.CreateInstance<TOptions>(); } 选项验证
选项模式提供了IValidateOptions<>接口，包含一个Validate方法对选项进行验证。将接口注入容器中，当调用工厂创建选项时，会调用接口中的Validate方法对选项进行验证。
// OptionsFactory<> public TOptions Create(string name) { TOptions options = CreateInstance(name); // 选项配置... if (_validations.Length > 0) { var failures = new List<string>(); foreach (IValidateOptions<TOptions> validate in _validations) { ValidateOptionsResult result = validate.Validate(name, options); if (result is not null && result.Failed) failures.AddRange(result.Failures); } if (failures.Count > 0) throw new OptionsValidationException(name, typeof(TOptions), failures); } return options; } 如果需要为选项添加验证，实现IValidateOptions<>接口并注入到容器即可：
builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton <IValidateOptions<SettingsOptions>, ValidateSettingsOptions>()); 也可以添加DataAnnotations验证，调用ValidateDataAnnotations扩展方法即可，该方法定义在 Microsoft.Extensions.Options.DataAnnotations中。需要先调用AddOptions<>扩展方法创建OptionsBuilder<>：
builder.Services.AddOptions<SettingsOptions>() .Bind(Configuration.GetSection(SettingsOptions.ConfigurationSectionName)) .ValidateDataAnnotations(); 绑定配置
通过如下扩展方法将选项绑定到配置：
builder.Services.Configure<SettingsOptions>(builder.Configuration.GetSection("Settings")); 绑定到配置是通过IConfiguration.Bind()扩展方法实现的，同时，也添加了对配置修改的监听：
public static IServiceCollection Configure<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TOptions>(this IServiceCollection services, string name, IConfiguration config, Action<BinderOptions> configureBinder) where TOptions : class { if (services == null) throw new ArgumentNullException(nameof(services)); if (config == null) throw new ArgumentNullException(nameof(config)); services.AddOptions(); services.AddSingleton<IOptionsChangeTokenSource<TOptions>>( new ConfigurationChangeTokenSource<TOptions>(name, config)); return services.AddSingleton<IConfigureOptions<TOptions>>( new NamedConfigureFromConfigurationOptions<TOptions>(name, config, configureBinder)); } 
