ASP.NET Core 3.0 : 二十四. 配置的Options模式
上一章讲到了配置的用法及内部处理机制,对于配置,asp.net core还提供了一种options模式。(asp.net core 系列目录)
一、options的使用
上一章有个配置的绑定的例子,可以将配置绑定到一个theme实例中。也就是在使用对应配置的时候,需要进行一次绑定操作。而options模式提供了更直接的方式,并且可以通过依赖注入的方式提供配置的读取。下文中称每一条options配置为option。
1.简单的不为option命名的方式
依然采用这个例子,在appsettings.json中存在这样的配置:
{ "theme": { "name": "blue", "color": "#0921dc" } }
修改一下valuecontroller,代码如下:
public class valuescontroller : controller { private ioptions<theme> _options = null; public valuescontroller(ioptions<theme> options) { _options = options; } public contentresult getoptions() { return new contentresult() { content = $"options:{ _options.value.name}" }; } }
依然需要在startup文件中做注册:
public void configureservices(iservicecollection services) { services.configure<theme>(configuration.getsection("theme")); services.addcontrollerswithviews(); //3.0中启用的新方法 }
请求这个action,获取到的结果为:
options:blue
这样就可以在需要使用该配置的时候通过依赖注入的方式使用了。但有个疑问,这里将“theme”类型绑定了这样的配置,但如果有多个这样的配置呢?就如同下面这样的配置的时候:
"themes": [ { "name": "blue", "color": "#0921dc" }, { "name": "red", "color": "#ff4500" } ]
在这样的情况下,存在多个theme的配置,这样对于之前这种依赖注入的方式就不行了。这时系统提供了将注入的options进行命名的方法。
2.为option命名的方式
首先需要在startup文件中注册的时候对其命名,添加如下两条注册代码:
services.configure<theme>("themeblue", configuration.getsection("themes:0")); services.configure<theme>("themered" , configuration.getsection("themes:1"));
修改valuecontroller代码,添加ioptionsmonitor<theme>和ioptionssnapshot<theme>两种新的注入方式如下:
private ioptions<theme> _options = null; private ioptionsmonitor<theme> _optionsmonitor = null; private ioptionssnapshot<theme> _optionssnapshot = null; public valuescontroller(ioptions<theme> options, ioptionsmonitor<theme> optionsmonitor, ioptionssnapshot<theme> optionssnapshot) { _options = options; _optionsmonitor = optionsmonitor; _optionssnapshot = optionssnapshot; } public contentresult getoptions() { return new contentresult() { content = $"options:{_options.value.name}," + $"optionssnapshot:{ _optionssnapshot.get("themeblue").name }," + $"optionsmonitor:{_optionsmonitor.get("themered").name}" }; }
请求这个action,获取到的结果为:
options:blue,optionssnapshot:red,optionsmonitor:gray
新增的两种注入方式通过options的名称获取到了对应的options。为什么是两种呢?它们有什么区别?不知道有没有读者想到上一章配置的重新加载功能。在配置注册的时候,有个reloadonchange选项,如果它被设置为true的,当对应的数据源发生改变的时候,会进行重新加载。而options怎么能少了这样的特性呢。
3.option的自动更新与生命周期
为了验证这三种options的读取方式的特性,修改theme类,添加一个guid字段,并在构造方法中对其赋值,代码如下:
public class theme { public theme() { guid = guid.newguid(); } public guid guid { get; set; } public string name { get; set; } public string color { get; set; } }
修改上例中的名为getoptions的action的代码如下:
public contentresult getoptions() { return new contentresult() { content = $"options:{_options.value.name}|{_options.value.guid}," + $"optionssnapshot:{ _optionssnapshot.get("themeblue").name }|{_optionssnapshot.get("themeblue").guid}," + $"optionsmonitor:{_optionsmonitor.get("themered").name}|{_optionsmonitor.get("themered").guid}" }; }
请求这个action,返回结果如下:
options:blue|ad328f15-254f-4505-a79f-4f27db4a393e,optionssnapshot:red|dba5f550-29ca-4779-9a02-781dd17f595a,optionsmonitor:gray|a799fa41-9444-45dd-b51b-fcd15049f98f
刷新页面,返回结果为:
options:blue|ad328f15-254f-4505-a79f-4f27db4a393e,optionssnapshot:red|a2350cb3-c156-4f71-bb2d-25890fe08bec,optionsmonitor:gray|a799fa41-9444-45dd-b51b-fcd15049f98f
可见ioptions和ioptionsmonitor两种方式获取到的name值和guid值均未改变,而通过ioptionssnapshot方式获取到的name值未改变,但guid值发生了改变,每次刷新页面均会改变。这类似前面讲依赖注入时做测试的例子,现在猜测guid未改变的ioptions和ioptionsmonitor两种方式是采用了singleton模式,而guid发生改变的ioptionssnapshot方式是采用了scoped或transient模式。如果在这个action中多次采用ioptionssnapshot读取_optionssnapshot.get("themeblue").guid的值,会发现同一次请求的值是相同的,不同请求之间的值是不同的,也就是ioptionssnapshot方式使采用了scoped模式(此验证示例比较简单,请读者自行修改代码验证)。
在这样的情况下,修改三种获取方式对应的配置项的name值,例如分别修改为“blue1”、“red1”和“gray1”,再次多次刷新页面查看返回值,会发现如下情况:
ioptions方式:name和guid的值始终未变。name值仍为blue。
ioptionssnapshot方式:name值变为red1,guid值单次请求内相同,每次刷新之间不同。
ioptionsmonitor方式:只有修改配置值后第一次刷新的时候将name值变为了gray1,guid未改变。之后多次刷新,这两个值均未做改变。
总结:ioptions和ioptionsmonitor两种方式采用了singleton模式,但区别在于ioptionsmonitor会监控对应数据源的变化,如果发生了变化则更新实例的配置值,但不会重新提供新的实例。ioptionssnapshot方式采用了scoped模式每次请求采用同一个实例,在下一次请求的时候获取到的是一个新的实例,所以如果数据源发生了改变,会读取到新的值。先大概记一下这一的情况,在下文剖析ioptions的内部处理机制的时候就会明白为什么会这样。
4.数据更新提醒
ioptionsmonitor方式还提供了一个onchange方法,当数据源发生改变的时候会触发它,所以如果想在这时候做点什么,可以利用这个方法实现。示例代码:
_optionsmonitor.onchange((theme,name)=> { console.writeline(theme.name +"-"+ name); });
5.不采用configuration配置作为数据源的方式
上面的例子都是采用了读取配置的方式,实际上options模式和上一章的configuration配置方式使分开的,读取配置只不过是options模式的一种实现方式,例如可以不使用configuration中的数据,直接通过如下代码注册:
services.configure<theme>("themeblack", theme => { theme.color = "#000000"; theme.name = "black"; });
6.configureall方法
系统提供了一个configureall方法,可以将所有对应的实例统一设置。例如如下代码:
services.configureall<theme>(theme => { theme.color = "#000000"; theme.name = "black2"; });
此时无论通过什么名称去获取theme的实例,包括不存在对应设置的名称,获取到的值都是本次通过configureall设置的值。
7.postconfigure和postconfigureall方法
这两个方法和configure、configureall方法类似,只是它们会在configure、configureall之后执行。
8.多个configure、configureall、postconfigure和postconfigureall的执行顺序
可以这样理解,每个configure都是去修改一个名为其设置的名称的变量,以如下代码为例:
services.configure<theme>("themeblack", theme => { theme.color = "#000000"; theme.name = "black"; });
这条设置就是去修改(注意是修改而不是替换)一个名为"themeblack"的theme类型的变量,如果该变量不存在,则创建一个theme实例并赋值。这样就生成了一些变量名为“空字符串、“themeblue”、“themeblack”的变量(只是举例,忽略空字符串作为变量名不合法的顾虑)”。
依次按照代码的顺序执行,这时候如果后面的代码中出现同名的configure,则修改对应名称的变量的值。如果是configureall方法,则修改所有类型为theme的变量的值。
而postconfigure和postconfigureall则在configure和configureall之后执行,即使configure的代码写在了postconfigure之后也是一样。
至于为什么会是这样的规则,下一节会详细介绍。
二、内部处理机制解析
1. 系统启动阶段,依赖注入
上一节的例子中涉及到了三个接口ioptions、ioptionssnapshot和ioptionsmonitor,那么就从这三个接口说起。既然options模式是通过这三个接口的泛型方式注入提供服务的,那么在这之前系统就需要将它们对应的实现注入到依赖注入容器中。这发生在系统启动阶段创建ihost的时候,这时候hostbuilder的build方法中调用了一个services.addoptions()方法,这个方法定义在optionsservicecollectionextensions中,代码如下:
public static class optionsservicecollectionextensions { public static iservicecollection addoptions(this iservicecollection services) { if (services == null) { throw new argumentnullexception(nameof(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; } public static iservicecollection configure<toptions>(this iservicecollection services, action<toptions> configureoptions) where toptions : class => services.configure(options.options.defaultname, configureoptions); 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 configureall<toptions>(this iservicecollection services, action<toptions> configureoptions) where toptions : class => services.configure(name: null, configureoptions: configureoptions); //省略部分代码 }
可见这个addoptions方法的作用就是进行服务注入,ioptions<>、ioptionssnapshot<>对应的实现是optionsmanager<>,只是分别采用了singleton和scoped两种生命周期模式,ioptionsmonitor<>对应的实现是optionsmonitor<>,同样为singleton模式,这也验证了上一节例子中的猜想。除了上面提到的三个接口外,还有ioptionsfactory<>和ioptionsmonitorcache<>两个接口,这也是options模式中非常重要的两个组成部分,接下来的内容中会用到。
另外的两个configure方法就是上一节例子中用到的将具体的theme注册到options中的方法了。二者的区别就是是否为配置的option命名,而第一个configure方法就未命名的方法,通过上面的代码可知它实际上是传入了一个默认的options.options.defaultname作为名称,这个默认值是一个空字符串,也就是说,未命名的option相当于是被命名为空字符串。最终都是按照已命名的方式也就是第二个configure方法进行处理。还有一个configureall方法,它是传入了一个null作为option的名称,也是交由第二个configure处理。
在第二个configure方法中仍调用了一次addoptions方法,然后才是将具体的类型进行注入。addoptions方法中采用的都是tryadd方法进行注入,已被注入的不会被再次注入。接下来注册了一个iconfigureoptions<toptions>接口,对应的实现是configurenamedoptions<toptions>(name, configureoptions),它的代码如下:
public class configurenamedoptions<toptions> : iconfigurenamedoptions<toptions> where toptions : class { 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 (options == null) { throw new argumentnullexception(nameof(options)); } // null name is used to configure all named options. if (name == null || name == name) { action?.invoke(options); } } public void configure(toptions options) => configure(options.defaultname, options); }
它在构造方法中存储了配置的名称(name)和创建方法(action),它的两个configure方法用于在获取options的值的时候执行对应的action来创建实例(例如示例中的theme)。在此时不会被执行。所以在此会出现3中类型的configurenamedoptions,分别是name值为具体值的、name值为为空字符串的和name值为null的。这分别对应了第一节的例子中的为option命名的configure方法、不为option命名的configure方法、以及configureall方法。
此处用到的optionsservicecollectionextensions和configurenamedoptions对应的是通过代码直接注册option的方式,例如第一节例子中的如下方式:
services.configure<theme>("themeblack", theme => { new theme { color = "#000000", name = "black" }; });
如果是以configuration作为数据源的方式,例如如下代码
services.configure<theme>("themeblue", configuration.getsection("themes:0"));
用到的是optionsservicecollectionextensions和configurenamedoptions这两个类的子类,分别为optionsconfigurationservicecollectionextensions和namedconfigurefromconfigurationoptions两个类,通过它们的名字也可以知道是专门用于采用configuration作为数据源用的,代码类似,只是多了一条关于ioptionschangetokensource的依赖注入,作用是将configuration的关于数据源变化的监听和options的关联起来,当数据源发生改变的时候可以及时更新options中的值,主要的configure方法代码如下:
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)); }
同样还有postconfigure和postconfigureall方法,和configure、configureall方法类似,只不过注入的类型为ipostconfigureoptions<toptions>。
2. options值的获取
option值的获取也就是从依赖注入容器中获取相应实现的过程。通过依赖注入阶段,已经知道了ioptions<>和ioptionssnapshot<>对应的实现是optionsmanager<>,就以optionsmanager<>为例看一下依赖注入后的服务提供过程。optionsmanager<>代码如下:
public class optionsmanager<toptions> : ioptions<toptions>, ioptionssnapshot<toptions> where toptions : class, new() { private readonly ioptionsfactory<toptions> _factory; private readonly optionscache<toptions> _cache = new optionscache<toptions>(); 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)); } }
它有ioptionsfactory<toptions>和optionscache<toptions>两个重要的成员。如果直接获取value值,实际上是调用的另一个get(string name)方法,传入了空字符串作为name值。所以最终值的获取还是在缓存中读取,这里的代码是_cache.getoradd(name, () => _factory.create(name)),即如果缓存中存在对应的值,则返回,如果不存在,则由_factory去创建。optionsfactory<toptions>的代码如下:
public class optionsfactory<toptions> : ioptionsfactory<toptions> where toptions : class, new() { private readonly ienumerable<iconfigureoptions<toptions>> _setups; private readonly ienumerable<ipostconfigureoptions<toptions>> _postconfigures; private readonly ienumerable<ivalidateoptions<toptions>> _validations; public optionsfactory(ienumerable<iconfigureoptions<toptions>> setups, ienumerable<ipostconfigureoptions<toptions>> postconfigures) : this(setups, postconfigures, validations: null) { } public optionsfactory(ienumerable<iconfigureoptions<toptions>> setups, ienumerable<ipostconfigureoptions<toptions>> postconfigures, ienumerable<ivalidateoptions<toptions>> validations) { _setups = setups; _postconfigures = postconfigures; _validations = validations; } public toptions create(string name) { var options = new toptions(); 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); } if (_validations != null) { var failures = new list<string>(); foreach (var validate in _validations) { var result = validate.validate(name, options); if (result.failed) { failures.addrange(result.failures); } } if (failures.count > 0) { throw new optionsvalidationexception(name, typeof(toptions), failures); } } return options; } }
主要看它的toptions create(string name)方法。这里会遍历它的_setups集合,这个集合类型为ienumerable<iconfigureoptions<toptions>>,在讲options模式的依赖注入的时候已经知道,每一个configure、configureall实际上就是向依赖注入容器中注册了一个iconfigureoptions<toptions>,只是名称可能不同。而postconfigure和postconfigureall方法注册的是ipostconfigureoptions<toptions>类型,对应的就是_postconfigures集合。
首先会遍历_setups集合,调用iconfigureoptions<toptions>的configure方法,这个方法的主要代码就是:
if (name == null || name == name) { action?.invoke(options); }
如果name值为null,即对应的是configureall方法,则执行该action。或者name值和需要读取的值相同,则执行该action。
_setups集合遍历之后,同样的机制遍历_postconfigures集合。这就是上一节关于configure、configureall、postconfigure和postconfigureall的执行顺序的验证。
最终返回对应的实例并写入缓存。这就是ioptions和ioptionssnapshot两种模式的处理机制,接下来看一下ioptionsmonitor模式,它对应的实现是optionsmonitor。代码如下:
public class optionsmonitor<toptions> : ioptionsmonitor<toptions> where toptions : class, new() { private readonly ioptionsmonitorcache<toptions> _cache; private readonly ioptionsfactory<toptions> _factory; private readonly ienumerable<ioptionschangetokensource<toptions>> _sources; 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; } 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; } }
大部分功能和optionsmanager类似,只是由于它是采用了singleton模式,所以它是采用监听数据源改变并更新的模式。当通过configuration作为数据源注册option的时候,多了一条ioptionschangetokensource的依赖注入。当数据源发生改变的时候更新数据并触发onchange(action<toptions, string> listener),在第一节的数据更新提醒中有相关的例子。