IOptions<TestOptions> wrapper
【ASP.NET Core】选项模式的相关接口
在 .NET 中，配置与选项模式其实有联系的（这些功能现在不仅限于 ASP.NET Core，而是作为平台扩展来提供，在其他.NET 项目中都能用）。配置一般从多个来源（上一篇水文中的例子，记得否？）来读取数据，最后以 Key - Value 的方式加载到应用程序中，然后应用程序可以读取配置。这些来源有 JSON文件、XML文件等。上次老周还演示了 CSV 文件。
而选项模式呢，说直白些就是一些简单的类，多数情况下只定义些公共属性，可以称为选项类（从泛型约束而言，选项类的要求一般就是 class，也就是类型是类的就行）。这些类其根本作用也是用来配置应用程序的，只是它们以面向对象的方式把配置信息封装起来。也就是说，选项类可以与配置信息做绑定。
咱们在定义选项类的时候，习惯让类名以“Options”结尾。这也不是什么硬规则，只不过易于理解罢了。你看到某个类以“Options”结尾，你就可以猜到它的用处——设定选项参数用的，其实也就是配置。
假设有这么个类。
public class TestOptions
{
public int Key1 { get; set; }
public string? Key2 { get; set; }
}
看着很是简单，就两个属性。
在 appsettings.json 文件中，我们可以加上这样一个节点：
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*",
"myConfig": {
"key1": 5055,
"key2": "Speaking Chinglish"
}
}
如你所见，“myConfig” 节点对应的那个 JObject 的属性结构和 TestOptions 类相同。
appsettings.json 在应用程序初始化时是自动添加的，我们不需要再配置，直接改文件就行，不用再添代码。IConfiguration 接口有个扩展方法 Bind，可以将配置信息与某个类型对象直接绑定。
app.MapGet("/", () =>
{
IConfigurationRoot config = (IConfigurationRoot)app.Configuration;
// 找出我们要的节
IConfigurationSection myconfig = config.GetSection("myConfig");
TestOptions options = new();
// 直接绑定
myconfig.Bind(options);
// 看看结果
return $"Key1 = {options.Key1}\nKey2 = {options.Key2}";
});
从 JSON 文件读出的配置信息可以直接与 TestOptions 实例绑定。这样，在代码运行后，能看到咱们刚刚在 JSON 文件中设置的内容。
上面这种方法虽然能做到了绑定，但用起来还费劲。为啥不直接弄进服务容器中，来个依赖注入，岂不美哉？
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.Configure<TestOptions>(builder.Configuration.GetSection("myConfig"));
var app = builder.Build();
Configure<TOptions> 是个扩展方法，它用来对选项类进行配置——就是为选项类的属性赋值。选项模式不仅限于把配置信息强类型化，它通用于应用程序内各种功能配置。如日志怎么记录、验证策略、Cookie 策略等。
这里注意在依赖注入时，我们不是直接用 TestOptions 类型，而是 IOptions<TOptions> 接口。比如，我们可以在 MVC 控制器中这样玩：
public class HomeController : Controller
{
readonly TestOptions _options;
// 构造函数，获取注入的对象
public HomeController(IOptions<TestOptions> wrapper)
{
_options = wrapper.Value;
}
public IActionResult Index()
{
// 这里访问选项
string s = $"Key1: {_options.Key1}\n";
s += $"Key2: {_options.Key2}";
return Content(s);
}
}
其实，咱们可以用的接口类型并不只有 IOptions<>，不妨看看 AddOptions 扩展方法的源代码（OptionsServiceCollectionExtensions.cs）
public static IServiceCollection AddOptions(this IServiceCollection services)
{
ThrowHelper.ThrowIfNull(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<> 接口，在容器中注册时用的就是这个接口嘛。其实，你可以用 IOptionsMonitor<TestOptions>。至于这几个接口有啥区别，我们先不管，下一个世纪再告诉你。
AddOptions 方法我们一般不需要调用，ASP.NET Core 应用程序初始化时自动调用了。
为了使选项模式有更好的适用性，我们也可以通过委托来配置选项类。
builder.Services.Configure<TestOptions>(opt =>
{
opt.Key1 = 999;
opt.Key2 = "Hi, baby";
});
至此，Configure 方法的两种用法就出来了：
1、用 IConfigure 对象，从配置信息源中加载，并填充选项类的属性值（这个挺像反序列化操作）；
2、直接用委托。
不管是配置信息还是委托，Configure 方法只是向服务容器添加了一组 IConfigureOptions<TOptions> 对象。它的实现类型有 ConfigureOptions<TOptions>、ConfigureNamedOptions<TOptions> 等。
我们以 ConfigureOptions<TOptions> 类为例分析一下，因为这个类比较简单
public class ConfigureOptions<TOptions> : IConfigureOptions<TOptions> where TOptions : class
{
public ConfigureOptions(Action<TOptions>? action)
{
Action = action;
}
public Action<TOptions>? Action { get; }
public virtual void Configure(TOptions options)
{
……
Action?.Invoke(options);
}
}
看到构造函数时，你有没有发现点什么？看，它是不是有个委托 Action<TOptions>，我们再回头看看刚刚我们在服务容器调用的 Configure 扩展方法，它是不是有一个重载版本也有个 Action<TOptions> 的参数。
builder.Services.Configure<TestOptions>(opt =>
{
opt.Key1 = 999;
opt.Key2 = "Hi, baby";
});
对的，我们传给它的委托就是传到了 ConfigureOptions 的构造函数里，ConfigureOptions 实现的就是 IConfigureOptions<TOptions> 接口。哦，原来是籍样子滴。我们每调用一次 Configure 方法，它就向容器注册一个 IConfigureOptions。
这只是放进了容器中罢了，并没有马上执行我们写的委托。
那，它们在哪里被调用呢？在工厂里面——IOptionsFactory<TOptions>。
public interface IOptionsFactory<TOptions>
where TOptions : class
{
TOptions Create(string name);
}
别小看这货，它可是核心角色。选项类的实例就是由它来创建的（实现 Create 方法）。你会注意到，这里有个 name 参数，干吗的？这个是为选项的命名分组准备。一般可以不理会它，除非你要实现不同分组产生不太一样的选项类实例，这样就用得上了。
其实，如果需要，我们不妨为 TestOptions 类写个小工厂（家庭小作坊）。
public class TestOptionsFactory : IOptionsFactory<TestOptions>
{
public TestOptions Create(string name)
{
return new TestOptions();
}
}
简单吧，然后咱用呢，不用管它咋用，你只要注册到服务容器中就行了。
var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllers(); builder.Services.AddTransient<IOptionsFactory<TestOptions>, TestOptionsFactory>();
这里我注册为暂时性服务，你也可以考虑注册为其他的，不冲突就行。
你要是有疑问，我自定义的工厂它会执行吗？会的，不信打个断点看看。
然后运行程序，瞧，这不，停下来了。
可，可，可是，这TNND，为什么是默认值，我刚刚不是 Configure 用委托设置了吗？
builder.Services.Configure<TestOptions>(opt =>
{
opt.Key1 = 999;
opt.Key2 = "Hi, baby";
});
无效？出啥故障了？等等，刚刚是不是说了，Configure 方法每调用一次就会注册一个 IConfigureOptions<TOptions> 吗？
想起来了，所以我们的工厂要改造一下，通过依赖注入把这一堆 IConfigureOptions 弄进来，然后逐个调用，这样就可以为选项类的属性赋值了。
public class TestOptionsFactory : IOptionsFactory<TestOptions>
{
readonly IEnumerable<IConfigureOptions<TestOptions>> _configs;
public TestOptionsFactory(IEnumerable<IConfigureOptions<TestOptions>> configs)
{
_configs = configs;
}
public TestOptions Create(string name)
{
TestOptions opt = new();
foreach(var cfg in _configs)
{
cfg.Configure(opt);
}
return opt;
}
}
看，这就成了。
其实，工厂所需要的依赖对象并不只有 IConfigureOptions，还有两个接口，需要了解一下：
1、IPostConfigureOptions：这货史称“后期配置”。其用法和 IConfigureOptions 一样的。对应的服务容器扩展方法是 PostConfigure<TOptions>，用法和 Configure<TOptions> 扩展方法完全一样的。它的用途是进行选项配置后做一些“修修补补”。比如，看看你还有哪些属性没赋值的，给它安排个默认值。有人会说，那我在创建选项类实例时就为每个属性分配默认值不就行了吗？还要啥后期配置？举个例子：
public class ProgressOptions
{
public int Max { get; set; }
public int Min { get; set; }
public int Current { get; set; }
}
就算我在工厂类中实例化时分配 Max = 100, Min = 0, Current = 50。那，如果我配置的时候是这样的呢：
builder.Services.Configure<ProgressOptions>(o =>
{
o.Max = 60;
o.Min = 0;
});
假如我没设置 Current 属性，默认规则是它取中值，那这时候取中值 50 显然就不行了。而是得根据 Max 和 Min 的值来决定。这时候用后期配置就很必要了。
builder.Services.PostConfigure<ProgressOptions>(o =>
{
o.Current = (o.Max - o.Min) / 2;
});
2、IValidateOptions：这货用来做验证用的。这个和上面的“修修补补”不同。验证是检查选项类的属性值是否符合要求。如果不符合，直接给你来个异常——回炉重造。
我们不妨看看默认的工作是怎么实现的。
public class OptionsFactory<[DynamicallyAccessedMembers(Options.DynamicallyAccessedMembers)] TOptions> :
IOptionsFactory<TOptions>
where TOptions : class
{
private readonly IConfigureOptions<TOptions>[] _setups;
private readonly IPostConfigureOptions<TOptions>[] _postConfigures;
private readonly IValidateOptions<TOptions>[] _validations;
public OptionsFactory(IEnumerable<IConfigureOptions<TOptions>> setups, IEnumerable<IPostConfigureOptions<TOptions>> postConfigures) : this(setups, postConfigures, validations: Array.Empty<IValidateOptions<TOptions>>())
{ }
public OptionsFactory(IEnumerable<IConfigureOptions<TOptions>> setups, IEnumerable<IPostConfigureOptions<TOptions>> postConfigures, IEnumerable<IValidateOptions<TOptions>> validations)
{
_setups = setups as IConfigureOptions<TOptions>[] ?? new List<IConfigureOptions<TOptions>>(setups).ToArray();
_postConfigures = postConfigures as IPostConfigureOptions<TOptions>[] ?? new List<IPostConfigureOptions<TOptions>>(postConfigures).ToArray();
_validations = validations as IValidateOptions<TOptions>[] ?? new List<IValidateOptions<TOptions>>(validations).ToArray();
}
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);
}
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;
}
/// <summary>
/// 这里是创建选项类实例的地方，为了通用化，它用了 Activator
/// </summary>
protected virtual TOptions CreateInstance(string name)
{
return Activator.CreateInstance<TOptions>();
}
}
从其源码我们知道它们的执行顺序：
N多个IConfigureOptions ---> N多个IPostConfigureOptions ---> N多个IValidateOptions。
好了，下面咱们解决最后一个疑问：选项类的实例怎么跑到 IOptions<TOptions> 里面的？通过前面的例子，咱们都知道，通过依赖注入访问选项类时，是通过 IOptions<> 等接口的。咋关联起来的？还是跟 Factory 有关，不然就不会说它是核心角色。
这里老周只说一对服务类型，其他的实现类似。在 AddOptions 扩展方法中，通过注册的服务类型得知，IOptions<> 对应的是 UnnamedOptionsManager。这个类没有公开，它的源码如下：
internal sealed class UnnamedOptionsManager<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);
}
}
}
}
现在知道它们怎么关联起来了吧——还是一样的套路，用依赖注入。
经过老周上文一系列胡说八道，这些与选项模式有关的接口之间的关系就清晰了。
