【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);
                }
            }
        }
    }

现在知道它们怎么关联起来了吧——还是一样的套路，用依赖注入。

经过老周上文一系列胡说八道，这些与选项模式有关的接口之间的关系就清晰了。

【ASP.NET Core】选项模式的相关接口 - 东邪独孤

【ASP.NET Core】选项模式的相关接口

Recommend

Find External Data for Machine Learning Pipelines

芯之所向·数智未来|第五届数字中国建设峰会 “泉州之夜”论坛在福建省福州市成功举办-品...

轩灵珠宝布局元宇宙跨入品牌3.0时代-品玩

Intel Raptor Lake CPUs could be on shelves come October 17

Efficient Dehumidifier Makes Air Conditioning a Breeze | PNNL

Announcing Windows 11 Insider Preview Build 25163

Xbox Alpha Insiders get new OS build with updated controller firmware

Genshin Impact developer miHoYo ramp up hiring plans for its metaverse headquart...

过期食品问题再遭处罚，必胜客会成为“必剩客”吗？

Cocos 虚拟角色业务总监倪飞：虚拟角色开发工具提升元宇宙应用落地效率

About Joyk