Net6 Configuration & Options 源码分析 Part2 Options
第二部分主要记录Options 模型
OptionsConfigurationServiceCollectionExtensions类提供了对Options 模型与配置系统的Configure方法的扩展
1. 直接使用Options
直接使用Options
在Starup ConfigService中经常会看到把一个拉姆达注册成配置项例如：.Configure<Profile>(it ->it.age = 18)，我们称这个拉姆达为Configure Action，其实这是使用了一个包装类，包装你的Configure Action委托，并把这个类的实例注册到Service容器中。它实现IOptions与拉姆达如何映射的，这一切由OptionsServiceCollectionExtensions、OptionsFacotry等实现的。你也可以直接像下面这样使用
var profile = new Servicecollection ().Addoptions().Configure<Profile>(it ->it.age = 18).BuildServiceProvider().GetRequiredService<IOptions<Profile>>().Value;
配置服务注册源码分析/Configure Action包装类的注册
OptionsServiceCollectionExtensions 作为配置服务的扩展类下面有三种类型的扩展方法分别是Configure、PostConfigure、AddOptions，前两所对应的服务为IConfigureOptions与IPostConfigureOptions 区别仅仅是为了实现配置Configure Action的执行时机，IPostConfigureOptions会后执行，而AddOptions本质上还是注册前两种，注册成面上看起来AddOptions注册的Configure Action具有了参数可以访问其它DI内服务。
注意：就算你使用了三个注册方式注册一次或多次对同一个TOptions进行注册，他们其实是操作的同一个TOptions给你。这体现在OptionsFactory.Create上，也是我们想要的效果。
以下代码为Configure、PostConfigure的服务注册逻辑。
Configure、PostConfigure、扩展方法注册的 Configure Action会由IConfigureOptions与IPostConfigureOptions 接口对应的包装类进行包装。属性均是Action，Configure Action的执行是在Configure方法中。IConfigureOptions
值得注意的是ConfigureAll如果你此方法去注入一个Name 为null 的 Configure Action包装类逻辑体现在ConfigureNamedOptions.Configure/PostConfigureOptions.Configure方法上。，官方说法：“Configure ALL options instances, both named and default”翻译后扩展方法将配置应用于所有选项，包括命名实例和默认实例。
Configure -> ConfigureNamedOptions
PostConfigure -> PostConfigureOptions
public static class OptionsServiceCollectionExtensions
{
...
public static IServiceCollection Configure<TOptions>(this IServiceCollection services!!, string? name, Action<TOptions> configureOptions!!)
where TOptions : class
{
services.AddOptions();
services.AddSingleton<IConfigureOptions<TOptions>>(new ConfigureNamedOptions<TOptions>(name, configureOptions));
return services;
}
public static IServiceCollection PostConfigure<TOptions>(this IServiceCollection services!!, string? name, Action<TOptions> configureOptions!!)
where TOptions : class
{
services.AddOptions();
services.AddSingleton<IPostConfigureOptions<TOptions>>(new PostConfigureOptions<TOptions>(name, configureOptions));
return services;
}
...
}
public class ConfigureNamedOptions<TOptions> : IConfigureNamedOptions<TOptions> where TOptions : class
{
public ConfigureNamedOptions(string? name, Action<TOptions>? action)
{
Name = name;
Action = action;
}
public virtual void Configure(string? name, TOptions options!!)
{
// Null name is used to configure all named options.// Name的过滤以及Configure 逻辑就是在这里体现的
if (Name == null || name == Name)
{
Action?.Invoke(options);
}
}
}
public class PostConfigureOptions<TOptions> : IPostConfigureOptions<TOptions> where TOptions : class
{
public PostConfigureOptions(string? name, Action<TOptions>? action)
{
Name = name;
Action = action;
}
public virtual void PostConfigure(string? name, TOptions options!!)
{
if (Name == null || name == Name)
{
Action?.Invoke(options);
}
}
}
以下代码为AddOptions 的服务注册逻辑。
AddOptions:此方法会帮你构建一个OptionsBuilder,并非向Service容器注入，而是利用其builder类的Configure方法向Service容器具体注入。其下面的大量重载 Configure方法会帮你创建基于IConfigureNamedOptions/IPostConfigureOptions不同数量的泛型类. 其目的就是为了解决在“ Configure Action”中使用其它服务。
设计思路很好可以参考整体思路大概是，先用AddOptions
扩展方法创建了一个OptionsBuilder 对象，然后调用它重载方法Configure<TService...>去创建具有多个泛型的ConfigureNamedOptions 对象。ConfigureNamedOptions的Configure在执行Action委托时会用serviceProvider获取到TService泛型服务。作为参数传入Action委托。这样委托在真正被执行时就会拿到对应的服务。
public static class OptionsServiceCollectionExtensions
{
...
public static OptionsBuilder<TOptions> AddOptions<TOptions>(this IServiceCollection services!!, string? name)
where TOptions : class
{
services.AddOptions();
return new OptionsBuilder<TOptions>(services, name);
}
...
}
public class OptionsBuilder<TOptions> where TOptions : class
{
...
public virtual OptionsBuilder<TOptions> Configure<TDep>(Action<TOptions, TDep> configureOptions!!) where TDep : class
{
Services.AddTransient<IConfigureOptions<TOptions>>(sp =>
new ConfigureNamedOptions<TOptions, TDep>(Name, sp.GetRequiredService<TDep>(), configureOptions));
return this;
}
...
}
public class ConfigureNamedOptions<TOptions, TDep> : IConfigureNamedOptions<TOptions> {
...
public ConfigureNamedOptions(string? name, TDep dependency, Action<TOptions, TDep>? action)
{
Name = name;
Action = action;
Dependency = dependency;
}
public virtual void Configure(string? name, TOptions options!!)
{
// Null name is used to configure all named options.
if (Name == null || name == Name)
{
Action?.Invoke(options, Dependency);
}
}
...
}
总结
| 注入到服务的扩展方法（OptionsServiceCollectionExtensions） | 服务类 | 服务实现类 | 使用 | 生命周期 | 备注 |
|---|---|---|---|---|---|
| Configure | IConfigureOptions | ConfigureNamedOptions | 被OptonsFactory使用 | Singleton | ConfigureAll，在IPostConfigureOptions前执行Configure Action |
| PostConfigure | IPostConfigureOptions | PostConfigureOptions | 被OptonsFactory使用 | Singleton | ConfigureAll 在IConfigureOptions后执行Configure Action |
| AddOptions | IConfigureOptions/IPostConfigureOptions | ConfigureNamedOptions/PostConfigureOptions | 被OptonsFactory使用 | Singleton | 辅助注入一个可以访问其它服务的Configure Action |
配置Otpns服务的使用
首先在固有想法上注入的服务直接会拿来使用。而在这里注入的均为IConfigureOptions/IPostConfigureOptions服务我们管他们叫Configure Action的包装类，而要使用这些服务是通过IOptions/IOptionsSnapshot/IOptionsMonitor去获得。我们称这三个服务为OptionsManger类。
注册的基础服务（OptionsServiceCollectionExtensions.AddOptions）
这里整理出来IOptions/IOptionsSnapshot/IOptionsMonitor三种OptionsManger的区别。
服务类|服务实现类|使用|生命周期|备注|
---|:--:--:--:----:
IOptions|UnnamedOptionsManager
IOptionsSnapshot|OptionsManager
IOptionsMonitor|OptionsMonitor
IOptions 使用Demo
var source = new Dictionary<string, string>{
{"TestOptions:Key1" ,"TestOptions key1"},
};
var config = new ConfigurationBuilder().Add(new MemoryConfigurationSource() { InitialData = source }).Build();
ServiceCollection services = new ServiceCollection();
services.AddOptions();
services.Configure<TestOptions>(config.GetSection("TestOptions")); // Import the "Microsoft.Extensions.Options.ConfigurationExtensions" package.
var serviceProvider = services.BuildServiceProvider();
IOptions<TestOptions> options = serviceProvider.GetService<IOptions<TestOptions>>();
Console.WriteLine(options.Value.Key1);
Console.ReadLine();
public class TestOptions
{
public string Key1 { get; set; }
}
IOptions 使用源码分析
以第一个为例：UnnamedOptionsManager 的value属性的get 访问器其内部直接调用OptionsFactory
internal sealed class UnnamedOptionsManager<[DynamicallyAccessedMembers(Options.DynamicallyAccessedMembers)] TOptions> : IOptions<TOptions>where TOptions : class
{
private volatile TOptions? _value;
public UnnamedOptionsManager(IOptionsFactory<TOptions> factory) => _factory = factory;
public TOptions Value
{
get
{
if (_value is TOptions value)
{
return value;
}
return _value ??= _factory.Create(Options.DefaultName);
}
}
}
public class OptionsFactory<[DynamicallyAccessedMembers(Options.DynamicallyAccessedMembers)] TOptions> :
IOptionsFactory<TOptions>
where TOptions : class
{
...
public TOptions Create(string name)
{
// 创建Toptions 实例对象
TOptions options = CreateInstance(name);
// 依次调用注册的 Configure Action
// 先执行IConfigureOptions包装的Configure Action.
foreach (IConfigureOptions<TOptions> setup in _setups)
{
if (setup is IConfigureNamedOptions<TOptions> namedSetup)
{
namedSetup.Configure(name, options);
}
else if (name == Options.DefaultName)
{
setup.Configure(options);
}
}
// 在执行 IPostConfigureOptions包装的Configure Action.
foreach (IPostConfigureOptions<TOptions> post in _postConfigures)
{
post.PostConfigure(name, options);
}
// 执行验证逻辑
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;
}
...
}
IOptionsSnapshot 使用Demo
因实现逻辑基本与IOptons相同这里就不多做记录。
var source = new Dictionary<string, string>{
{"TestOptions:Key1" ,"TestOptions key1"},
};
var config = new ConfigurationBuilder().Add(new MemoryConfigurationSource() { InitialData = source }).Build();
ServiceCollection services = new ServiceCollection();
services.AddOptions();
services.Configure<TestOptions>("TestOptions", config.GetSection("TestOptions")); // Import the "Microsoft.Extensions.Options.ConfigurationExtensions" package.
var serviceProvider = services.BuildServiceProvider();
IOptionsSnapshot<TestOptions> optionsAccessor = serviceProvider.GetRequiredService<IOptionsSnapshot<TestOptions>>();
Console.WriteLine(optionsAccessor.Get("TestOptions").Key1);
Console.ReadLine();
public class TestOptions
{
public string Key1 { get; set; }
}
配置源的同步 IOptionsMonitor 的使用 Demo
源码在part3 单独分析。
var configuration = new ConfigurationBuilder().AddJsonFile(path: "profile.json",
optional: false,
reloadOnChange: true).Build();
new ServiceCollection().AddOptions().Configure<Profile>(configuration).BuildServiceProvider().GetRequiredService<IOptionsMonitor<Profile>>().OnChange(profile => Console.WriteLine($"changed: {profile.Age}"));
Console.Read();
public class Profile
{
public int Age { get; set; }
}
"Options模型"与“配置系统”结合。
2. 将配置绑定为Options对象
如下两个demo分别演示了"Options模型"与“配置系统”结合的结合使用。
Demo1
var configuration = new ConfigurationBuilder ().AddJsonFile ("profile.json").Build ();
var profile = new ServiceCollection().AddOptions().Configure<Profile>(configuration).BuildServiceProvider().GetRequiredService<IOptions<Profile>>().Value;
Demo2
var source = new Dictionary<string, string>{
{"TestOptions:Key1" ,"TestOptions key1"},
{"TestOptions:Key2" ,"TestOptions key2"},
{"UserInfo:key1" ,"UserInfo"},
};
var config = new ConfigurationBuilder().Add(new MemoryConfigurationSource() { InitialData = source }).Build();
ServiceCollection services = new ServiceCollection();
services.AddOptions();
services.Configure<TestOpetion>(config.GetSection("TestOptions")); // Import the "Microsoft.Extensions.Options.ConfigurationExtensions" package.
var serviceProvider = services.BuildServiceProvider();
var options = serviceProvider.GetRequiredService<IOptions<TestOpetion>>();
Console.WriteLine(options.Value.Key1);
Console.ReadLine();
public class TestOpetion{
public string Key1{ get; set; }
public string Key2 { get; set; }
}
以上操作步骤为OptionsConfigurationServiceCollectionExtensions类定义了对 Configure的扩展，有三个参数string name、config（IConfiguration），configureBinder的委托，第一个参数是TOptions的name， 第二个表示配置系统的IConfiguration，第三个configureBinder 是配置系统在映射Toptions时候的一些配置
原理很简单，因为有了ServiceCollection的支持，那么就往里面帮我们注入一个类型为IConfigureOptions
关于configureBinder基本逻辑基本是根据TOptions的Type 对象反射出信息，然后第二个参数config（配置系统提供数据的接口）拿数据，在把对应的数据绑定在TOptions 对象上。
public static IServiceCollection Configure<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TOptions>(this IServiceCollection services!!, string? name, IConfiguration config!!, Action<BinderOptions>? configureBinder)
where TOptions : class
{
services.AddOptions();
// 用于支持**“配置系统”**与 **"Options模型"**结合后当配置系统发生更新时回调options时注册的回调函数。后面会说到
services.AddSingleton<IOptionsChangeTokenSource<TOptions>>(new ConfigurationChangeTokenSource<TOptions>(name, config));
// 注册NamedConfigureFromConfigurationOptions
return services.AddSingleton<IConfigureOptions<TOptions>>(new NamedConfigureFromConfigurationOptions<TOptions>(name, config, configureBinder));
}
/// Configures an option instance by using <see cref="ConfigurationBinder.Bind(IConfiguration, object)"/> against an <see cref="IConfiguration"/>.
public class NamedConfigureFromConfigurationOptions<TOptions> : ConfigureNamedOptions<TOptions> where TOptions : class
{
public NamedConfigureFromConfigurationOptions(string? name, IConfiguration config!!, Action<BinderOptions>? configureBinder)
: base(name, options => BindFromOptions(options, config, configureBinder)){
}
private static void BindFromOptions(TOptions options, IConfiguration config, Action<BinderOptions>? configureBinder) => config.Bind(options, configureBinder);
}
public class BinderOptions
{
// true 会对TOptons的私有属性也赋值
public bool BindNonPublicProperties { get; set; }
public bool ErrorOnUnknownConfiguration { get; set; }
}
验证Options的有效性
Options 扩展方法注册Microsoft.Extensions.Options向Service容器注入认证服务，其原理是OptionsFactory.Create拿到所有注入的服务。将TOptons作为参数传入实例的验证方法。
services.AddOptions<DateTimeFormatOptions>().Configure(options =>options. DatePattern = datePattern;options.TimePattern = timePattern;).Validate(options => Validate (options.DatePattern) && Validate(options. TimePattern), "Invalid Date or Time pattern.");
其它
OptionsServiceCollectionExtensions Options 模型依赖的服务
public static IServiceCollection AddOptions(this IServiceCollection 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<>)));
}