ASP.NET Core Options模式
谢友海 人气:0本章将和大家分享ASP.NET Core中Options模式的使用及其源码解析。
在ASP.NET Core中引入了Options这一使用配置方式,其主要是为了解决依赖注入时需要传递指定数据问题(不是自行获取,而是能集中配置)。通常来讲我们会把所需要的配置通过IConfiguration对象配置成一个普通的类,并且习惯上我们会把这个类的名字后缀加上Options。所以我们在使用某一个中间件或者使用第三方类库时,经常会看到配置对应的Options代码,例如:关于Cookie的中间件就会配置CookiePolicyOptions这个对象。
1、Options模式的用法
向服务容器中注入TOptions配置(绑定配置):
using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Hosting; using Microsoft.Extensions.Configuration; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Newtonsoft.Json; using Newtonsoft.Json.Serialization; using IConfiguration_IOptions_Demo.Models; namespace IConfiguration_IOptions_Demo { public class Startup { public Startup(IConfiguration configuration) { Configuration = configuration; } public IConfiguration Configuration { get; } // This method gets called by the runtime. Use this method to add services to the container. public void ConfigureServices(IServiceCollection services) #region Options模式 services.PostConfigureAll<AppSettingsOptions>(options => options.Title = "PostConfigureAll"); services.Configure<AppSettingsOptions>(Configuration); services.Configure<OtherConfig>(Configuration.GetSection("OtherConfig")); services.Configure<AppSettingsOptions>(options => options.Title = "Default Name");//默认名称string.Empty services.Configure<AppSettingsOptions>("FromMemory", options => options.Title = "FromMemory"); services.AddOptions<AppSettingsOptions>("AddOption").Configure(options => options.Title = "AddOptions"); services.Configure<OtherConfig>("FromConfiguration", Configuration.GetSection("OtherConfig")); services.ConfigureAll<AppSettingsOptions>(options => options.Title = "ConfigureAll"); services.PostConfigure<AppSettingsOptions>(options => options.Title = "PostConfigure"); #endregion Options模式 services .AddControllersWithViews() .AddRazorRuntimeCompilation() //修改cshtml后能自动编译 .AddNewtonsoftJson(options => { options.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore;//忽略循环引用 options.SerializerSettings.NullValueHandling = NullValueHandling.Ignore;//序列化忽略null和空字符串 options.SerializerSettings.MissingMemberHandling = MissingMemberHandling.Ignore; options.SerializerSettings.ContractResolver = new DefaultContractResolver();//不使用驼峰样式的key }); // This method gets called by the runtime. Use this method to configure the HTTP request pipeline. public void Configure(IApplicationBuilder app, IWebHostEnvironment env) if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } else app.UseExceptionHandler("/Home/Error"); app.UseStaticFiles(); app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => endpoints.MapControllerRoute( name: "default", pattern: "{controller=Home}/{action=Index}/{id?}"); }); } }
从服务容器中获取TOptions对象(读取配置):
using Microsoft.AspNetCore.Mvc; using Microsoft.Extensions.Options; using IConfiguration_IOptions_Demo.Models; using Newtonsoft.Json; using System.Text; namespace IConfiguration_IOptions_Demo.Controllers { public class OptionsDemoController : Controller { protected readonly IOptions<AppSettingsOptions> _options; //直接单例,不支持数据变化,性能高 protected readonly IOptionsMonitor<AppSettingsOptions> _optionsMonitor; //支持数据修改,靠的是监听文件更新(onchange)数据(修改配置文件会更新缓存) protected readonly IOptionsSnapshot<AppSettingsOptions> _optionsSnapshot; //一次请求数据不变的,但是不同请求可以不同的,每次生成 protected readonly IOptions<OtherConfig> _optionsOtherConfig; public OptionsDemoController( IOptions<AppSettingsOptions> options, IOptionsMonitor<AppSettingsOptions> optionsMonitor, IOptionsSnapshot<AppSettingsOptions> optionsSnapshot, IOptions<OtherConfig> optionsOtherConfig) { _options = options; _optionsMonitor = optionsMonitor; _optionsSnapshot = optionsSnapshot; _optionsOtherConfig = optionsOtherConfig; } public IActionResult Index() var sb = new StringBuilder(); AppSettingsOptions options1 = _options.Value; OtherConfig otherConfigOptions1 = _optionsOtherConfig.Value; sb.AppendLine($"_options.Value => {JsonConvert.SerializeObject(options1)}"); sb.AppendLine(""); sb.AppendLine($"_optionsOtherConfig.Value => {JsonConvert.SerializeObject(otherConfigOptions1)}"); AppSettingsOptions options2 = _optionsMonitor.CurrentValue; //_optionsMonitor.Get(Microsoft.Extensions.Options.Options.DefaultName); AppSettingsOptions fromMemoryOptions2 = _optionsMonitor.Get("FromMemory"); //命名选项 sb.AppendLine($"_optionsMonitor.CurrentValue => {JsonConvert.SerializeObject(options2)}"); sb.AppendLine($"_optionsMonitor.Get(\"FromMemory\") => {JsonConvert.SerializeObject(fromMemoryOptions2)}"); AppSettingsOptions options3 = _optionsSnapshot.Value; //_optionsSnapshot.Get(Microsoft.Extensions.Options.Options.DefaultName); AppSettingsOptions fromMemoryOptions3 = _optionsSnapshot.Get("FromMemory"); //命名选项 sb.AppendLine($"_optionsSnapshot.Value => {JsonConvert.SerializeObject(options3)}"); sb.AppendLine($"_optionsSnapshot.Get(\"FromMemory\") => {JsonConvert.SerializeObject(fromMemoryOptions3)}"); return Content(sb.ToString()); } }
访问 “/OptionsDemo/Index” 运行结果如下所示:
2、Options模式源码解析
我们从下面的这条语句开始分析:
services.Configure<AppSettingsOptions>(options => options.Title = "Default Name");
将光标移动到Configure 然后按 F12 转到定义,如下:
可以发现此Configure 是个扩展方法,位于OptionsServiceCollectionExtensions 类中,我们找到OptionsServiceCollectionExtensions 类的源码如下:
// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System; using System.Collections.Generic; using System.Linq; using System.Reflection; using Microsoft.Extensions.DependencyInjection.Extensions; using Microsoft.Extensions.Options; namespace Microsoft.Extensions.DependencyInjection { /// <summary> /// Extension methods for adding options services to the DI container. /// </summary> public static class OptionsServiceCollectionExtensions { /// <summary> /// Adds services required for using options. /// </summary> /// <param name="services">The <see cref="IServiceCollection"/> to add the services to.</param> /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns> 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; } /// Registers an action used to configure a particular type of options. /// Note: These are run before all <seealso cref="PostConfigure{TOptions}(IServiceCollection, Action{TOptions})"/>. /// <typeparam name="TOptions">The options type to be configured.</typeparam> /// <param name="configureOptions">The action used to configure the options.</param> public static IServiceCollection Configure<TOptions>(this IServiceCollection services, Action<TOptions> configureOptions) where TOptions : class => services.Configure(Options.Options.DefaultName, configureOptions); /// <param name="name">The name of the options instance.</param> public static IServiceCollection Configure<TOptions>(this IServiceCollection services, string name, Action<TOptions> configureOptions) where TOptions : class if (configureOptions == null) throw new ArgumentNullException(nameof(configureOptions)); services.AddOptions(); services.AddSingleton<IConfigureOptions<TOptions>>(new ConfigureNamedOptions<TOptions>(name, configureOptions)); /// Registers an action used to configure all instances of a particular type of options. public static IServiceCollection ConfigureAll<TOptions>(this IServiceCollection services, Action<TOptions> configureOptions) where TOptions : class => services.Configure(name: null, configureOptions: configureOptions); /// Registers an action used to initialize a particular type of options. /// Note: These are run after all <seealso cref="Configure{TOptions}(IServiceCollection, Action{TOptions})"/>. public static IServiceCollection PostConfigure<TOptions>(this IServiceCollection services, Action<TOptions> configureOptions) where TOptions : class => services.PostConfigure(Options.Options.DefaultName, configureOptions); /// <typeparam name="TOptions">The options type to be configure.</typeparam> public static IServiceCollection PostConfigure<TOptions>(this IServiceCollection services, string name, Action<TOptions> configureOptions) services.AddSingleton<IPostConfigureOptions<TOptions>>(new PostConfigureOptions<TOptions>(name, configureOptions)); /// Registers an action used to post configure all instances of a particular type of options. public static IServiceCollection PostConfigureAll<TOptions>(this IServiceCollection services, Action<TOptions> configureOptions) where TOptions : class => services.PostConfigure(name: null, configureOptions: configureOptions); /// Registers a type that will have all of its I[Post]ConfigureOptions registered. /// <typeparam name="TConfigureOptions">The type that will configure options.</typeparam> public static IServiceCollection ConfigureOptions<TConfigureOptions>(this IServiceCollection services) where TConfigureOptions : class => services.ConfigureOptions(typeof(TConfigureOptions)); private static bool IsAction(Type type) => (type.GetTypeInfo().IsGenericType && type.GetGenericTypeDefinition() == typeof(Action<>)); private static IEnumerable<Type> FindIConfigureOptions(Type type) var serviceTypes = type.GetTypeInfo().ImplementedInterfaces .Where(t => t.GetTypeInfo().IsGenericType && (t.GetGenericTypeDefinition() == typeof(IConfigureOptions<>) || t.GetGenericTypeDefinition() == typeof(IPostConfigureOptions<>))); if (!serviceTypes.Any()) throw new InvalidOperationException( IsAction(type) ? Resources.Error_NoIConfigureOptionsAndAction : Resources.Error_NoIConfigureOptions); return serviceTypes; /// <param name="configureType">The type that will configure options.</param> public static IServiceCollection ConfigureOptions(this IServiceCollection services, Type configureType) var serviceTypes = FindIConfigureOptions(configureType); foreach (var serviceType in serviceTypes) services.AddTransient(serviceType, configureType); /// Registers an object that will have all of its I[Post]ConfigureOptions registered. /// <param name="configureInstance">The instance that will configure options.</param> public static IServiceCollection ConfigureOptions(this IServiceCollection services, object configureInstance) var serviceTypes = FindIConfigureOptions(configureInstance.GetType()); services.AddSingleton(serviceType, configureInstance); /// Gets an options builder that forwards Configure calls for the same <typeparamref name="TOptions"/> to the underlying service collection. /// <returns>The <see cref="OptionsBuilder{TOptions}"/> so that configure calls can be chained in it.</returns> public static OptionsBuilder<TOptions> AddOptions<TOptions>(this IServiceCollection services) where TOptions : class => services.AddOptions<TOptions>(Options.Options.DefaultName); /// Gets an options builder that forwards Configure calls for the same named <typeparamref name="TOptions"/> to the underlying service collection. public static OptionsBuilder<TOptions> AddOptions<TOptions>(this IServiceCollection services, string name) return new OptionsBuilder<TOptions>(services, name); } } Microsoft.Extensions.DependencyInjection.OptionsServiceCollectionExtensions类源码
仔细阅读上面的源码后可以发现,Configure方法虽然有多个重载,但最终都会调用下面的这个方法:
/// <summary> /// Registers an action used to configure a particular type of options. /// Note: These are run before all <seealso cref="PostConfigure{TOptions}(IServiceCollection, Action{TOptions})"/>. /// </summary> /// <typeparam name="TOptions">The options type to be configured.</typeparam> /// <param name="services">The <see cref="IServiceCollection"/> to add the services to.</param> /// <param name="name">The name of the options instance.</param> /// <param name="configureOptions">The action used to configure the options.</param> /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns> public static IServiceCollection Configure<TOptions>(this IServiceCollection services, string name, Action<TOptions> configureOptions) where TOptions : class { if (services == null) { throw new ArgumentNullException(nameof(services)); } if (configureOptions == null) { throw new ArgumentNullException(nameof(configureOptions)); } services.AddOptions(); services.AddSingleton<IConfigureOptions<TOptions>>(new ConfigureNamedOptions<TOptions>(name, configureOptions)); return services; }
Configure方法的多个重载主要差异在于name参数值的不同。当不传递name参数值时,默认使用Microsoft.Extensions.Options.Options.DefaultName,它等于string.Empty,如下所示:
/// <summary> /// Registers an action used to configure a particular type of options. /// Note: These are run before all <seealso cref="PostConfigure{TOptions}(IServiceCollection, Action{TOptions})"/>. /// </summary> /// <typeparam name="TOptions">The options type to be configured.</typeparam> /// <param name="services">The <see cref="IServiceCollection"/> to add the services to.</param> /// <param name="configureOptions">The action used to configure the options.</param> /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns> public static IServiceCollection Configure<TOptions>(this IServiceCollection services, Action<TOptions> configureOptions) where TOptions : class => services.Configure(Options.Options.DefaultName, configureOptions);
// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. namespace Microsoft.Extensions.Options { /// <summary> /// Helper class. /// </summary> public static class Options { /// <summary> /// The default name used for options instances: "". /// </summary> public static readonly string DefaultName = string.Empty; /// Creates a wrapper around an instance of <typeparamref name="TOptions"/> to return itself as an <see cref="IOptions{TOptions}"/>. /// <typeparam name="TOptions">Options type.</typeparam> /// <param name="options">Options object.</param> /// <returns>Wrapped options object.</returns> public static IOptions<TOptions> Create<TOptions>(TOptions options) where TOptions : class, new() { return new OptionsWrapper<TOptions>(options); } } }
另外,我们可以看到ConfigureAll这个方法,此方法的内部也是调用Configure方法,只不过把name值设置成null,后续在创建TOptions时,会把name值为null的Action<TOptions>应用于所有实例。如下:
/// <summary> /// Registers an action used to configure all instances of a particular type of options. /// </summary> /// <typeparam name="TOptions">The options type to be configured.</typeparam> /// <param name="services">The <see cref="IServiceCollection"/> to add the services to.</param> /// <param name="configureOptions">The action used to configure the options.</param> /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns> public static IServiceCollection ConfigureAll<TOptions>(this IServiceCollection services, Action<TOptions> configureOptions) where TOptions : class => services.Configure(name: null, configureOptions: configureOptions);
至此我们大概知道了,其实Configure方法主要就是做两件事:
1、调用services.AddOptions()方法。
2、将 new ConfigureNamedOptions<TOptions>(name, configureOptions) 注册给IConfigureOptions<TOptions> 。
此外,从OptionsServiceCollectionExtensions类的源码中我们可以发现PostConfigure方法同样有多个重载,并且最终都会调用下面的这个方法:
/// <summary> /// Registers an action used to configure a particular type of options. /// Note: These are run after all <seealso cref="Configure{TOptions}(IServiceCollection, Action{TOptions})"/>. /// </summary> /// <typeparam name="TOptions">The options type to be configure.</typeparam> /// <param name="services">The <see cref="IServiceCollection"/> to add the services to.</param> /// <param name="name">The name of the options instance.</param> /// <param name="configureOptions">The action used to configure the options.</param> /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns> public static IServiceCollection PostConfigure<TOptions>(this IServiceCollection services, string name, Action<TOptions> configureOptions) where TOptions : class { if (services == null) { throw new ArgumentNullException(nameof(services)); } if (configureOptions == null) throw new ArgumentNullException(nameof(configureOptions)); services.AddOptions(); services.AddSingleton<IPostConfigureOptions<TOptions>>(new PostConfigureOptions<TOptions>(name, configureOptions)); return services; }
与Configure方法一样,PostConfigure方法的多个重载主要差异在于name参数值的不同。当不传递name参数值时,默认使用Microsoft.Extensions.Options.Options.DefaultName,它等于string.Empty,如下:
/// <summary> /// Registers an action used to initialize a particular type of options. /// Note: These are run after all <seealso cref="Configure{TOptions}(IServiceCollection, Action{TOptions})"/>. /// </summary> /// <typeparam name="TOptions">The options type to be configured.</typeparam> /// <param name="services">The <see cref="IServiceCollection"/> to add the services to.</param> /// <param name="configureOptions">The action used to configure the options.</param> /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns> public static IServiceCollection PostConfigure<TOptions>(this IServiceCollection services, Action<TOptions> configureOptions) where TOptions : class => services.PostConfigure(Options.Options.DefaultName, configureOptions);
同样的,PostConfigureAll方法的内部也是调用PostConfigure方法,只不过把name值设置成null,如下:
/// <summary> /// Registers an action used to post configure all instances of a particular type of options. /// Note: These are run after all <seealso cref="Configure{TOptions}(IServiceCollection, Action{TOptions})"/>. /// </summary> /// <typeparam name="TOptions">The options type to be configured.</typeparam> /// <param name="services">The <see cref="IServiceCollection"/> to add the services to.</param> /// <param name="configureOptions">The action used to configure the options.</param> /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns> public static IServiceCollection PostConfigureAll<TOptions>(this IServiceCollection services, Action<TOptions> configureOptions) where TOptions : class => services.PostConfigure(name: null, configureOptions: configureOptions);
至此我们可以发现,PostConfigure方法同样也是只做两件事:
1、调用services.AddOptions() 方法。
2、将new PostConfigureOptions<TOptions>(name, configureOptions) 注册给IPostConfigureOptions<TOptions> 。
其实PostConfigure方法,它和Configure方法使用方式一模一样,也是在创建TOptions时调用。只不过先后顺序不一样,PostConfigure在Configure之后调用,该点在后面的讲解中会再次提到。
另外,还有一种AddOptions的用法,如下所示:
services.AddOptions<AppSettingsOptions>("AddOption").Configure(options => options.Title = "AddOptions");
/// <summary> /// Gets an options builder that forwards Configure calls for the same <typeparamref name="TOptions"/> to the underlying service collection. /// </summary> /// <typeparam name="TOptions">The options type to be configured.</typeparam> /// <param name="services">The <see cref="IServiceCollection"/> to add the services to.</param> /// <returns>The <see cref="OptionsBuilder{TOptions}"/> so that configure calls can be chained in it.</returns> public static OptionsBuilder<TOptions> AddOptions<TOptions>(this IServiceCollection services) where TOptions : class => services.AddOptions<TOptions>(Options.Options.DefaultName); /// Gets an options builder that forwards Configure calls for the same named <typeparamref name="TOptions"/> to the underlying service collection. /// <param name="name">The name of the options instance.</param> public static OptionsBuilder<TOptions> AddOptions<TOptions>(this IServiceCollection services, string name) where TOptions : class { if (services == null) { throw new ArgumentNullException(nameof(services)); } services.AddOptions(); return new OptionsBuilder<TOptions>(services, name); }
这种方式会创建一个OptionsBuilder对象,用来辅助配置TOptions对象,我们找到OptionsBuilder类的源码如下:
Microsoft.Extensions.Options.OptionsBuilder类源码
// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System; using Microsoft.Extensions.DependencyInjection; namespace Microsoft.Extensions.Options { /// <summary> /// Used to configure <typeparamref name="TOptions"/> instances. /// </summary> /// <typeparam name="TOptions">The type of options being requested.</typeparam> public class OptionsBuilder<TOptions> where TOptions : class { private const string DefaultValidationFailureMessage = "A validation error has occured."; /// <summary> /// The default name of the <typeparamref name="TOptions"/> instance. /// </summary> public string Name { get; } /// The <see cref="IServiceCollection"/> for the options being configured. public IServiceCollection Services { get; } /// Constructor. /// <param name="services">The <see cref="IServiceCollection"/> for the options being configured.</param> /// <param name="name">The default name of the <typeparamref name="TOptions"/> instance, if null <see cref="Options.DefaultName"/> is used.</param> public OptionsBuilder(IServiceCollection services, string name) { if (services == null) { throw new ArgumentNullException(nameof(services)); } Services = services; Name = name ?? Options.DefaultName; } /// Registers an action used to configure a particular type of options. /// Note: These are run before all <seealso cref="PostConfigure(Action{TOptions})"/>. /// <param name="configureOptions">The action used to configure the options.</param> /// <returns>The current <see cref="OptionsBuilder{TOptions}"/>.</returns> public virtual OptionsBuilder<TOptions> Configure(Action<TOptions> configureOptions) if (configureOptions == null) throw new ArgumentNullException(nameof(configureOptions)); Services.AddSingleton<IConfigureOptions<TOptions>>(new ConfigureNamedOptions<TOptions>(Name, configureOptions)); return this; /// <typeparam name="TDep">A dependency used by the action.</typeparam> 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)); /// <typeparam name="TDep1">The first dependency used by the action.</typeparam> /// <typeparam name="TDep2">The second dependency used by the action.</typeparam> public virtual OptionsBuilder<TOptions> Configure<TDep1, TDep2>(Action<TOptions, TDep1, TDep2> configureOptions) where TDep1 : class where TDep2 : class new ConfigureNamedOptions<TOptions, TDep1, TDep2>(Name, sp.GetRequiredService<TDep1>(), sp.GetRequiredService<TDep2>(), configureOptions)); /// <typeparam name="TDep3">The third dependency used by the action.</typeparam> public virtual OptionsBuilder<TOptions> Configure<TDep1, TDep2, TDep3>(Action<TOptions, TDep1, TDep2, TDep3> configureOptions) where TDep3 : class Services.AddTransient<IConfigureOptions<TOptions>>( sp => new ConfigureNamedOptions<TOptions, TDep1, TDep2, TDep3>( Name, sp.GetRequiredService<TDep1>(), sp.GetRequiredService<TDep2>(), sp.GetRequiredService<TDep3>(), configureOptions)); /// <typeparam name="TDep4">The fourth dependency used by the action.</typeparam> public virtual OptionsBuilder<TOptions> Configure<TDep1, TDep2, TDep3, TDep4>(Action<TOptions, TDep1, TDep2, TDep3, TDep4> configureOptions) where TDep4 : class sp => new ConfigureNamedOptions<TOptions, TDep1, TDep2, TDep3, TDep4>( sp.GetRequiredService<TDep4>(), /// <typeparam name="TDep5">The fifth dependency used by the action.</typeparam> public virtual OptionsBuilder<TOptions> Configure<TDep1, TDep2, TDep3, TDep4, TDep5>(Action<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5> configureOptions) where TDep5 : class sp => new ConfigureNamedOptions<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5>( sp.GetRequiredService<TDep5>(), /// Note: These are run after all <seealso cref="Configure(Action{TOptions})"/>. public virtual OptionsBuilder<TOptions> PostConfigure(Action<TOptions> configureOptions) Services.AddSingleton<IPostConfigureOptions<TOptions>>(new PostConfigureOptions<TOptions>(Name, configureOptions)); /// Registers an action used to post configure a particular type of options. /// <typeparam name="TDep">The dependency used by the action.</typeparam> public virtual OptionsBuilder<TOptions> PostConfigure<TDep>(Action<TOptions, TDep> configureOptions) Services.AddTransient<IPostConfigureOptions<TOptions>>(sp => new PostConfigureOptions<TOptions, TDep>(Name, sp.GetRequiredService<TDep>(), configureOptions)); public virtual OptionsBuilder<TOptions> PostConfigure<TDep1, TDep2>(Action<TOptions, TDep1, TDep2> configureOptions) new PostConfigureOptions<TOptions, TDep1, TDep2>(Name, sp.GetRequiredService<TDep1>(), sp.GetRequiredService<TDep2>(), configureOptions)); public virtual OptionsBuilder<TOptions> PostConfigure<TDep1, TDep2, TDep3>(Action<TOptions, TDep1, TDep2, TDep3> configureOptions) Services.AddTransient<IPostConfigureOptions<TOptions>>( sp => new PostConfigureOptions<TOptions, TDep1, TDep2, TDep3>( public virtual OptionsBuilder<TOptions> PostConfigure<TDep1, TDep2, TDep3, TDep4>(Action<TOptions, TDep1, TDep2, TDep3, TDep4> configureOptions) sp => new PostConfigureOptions<TOptions, TDep1, TDep2, TDep3, TDep4>( public virtual OptionsBuilder<TOptions> PostConfigure<TDep1, TDep2, TDep3, TDep4, TDep5>(Action<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5> configureOptions) sp => new PostConfigureOptions<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5>( /// Register a validation action for an options type using a default failure message. /// <param name="validation">The validation function.</param> public virtual OptionsBuilder<TOptions> Validate(Func<TOptions, bool> validation) => Validate(validation: validation, failureMessage: DefaultValidationFailureMessage); /// Register a validation action for an options type. /// <param name="failureMessage">The failure message to use when validation fails.</param> public virtual OptionsBuilder<TOptions> Validate(Func<TOptions, bool> validation, string failureMessage) if (validation == null) throw new ArgumentNullException(nameof(validation)); Services.AddSingleton<IValidateOptions<TOptions>>(new ValidateOptions<TOptions>(Name, validation, failureMessage)); /// <typeparam name="TDep">The dependency used by the validation function.</typeparam> public virtual OptionsBuilder<TOptions> Validate<TDep>(Func<TOptions, TDep, bool> validation) public virtual OptionsBuilder<TOptions> Validate<TDep>(Func<TOptions, TDep, bool> validation, string failureMessage) Services.AddTransient<IValidateOptions<TOptions>>(sp => new ValidateOptions<TOptions, TDep>(Name, sp.GetRequiredService<TDep>(), validation, failureMessage)); /// <typeparam name="TDep1">The first dependency used by the validation function.</typeparam> /// <typeparam name="TDep2">The second dependency used by the validation function.</typeparam> public virtual OptionsBuilder<TOptions> Validate<TDep1, TDep2>(Func<TOptions, TDep1, TDep2, bool> validation) public virtual OptionsBuilder<TOptions> Validate<TDep1, TDep2>(Func<TOptions, TDep1, TDep2, bool> validation, string failureMessage) new ValidateOptions<TOptions, TDep1, TDep2>(Name, validation, failureMessage)); /// <typeparam name="TDep3">The third dependency used by the validation function.</typeparam> public virtual OptionsBuilder<TOptions> Validate<TDep1, TDep2, TDep3>(Func<TOptions, TDep1, TDep2, TDep3, bool> validation) public virtual OptionsBuilder<TOptions> Validate<TDep1, TDep2, TDep3>(Func<TOptions, TDep1, TDep2, TDep3, bool> validation, string failureMessage) new ValidateOptions<TOptions, TDep1, TDep2, TDep3>(Name, /// <typeparam name="TDep4">The fourth dependency used by the validation function.</typeparam> public virtual OptionsBuilder<TOptions> Validate<TDep1, TDep2, TDep3, TDep4>(Func<TOptions, TDep1, TDep2, TDep3, TDep4, bool> validation) public virtual OptionsBuilder<TOptions> Validate<TDep1, TDep2, TDep3, TDep4>(Func<TOptions, TDep1, TDep2, TDep3, TDep4, bool> validation, string failureMessage) new ValidateOptions<TOptions, TDep1, TDep2, TDep3, TDep4>(Name, /// <typeparam name="TDep5">The fifth dependency used by the validation function.</typeparam> public virtual OptionsBuilder<TOptions> Validate<TDep1, TDep2, TDep3, TDep4, TDep5>(Func<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5, bool> validation) public virtual OptionsBuilder<TOptions> Validate<TDep1, TDep2, TDep3, TDep4, TDep5>(Func<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5, bool> validation, string failureMessage) new ValidateOptions<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5>(Name, } } Microsoft.Extensions.Options.OptionsBuilder类源码
我们重点来看其中的一个方法,如下所示:
/// <summary> /// Registers an action used to configure a particular type of options. /// Note: These are run before all <seealso cref="PostConfigure(Action{TOptions})"/>. /// </summary> /// <param name="configureOptions">The action used to configure the options.</param> /// <returns>The current <see cref="OptionsBuilder{TOptions}"/>.</returns> public virtual OptionsBuilder<TOptions> Configure(Action<TOptions> configureOptions) { if (configureOptions == null) { throw new ArgumentNullException(nameof(configureOptions)); } Services.AddSingleton<IConfigureOptions<TOptions>>(new ConfigureNamedOptions<TOptions>(Name, configureOptions)); return this; }
可以发现其内部实现是和Configure方法一样的。
最后还有一种比较酷的用法,就是在调用Configure方法时并没有传递Action<TOptions>,而是直接传递了一个IConfiguration,如下所示:
services.Configure<AppSettingsOptions>(Configuration); services.Configure<OtherConfig>(Configuration.GetSection("OtherConfig")); services.Configure<OtherConfig>("FromConfiguration", Configuration.GetSection("OtherConfig"));
其实这是因为框架在内部帮我们转化了一下,最终传递的还是一个Action<TOptions>,下面我们就重点来看一下这个过程:
我们将光标移动到对应的 Configure 然后按 F12 转到定义,如下所示:
可以发现此Configure 是个扩展方法,位于OptionsConfigurationServiceCollectionExtensions 类中,我们找到OptionsConfigurationServiceCollectionExtensions类的源码如下:
// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System; using Microsoft.Extensions.Configuration; using Microsoft.Extensions.Options; namespace Microsoft.Extensions.DependencyInjection { /// <summary> /// Extension methods for adding configuration related options services to the DI container. /// </summary> public static class OptionsConfigurationServiceCollectionExtensions { /// <summary> /// Registers a configuration instance which TOptions will bind against. /// </summary> /// <typeparam name="TOptions">The type of options being configured.</typeparam> /// <param name="services">The <see cref="IServiceCollection"/> to add the services to.</param> /// <param name="config">The configuration being bound.</param> /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns> public static IServiceCollection Configure<TOptions>(this IServiceCollection services, IConfiguration config) where TOptions : class => services.Configure<TOptions>(Options.Options.DefaultName, config); /// <param name="name">The name of the options instance.</param> public static IServiceCollection Configure<TOptions>(this IServiceCollection services, string name, IConfiguration config) where TOptions : class => services.Configure<TOptions>(name, config, _ => { }); /// <param name="configureBinder">Used to configure the <see cref="BinderOptions"/>.</param> public static IServiceCollection Configure<TOptions>(this IServiceCollection services, IConfiguration config, Action<BinderOptions> configureBinder) where TOptions : class => services.Configure<TOptions>(Options.Options.DefaultName, config, configureBinder); public static IServiceCollection Configure<TOptions>(this IServiceCollection services, string name, IConfiguration config, Action<BinderOptions> configureBinder) { if (services == null) { throw new ArgumentNullException(nameof(services)); } if (config == null) throw new ArgumentNullException(nameof(config)); services.AddOptions(); services.AddSingleton<IOptionsChangeTokenSource<TOptions>>(new ConfigurationChangeTokenSource<TOptions>(name, config)); return services.AddSingleton<IConfigureOptions<TOptions>>(new NamedConfigureFromConfigurationOptions<TOptions>(name, config, configureBinder)); } } }
从此处我们可以看出最终它会将new NamedConfigureFromConfigurationOptions<TOptions>(name, config, configureBinder) 注册给IConfigureOptions<TOptions>,我们找到NamedConfigureFromConfigurationOptions 类的源码,如下:
// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System; using Microsoft.Extensions.Configuration; namespace Microsoft.Extensions.Options { /// <summary> /// Configures an option instance by using <see cref="ConfigurationBinder.Bind(IConfiguration, object)"/> against an <see cref="IConfiguration"/>. /// </summary> /// <typeparam name="TOptions">The type of options to bind.</typeparam> public class NamedConfigureFromConfigurationOptions<TOptions> : ConfigureNamedOptions<TOptions> where TOptions : class { /// <summary> /// Constructor that takes the <see cref="IConfiguration"/> instance to bind against. /// </summary> /// <param name="name">The name of the options instance.</param> /// <param name="config">The <see cref="IConfiguration"/> instance.</param> public NamedConfigureFromConfigurationOptions(string name, IConfiguration config) : this(name, config, _ => { }) { } /// <param name="configureBinder">Used to configure the <see cref="BinderOptions"/>.</param> public NamedConfigureFromConfigurationOptions(string name, IConfiguration config, Action<BinderOptions> configureBinder) : base(name, options => config.Bind(options, configureBinder)) { if (config == null) { throw new ArgumentNullException(nameof(config)); } } } }
从中我们可以发现其实NamedConfigureFromConfigurationOptions<TOptions> 类它是继承自ConfigureNamedOptions<TOptions> 类的,我们继续找到ConfigureNamedOptions<TOptions> 类的源码,如下:
Microsoft.Extensions.Options.ConfigureNamedOptions类源码
// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System; namespace Microsoft.Extensions.Options { /// <summary> /// Implementation of <see cref="IConfigureNamedOptions{TOptions}"/>. /// </summary> /// <typeparam name="TOptions">Options type being configured.</typeparam> public class ConfigureNamedOptions<TOptions> : IConfigureNamedOptions<TOptions> where TOptions : class { /// <summary> /// Constructor. /// </summary> /// <param name="name">The name of the options.</param> /// <param name="action">The action to register.</param> public ConfigureNamedOptions(string name, Action<TOptions> action) { Name = name; Action = action; } /// The options name. public string Name { get; } /// The configuration action. public Action<TOptions> Action { get; } /// Invokes the registered configure <see cref="Action"/> if the <paramref name="name"/> matches. /// <param name="name">The name of the options instance being configured.</param> /// <param name="options">The options instance to configure.</param> 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); /// Invoked to configure a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>. public void Configure(TOptions options) => Configure(Options.DefaultName, options); } /// <typeparam name="TDep">Dependency type.</typeparam> public class ConfigureNamedOptions<TOptions, TDep> : IConfigureNamedOptions<TOptions> where TOptions : class where TDep : class /// <param name="dependency">A dependency.</param> public ConfigureNamedOptions(string name, TDep dependency, Action<TOptions, TDep> action) Dependency = dependency; public Action<TOptions, TDep> Action { get; } /// The dependency. public TDep Dependency { get; } Action?.Invoke(options, Dependency); /// <typeparam name="TDep1">First dependency type.</typeparam> /// <typeparam name="TDep2">Second dependency type.</typeparam> public class ConfigureNamedOptions<TOptions, TDep1, TDep2> : IConfigureNamedOptions<TOptions> where TDep1 : class where TDep2 : class /// <param name="dependency2">A second dependency.</param> public ConfigureNamedOptions(string name, TDep1 dependency, TDep2 dependency2, Action<TOptions, TDep1, TDep2> action) Dependency1 = dependency; Dependency2 = dependency2; public Action<TOptions, TDep1, TDep2> Action { get; } /// The first dependency. public TDep1 Dependency1 { get; } /// The second dependency. public TDep2 Dependency2 { get; } Action?.Invoke(options, Dependency1, Dependency2); /// <typeparam name="TDep3">Third dependency type.</typeparam> public class ConfigureNamedOptions<TOptions, TDep1, TDep2, TDep3> : IConfigureNamedOptions<TOptions> where TDep3 : class /// <param name="dependency3">A third dependency.</param> public ConfigureNamedOptions(string name, TDep1 dependency, TDep2 dependency2, TDep3 dependency3, Action<TOptions, TDep1, TDep2, TDep3> action) Dependency3 = dependency3; public Action<TOptions, TDep1, TDep2, TDep3> Action { get; } /// The third dependency. public TDep3 Dependency3 { get; } Action?.Invoke(options, Dependency1, Dependency2, Dependency3); /// <typeparam name="TDep4">Fourth dependency type.</typeparam> public class ConfigureNamedOptions<TOptions, TDep1, TDep2, TDep3, TDep4> : IConfigureNamedOptions<TOptions> where TDep4 : class /// <param name="dependency1">A dependency.</param> /// <param name="dependency4">A fourth dependency.</param> public ConfigureNamedOptions(string name, TDep1 dependency1, TDep2 dependency2, TDep3 dependency3, TDep4 dependency4, Action<TOptions, TDep1, TDep2, TDep3, TDep4> action) Dependency1 = dependency1; Dependency4 = dependency4; public Action<TOptions, TDep1, TDep2, TDep3, TDep4> Action { get; } /// The fourth dependency. public TDep4 Dependency4 { get; } Action?.Invoke(options, Dependency1, Dependency2, Dependency3, Dependency4); /// <typeparam name="TDep5">Fifth dependency type.</typeparam> public class ConfigureNamedOptions<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5> : IConfigureNamedOptions<TOptions> where TDep5 : class /// <param name="dependency5">A fifth dependency.</param> public ConfigureNamedOptions(string name, TDep1 dependency1, TDep2 dependency2, TDep3 dependency3, TDep4 dependency4, TDep5 dependency5, Action<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5> action) Dependency5 = dependency5; public Action<TOptions, TDep1, TDep2, TDep3, TDep4, TDep5> Action { get; } /// The fifth dependency. public TDep5 Dependency5 { get; } Action?.Invoke(options, Dependency1, Dependency2, Dependency3, Dependency4, Dependency5); } Microsoft.Extensions.Options.ConfigureNamedOptions类源码
其中我们重点来看下面的这部分:
/// <summary> /// Implementation of <see cref="IConfigureNamedOptions{TOptions}"/>. /// </summary> /// <typeparam name="TOptions">Options type being configured.</typeparam> public class ConfigureNamedOptions<TOptions> : IConfigureNamedOptions<TOptions> where TOptions : class { /// <summary> /// Constructor. /// </summary> /// <param name="name">The name of the options.</param> /// <param name="action">The action to register.</param> public ConfigureNamedOptions(string name, Action<TOptions> action) { Name = name; Action = action; } /// The options name. public string Name { get; } /// The configuration action. public Action<TOptions> Action { get; } /// Invokes the registered configure <see cref="Action"/> if the <paramref name="name"/> matches. /// <param name="name">The name of the options instance being configured.</param> /// <param name="options">The options instance to configure.</param> 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); /// Invoked to configure a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>. public void Configure(TOptions options) => Configure(Options.DefaultName, options); }
结合NamedConfigureFromConfigurationOptions<TOptions> 和ConfigureNamedOptions<TOptions> 这两个类的源码我们可以发现:
1、 调用 services.Configure<AppSettingsOptions>(Configuration) 方法时框架在内部帮我们转化了一下,最终传递的是 “options => config.Bind(options, configureBinder)” 。
2、 调用 Configure(string name, TOptions options) 方法时会把Name值为null的Action<TOptions>应用于所有TOptions实例。
我们找到config.Bind(options, configureBinder) 这个方法,它是个扩展方法,位于ConfigurationBinder静态类中,如下:
Microsoft.Extensions.Configuration.ConfigurationBinder类源码
// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System; using System.Collections.Generic; using System.ComponentModel; using System.Linq; using System.Reflection; using Microsoft.Extensions.Configuration.Binder; namespace Microsoft.Extensions.Configuration { /// <summary> /// Static helper class that allows binding strongly typed objects to configuration values. /// </summary> public static class ConfigurationBinder { /// <summary> /// Attempts to bind the configuration instance to a new instance of type T. /// If this configuration section has a value, that will be used. /// Otherwise binding by matching property names against configuration keys recursively. /// </summary> /// <typeparam name="T">The type of the new instance to bind.</typeparam> /// <param name="configuration">The configuration instance to bind.</param> /// <returns>The new instance of T if successful, default(T) otherwise.</returns> public static T Get<T>(this IConfiguration configuration) => configuration.Get<T>(_ => { }); /// <param name="configureOptions">Configures the binder options.</param> public static T Get<T>(this IConfiguration configuration, Action<BinderOptions> configureOptions) { if (configuration == null) { throw new ArgumentNullException(nameof(configuration)); } var result = configuration.Get(typeof(T), configureOptions); if (result == null) return default(T); return (T)result; } /// <param name="type">The type of the new instance to bind.</param> /// <returns>The new instance if successful, null otherwise.</returns> public static object Get(this IConfiguration configuration, Type type) => configuration.Get(type, _ => { }); public static object Get(this IConfiguration configuration, Type type, Action<BinderOptions> configureOptions) var options = new BinderOptions(); configureOptions?.Invoke(options); return BindInstance(type, instance: null, config: configuration, options: options); /// Attempts to bind the given object instance to the configuration section specified by the key by matching property names against configuration keys recursively. /// <param name="key">The key of the configuration section to bind.</param> /// <param name="instance">The object to bind.</param> public static void Bind(this IConfiguration configuration, string key, object instance) => configuration.GetSection(key).Bind(instance); /// Attempts to bind the given object instance to configuration values by matching property names against configuration keys recursively. public static void Bind(this IConfiguration configuration, object instance) => configuration.Bind(instance, o => { }); public static void Bind(this IConfiguration configuration, object instance, Action<BinderOptions> configureOptions) if (instance != null) var options = new BinderOptions(); configureOptions?.Invoke(options); BindInstance(instance.GetType(), instance, configuration, options); /// Extracts the value with the specified key and converts it to type T. /// <typeparam name="T">The type to convert the value to.</typeparam> /// <param name="configuration">The configuration.</param> /// <param name="key">The key of the configuration section's value to convert.</param> /// <returns>The converted value.</returns> public static T GetValue<T>(this IConfiguration configuration, string key) return GetValue(configuration, key, default(T)); /// <param name="defaultValue">The default value to use if no value is found.</param> public static T GetValue<T>(this IConfiguration configuration, string key, T defaultValue) return (T)GetValue(configuration, typeof(T), key, defaultValue); /// Extracts the value with the specified key and converts it to the specified type. /// <param name="type">The type to convert the value to.</param> public static object GetValue(this IConfiguration configuration, Type type, string key) return GetValue(configuration, type, key, defaultValue: null); public static object GetValue(this IConfiguration configuration, Type type, string key, object defaultValue) var section = configuration.GetSection(key); var value = section.Value; if (value != null) return ConvertValue(type, value, section.Path); return defaultValue; private static void BindNonScalar(this IConfiguration configuration, object instance, BinderOptions options) foreach (var property in GetAllProperties(instance.GetType().GetTypeInfo())) { BindProperty(property, instance, configuration, options); } private static void BindProperty(PropertyInfo property, object instance, IConfiguration config, BinderOptions options) // We don't support set only, non public, or indexer properties if (property.GetMethod == null || (!options.BindNonPublicProperties && !property.GetMethod.IsPublic) || property.GetMethod.GetParameters().Length > 0) return; var propertyValue = property.GetValue(instance); var hasSetter = property.SetMethod != null && (property.SetMethod.IsPublic || options.BindNonPublicProperties); if (propertyValue == null && !hasSetter) // Property doesn't have a value and we cannot set it so there is no // point in going further down the graph propertyValue = BindInstance(property.PropertyType, propertyValue, config.GetSection(property.Name), options); if (propertyValue != null && hasSetter) property.SetValue(instance, propertyValue); private static object BindToCollection(TypeInfo typeInfo, IConfiguration config, BinderOptions options) var type = typeof(List<>).MakeGenericType(typeInfo.GenericTypeArguments[0]); var instance = Activator.CreateInstance(type); BindCollection(instance, type, config, options); return instance; // Try to create an array/dictionary instance to back various collection interfaces private static object AttemptBindToCollectionInterfaces(Type type, IConfiguration config, BinderOptions options) var typeInfo = type.GetTypeInfo(); if (!typeInfo.IsInterface) return null; var collectionInterface = FindOpenGenericInterface(typeof(IReadOnlyList<>), type); if (collectionInterface != null) // IEnumerable<T> is guaranteed to have exactly one parameter return BindToCollection(typeInfo, config, options); collectionInterface = FindOpenGenericInterface(typeof(IReadOnlyDictionary<,>), type); var dictionaryType = typeof(Dictionary<,>).MakeGenericType(typeInfo.GenericTypeArguments[0], typeInfo.GenericTypeArguments[1]); var instance = Activator.CreateInstance(dictionaryType); BindDictionary(instance, dictionaryType, config, options); return instance; collectionInterface = FindOpenGenericInterface(typeof(IDictionary<,>), type); var instance = Activator.CreateInstance(typeof(Dictionary<,>).MakeGenericType(typeInfo.GenericTypeArguments[0], typeInfo.GenericTypeArguments[1])); BindDictionary(instance, collectionInterface, config, options); collectionInterface = FindOpenGenericInterface(typeof(IReadOnlyCollection<>), type); // IReadOnlyCollection<T> is guaranteed to have exactly one parameter collectionInterface = FindOpenGenericInterface(typeof(ICollection<>), type); // ICollection<T> is guaranteed to have exactly one parameter collectionInterface = FindOpenGenericInterface(typeof(IEnumerable<>), type); return null; private static object BindInstance(Type type, object instance, IConfiguration config, BinderOptions options) // if binding IConfigurationSection, break early if (type == typeof(IConfigurationSection)) return config; var section = config as IConfigurationSection; var configValue = section?.Value; object convertedValue; Exception error; if (configValue != null && TryConvertValue(type, configValue, section.Path, out convertedValue, out error)) if (error != null) throw error; // Leaf nodes are always reinitialized return convertedValue; if (config != null && config.GetChildren().Any()) // If we don't have an instance, try to create one if (instance == null) // We are already done if binding to a new collection instance worked instance = AttemptBindToCollectionInterfaces(type, config, options); if (instance != null) { return instance; } instance = CreateInstance(type); // See if its a Dictionary var collectionInterface = FindOpenGenericInterface(typeof(IDictionary<,>), type); if (collectionInterface != null) BindDictionary(instance, collectionInterface, config, options); else if (type.IsArray) instance = BindArray((Array)instance, config, options); else // See if its an ICollection collectionInterface = FindOpenGenericInterface(typeof(ICollection<>), type); if (collectionInterface != null) BindCollection(instance, collectionInterface, config, options); // Something else else BindNonScalar(config, instance, options); private static object CreateInstance(Type type) if (typeInfo.IsInterface || typeInfo.IsAbstract) throw new InvalidOperationException(Resources.FormatError_CannotActivateAbstractOrInterface(type)); if (type.IsArray) if (typeInfo.GetArrayRank() > 1) throw new InvalidOperationException(Resources.FormatError_UnsupportedMultidimensionalArray(type)); return Array.CreateInstance(typeInfo.GetElementType(), 0); var hasDefaultConstructor = typeInfo.DeclaredConstructors.Any(ctor => ctor.IsPublic && ctor.GetParameters().Length == 0); if (!hasDefaultConstructor) throw new InvalidOperationException(Resources.FormatError_MissingParameterlessConstructor(type)); try return Activator.CreateInstance(type); catch (Exception ex) throw new InvalidOperationException(Resources.FormatError_FailedToActivate(type), ex); private static void BindDictionary(object dictionary, Type dictionaryType, IConfiguration config, BinderOptions options) var typeInfo = dictionaryType.GetTypeInfo(); // IDictionary<K,V> is guaranteed to have exactly two parameters var keyType = typeInfo.GenericTypeArguments[0]; var valueType = typeInfo.GenericTypeArguments[1]; var keyTypeIsEnum = keyType.GetTypeInfo().IsEnum; if (keyType != typeof(string) && !keyTypeIsEnum) // We only support string and enum keys var setter = typeInfo.GetDeclaredProperty("Item"); foreach (var child in config.GetChildren()) var item = BindInstance( type: valueType, instance: null, config: child, options: options); if (item != null) if (keyType == typeof(string)) var key = child.Key; setter.SetValue(dictionary, item, new object[] { key }); else if (keyTypeIsEnum) var key = Enum.Parse(keyType, child.Key); private static void BindCollection(object collection, Type collectionType, IConfiguration config, BinderOptions options) var typeInfo = collectionType.GetTypeInfo(); // ICollection<T> is guaranteed to have exactly one parameter var itemType = typeInfo.GenericTypeArguments[0]; var addMethod = typeInfo.GetDeclaredMethod("Add"); foreach (var section in config.GetChildren()) try var item = BindInstance( type: itemType, instance: null, config: section, options: options); if (item != null) addMethod.Invoke(collection, new[] { item }); catch private static Array BindArray(Array source, IConfiguration config, BinderOptions options) var children = config.GetChildren().ToArray(); var arrayLength = source.Length; var elementType = source.GetType().GetElementType(); var newArray = Array.CreateInstance(elementType, arrayLength + children.Length); // binding to array has to preserve already initialized arrays with values if (arrayLength > 0) Array.Copy(source, newArray, arrayLength); for (int i = 0; i < children.Length; i++) type: elementType, config: children[i], newArray.SetValue(item, arrayLength + i); return newArray; private static bool TryConvertValue(Type type, string value, string path, out object result, out Exception error) error = null; result = null; if (type == typeof(object)) result = value; return true; if (type.GetTypeInfo().IsGenericType && type.GetGenericTypeDefinition() == typeof(Nullable<>)) if (string.IsNullOrEmpty(value)) return true; return TryConvertValue(Nullable.GetUnderlyingType(type), value, path, out result, out error); var converter = TypeDescriptor.GetConverter(type); if (converter.CanConvertFrom(typeof(string))) result = converter.ConvertFromInvariantString(value); catch (Exception ex) error = new InvalidOperationException(Resources.FormatError_FailedBinding(path, type), ex); return false; private static object ConvertValue(Type type, string value, string path) object result; TryConvertValue(type, value, path, out result, out error); if (error != null) throw error; return result; private static Type FindOpenGenericInterface(Type expected, Type actual) var actualTypeInfo = actual.GetTypeInfo(); if(actualTypeInfo.IsGenericType && actual.GetGenericTypeDefinition() == expected) return actual; var interfaces = actualTypeInfo.ImplementedInterfaces; foreach (var interfaceType in interfaces) if (interfaceType.GetTypeInfo().IsGenericType && interfaceType.GetGenericTypeDefinition() == expected) return interfaceType; private static IEnumerable<PropertyInfo> GetAllProperties(TypeInfo type) var allProperties = new List<PropertyInfo>(); do allProperties.AddRange(type.DeclaredProperties); type = type.BaseType.GetTypeInfo(); while (type != typeof(object).GetTypeInfo()); return allProperties; } } Microsoft.Extensions.Configuration.ConfigurationBinder类源码
仔细阅读上面的源码你会发现,其实它是通过反射的方式为TOptions实例赋值的,而它的值则是通过IConfiguration方式获取的,如果通过IConfiguration方式没有获取到指定的值则不做任何处理还是保留原来的默认值。对于使用IConfiguration获取配置值的实现原理,这在上一篇我们已经详细的讲解过了,此处就不再做过多的介绍了。
从上文的分析中我们可以知道,不管是采用哪种绑定配置的方式其内部都会调用 services.AddOptions() 这个方法,该方法位于OptionsServiceCollectionExtensions静态类中,我们找到该方法,如下所示:
/// <summary> /// Adds services required for using options. /// </summary> /// <param name="services">The <see cref="IServiceCollection"/> to add the services to.</param> /// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns> 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; }
从中我们大概能猜出 IOptions<TOptions>、IOptionsMonitor<TOptions> 以及 IOptionsSnapshot<TOptions>这三者的主要区别:
1、IOptions在注册到容器时是以单例的形式,这种方式数据全局唯一,不支持数据变化。
2、IOptionsSnapshot在注册到容器时是以Scoped的形式,这种方式单次请求数据是不变的,但是不同的请求数据有可能是不一样的,它能觉察到配置源的改变。
3、IOptionsMonitor在注册到容器时虽然也是以单例的形式,但是它多了一个IOptionsMonitorCache缓存,它也是能觉察到配置源的改变,一旦发生改变就会告知OptionsMonitor从缓存中移除相应的对象。
下面我们继续往下分析,首先找到OptionsManager 类的源码,如下所示:
// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. namespace Microsoft.Extensions.Options { /// <summary> /// Implementation of <see cref="IOptions{TOptions}"/> and <see cref="IOptionsSnapshot{TOptions}"/>. /// </summary> /// <typeparam name="TOptions">Options type.</typeparam> 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>(); // Note: this is a private cache /// <summary> /// Initializes a new instance with the specified options configurations. /// </summary> /// <param name="factory">The factory to use to create options.</param> public OptionsManager(IOptionsFactory<TOptions> factory) { _factory = factory; } /// The default configured <typeparamref name="TOptions"/> instance, equivalent to Get(Options.DefaultName). public TOptions Value get { return Get(Options.DefaultName); } /// Returns a configured <typeparamref name="TOptions"/> instance with the given <paramref name="name"/>. public virtual TOptions Get(string name) name = name ?? Options.DefaultName; // Store the options in our instance cache return _cache.GetOrAdd(name, () => _factory.Create(name)); } }
可以发现TOptions对象是通过IOptionsFactory工厂产生的,我们继续找到OptionsFactory 类的源码,如下:
// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System.Collections.Generic; namespace Microsoft.Extensions.Options { /// <summary> /// Implementation of <see cref="IOptionsFactory{TOptions}"/>. /// </summary> /// <typeparam name="TOptions">The type of options being requested.</typeparam> 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; /// <summary> /// Initializes a new instance with the specified options configurations. /// </summary> /// <param name="setups">The configuration actions to run.</param> /// <param name="postConfigures">The initialization actions to run.</param> public OptionsFactory(IEnumerable<IConfigureOptions<TOptions>> setups, IEnumerable<IPostConfigureOptions<TOptions>> postConfigures) : this(setups, postConfigures, validations: null) { } /// <param name="validations">The validations to run.</param> public OptionsFactory(IEnumerable<IConfigureOptions<TOptions>> setups, IEnumerable<IPostConfigureOptions<TOptions>> postConfigures, IEnumerable<IValidateOptions<TOptions>> validations) { _setups = setups; _postConfigures = postConfigures; _validations = validations; } /// Returns a configured <typeparamref name="TOptions"/> instance with the given <paramref name="name"/>. 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; } }
从此处我们可以看出,在调用 Create(string name) 方法时,首先它会去先创建一个 TOptions 对象,接着再遍历_setups 集合去依次调用所有的 Configure 方法,最后再遍历 _postConfigures 集合去依次调用所有的 PostConfigure 方法。而从上文的分析中我们知道此时_setups 集合中存放的是 ConfigureNamedOptions<TOptions>类型的对象,_postConfigures集合中存放的则是PostConfigureOptions<TOptions>类型的对象。我们分别找到这两个类的源码,如下所示:
/// <summary> /// Implementation of <see cref="IConfigureNamedOptions{TOptions}"/>. /// </summary> /// <typeparam name="TOptions">Options type being configured.</typeparam> public class ConfigureNamedOptions<TOptions> : IConfigureNamedOptions<TOptions> where TOptions : class { /// <summary> /// Constructor. /// </summary> /// <param name="name">The name of the options.</param> /// <param name="action">The action to register.</param> public ConfigureNamedOptions(string name, Action<TOptions> action) { Name = name; Action = action; } /// The options name. public string Name { get; } /// The configuration action. public Action<TOptions> Action { get; } /// Invokes the registered configure <see cref="Action"/> if the <paramref name="name"/> matches. /// <param name="name">The name of the options instance being configured.</param> /// <param name="options">The options instance to configure.</param> 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); /// Invoked to configure a <typeparamref name="TOptions"/> instance with the <see cref="Options.DefaultName"/>. public void Configure(TOptions options) => Configure(Options.DefaultName, options); }
/// <summary> /// Implementation of <see cref="IPostConfigureOptions{TOptions}"/>. /// </summary> /// <typeparam name="TOptions">Options type being configured.</typeparam> public class PostConfigureOptions<TOptions> : IPostConfigureOptions<TOptions> where TOptions : class { /// <summary> /// Creates a new instance of <see cref="PostConfigureOptions{TOptions}"/>. /// </summary> /// <param name="name">The name of the options.</param> /// <param name="action">The action to register.</param> public PostConfigureOptions(string name, Action<TOptions> action) { Name = name; Action = action; } /// The options name. public string Name { get; } /// The initialization action. public Action<TOptions> Action { get; } /// Invokes the registered initialization <see cref="Action"/> if the <paramref name="name"/> matches. /// <param name="name">The name of the action to invoke.</param> /// <param name="options">The options to use in initialization.</param> public virtual void PostConfigure(string name, TOptions options) if (options == null) { throw new ArgumentNullException(nameof(options)); } // Null name is used to initialize all named options. if (Name == null || name == Name) Action?.Invoke(options); }
至此,我们整个流程都串起来了,最后我们来看下OptionsMonitor 类的源码,如下所示:
// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System; using System.Collections.Generic; using Microsoft.Extensions.Primitives; namespace Microsoft.Extensions.Options { /// <summary> /// Implementation of <see cref="IOptionsMonitor{TOptions}"/>. /// </summary> /// <typeparam name="TOptions">Options type.</typeparam> public class OptionsMonitor<TOptions> : IOptionsMonitor<TOptions>, IDisposable where TOptions : class, new() { private readonly IOptionsMonitorCache<TOptions> _cache; private readonly IOptionsFactory<TOptions> _factory; private readonly IEnumerable<IOptionsChangeTokenSource<TOptions>> _sources; private readonly List<IDisposable> _registrations = new List<IDisposable>(); internal event Action<TOptions, string> _onChange; /// <summary> /// Constructor. /// </summary> /// <param name="factory">The factory to use to create options.</param> /// <param name="sources">The sources used to listen for changes to the options instance.</param> /// <param name="cache">The cache used to store options.</param> 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); /// The present value of the options. public TOptions CurrentValue get => Get(Options.DefaultName); /// Returns a configured <typeparamref name="TOptions"/> instance with the given <paramref name="name"/>. public virtual TOptions Get(string name) return _cache.GetOrAdd(name, () => _factory.Create(name)); /// Registers a listener to be called whenever <typeparamref name="TOptions"/> changes. /// <param name="listener">The action to be invoked when <typeparamref name="TOptions"/> has changed.</param> /// <returns>An <see cref="IDisposable"/> which should be disposed to stop listening for changes.</returns> public IDisposable OnChange(Action<TOptions, string> listener) var disposable = new ChangeTrackerDisposable(this, listener); _onChange += disposable.OnChange; return disposable; /// Removes all change registration subscriptions. public void Dispose() // Remove all subscriptions to the change tokens foreach (var registration in _registrations) registration.Dispose(); _registrations.Clear(); 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; } } Microsoft.Extensions.Options.OptionsMonitor类源码
Microsoft.Extensions.Options.OptionsMonitor类源码
3、最佳实践
既然有如此多的获取方式,那我们应该如何选择呢?
1、如果TOption不需要监控且整个程序就只有一个同类型的TOption,那么强烈建议使用IOptions<TOptions>。
2、如果TOption需要监控或者整个程序有多个同类型的TOption,那么只能选择IOptionsMonitor<TOptions>或者IOptionsSnapshot<TOptions>。
3、当IOptionsMonitor<TOptions>和IOptionsSnapshot<TOptions>都可以选择时,如果Action<TOptions>是一个比较耗时的操作,那么建议使用IOptionsMonitor<TOptions>,反之选择IOptionsSnapshot<TOptions>。
4、如果需要对配置源的更新做出反应时(不仅仅是配置对象TOptions本身的更新),那么只能使用IOptionsMonitor<TOptions>,并且注册回调。
本文部分内容参考博文:https://www.cnblogs.com/zhurongbo/p/10856073.html
选项模式微软官方文档:https://docs.microsoft.com/zh-cn/aspnet/core/fundamentals/configuration/options?view=aspnetcore-6.0
aspnetcore源码:
链接: http://pan.baidu.com/s/1BLLjRsvTEBmeVRX68eX7qg?pwd=mju5
提取码: mju5
Demo源码:
链接: http://pan.baidu.com/s/1P9whG1as62gkZEvgz7eSwg?pwd=d6zm
提取码: d6zm
版权声明:如有雷同纯属巧合,如有侵权请及时联系本人修改,谢谢!!!
加载全部内容