Net6Configuration&Options源码分析Part2Options

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与IPostConfigureOptions的大量泛型类是为了实现使用AddOptions注册的Configure Action访问其它DI内服务。会在下面单独记录。

值得注意的是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|直接在DI|Singleton|在应用启动后读取配置数据且配置更新后获取不到新的变更。实现逻辑：直接调用OptionsFactory.Create(Options.DefaultName)拿到所有Configure Action的包装类 执行包装类配置方法|
IOptionsSnapshot|OptionsManager|同上|Scoped:|区别，通过使用 IOptionsSnapshot，针对请求生存期访问和缓存选项时，每个请求都会计算一次选项。 当使用支持读取已更新的配置值的配置提供程序时，将在应用启动后读取对配置所做的更改。实现逻辑：用Factory创建完后得缓存下。非常的简单。|
IOptionsMonitor|OptionsMonitor|同上|Singleton|区别，当配置发生改变是由他提供的配置会实时更新。|

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.Craete Create就更简单了。构造方法就把所有的 IConfigureOptions/IPostConfigureOptions拿到了。直接循环两个集合，并调用Configure方法就Ok了 Caonfigure内部执行注入的Action 对TOptions实例一顿操作。

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 实际为new NamedConfigureFromConfigurationOptions的类。那么NamedConfigureFromConfigurationOptions类构造函数里面直接把BindFromOptions方法作为Configure Action传给父类ConfigureNamedOptions 也就是说此类是帮我们提供了一个调用了configureBinder的Configure Action。（config.Bind(options, configureBinder)这个Bing是扩展方法,ConfigurationBinder是个帮助类）。这样看来NamedConfigureFromConfigurationOptions唯一的作用就是帮帮我们组织了一个Configure Action免得你去自己写了。
关于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<>)));}