ASP.NET Core 中的选项模式
目录
- 前言：
- 一、依赖注入的生命周期
- 一、常规选项配置
- 备注
- 二、通过委托配置简单选项
- 三、子选项配置
- 四、重新加载配置数据
- 五、命名选项
- 六、配置所有选项
- 七、OptionsBuilder API
- 八、使用 DI 服务配置选项
- 九、后期配置
- 十、选项验证
- 1) 使用Validate 方法验证
- 2) 基于数据注释的验证
- 3) 实现 IValidateOptions 进行验证
- 十一、在启动期间访问选项
-
- 参考文档
前言：
选项模式使用的 Microsoft.Extensions.Options.ConfigurationExtensions 包已在 ASP.NET Core 应用中隐式引用。
全文中我们全部使用一个名称为 MyOptions 的类：
public class MyOptions : IDisposable
{
public MyOptions()
{
Option1 = "value_ctor";
}
public string Option1 { get; set; }
[Range(0, int.MaxValue)]
public int Option2 { get; set; } = 5;
public void Dispose()
{
Console.WriteLine($"MyOptions Disposed：{GetHashCode()}");
}
}
配置文件 appsettings.json 的内容：
{
"option1": "value_json",
"option2": -1,
"subsection": {
"option1": "subvalue_json",
"option2": 55555
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
本人在进行测试时，发现 选项模式的实例并不会走 Dispose() 方法 。
一、依赖注入的生命周期
在选项模式中实例的生命周期由注入时使用的接口决定，
有IOptions 、 IOptionsMonitor 和 IOptionsSnapshot共三个，
其中 IOptions 、 IOptionsMonitor 的生命周期是单例模式，生命周期和 AddSingleton 类似，
IOptions 没有数据热更新，读取的值永远不会变。
IOptionsMonitor 和 IOptionsSnapshot 有数据热更新，会保持最新值。
剩下的 IOptionsSnapshot 是作用域服务（快照），生命周期和 AddScoped 类似。
一、常规选项配置
MyOptions 类已通过 Configure 添加到服务容器并绑定到配置：
#region ConfigureServices
services.Configure<MyOptions>(Configuration);
#endregion
#region [ApiController]
private readonly MyOptions _options;
public HomeController(IOptionsMonitor<MyOptions> options)
{
_options = options.CurrentValue;
}
[HttpGet]
public MyOptions Index() { return _options; }
#endregion
访问 /Home/Index 得到的值为：
{"option1":"value_json","option2":-1}
可以看到，配置文件中的值已将实例的默认值覆盖了。
备注
使用自定义 ConfigurationBuilder 从设置文件加载选项配置：
#region ConfigureServices var configBuilder = new ConfigurationBuilder() .SetBasePath(Directory.GetCurrentDirectory()) .AddJsonFile("appsettings.json", optional: true); var config = configBuilder.Build(); services.Configure<MyOptions>(config); #endregion
二、通过委托配置简单选项
使用委托设置选项值：
#region ConfigureServices
services.Configure<MyOptions>(myOptions =>
{
myOptions.Option1 = "value_delegate";
myOptions.Option2 = 2333;
});
#endregion
访问 /Home/Index 得到的值为：
{"option1":"value_delegate","option2":2333}
可以看到，MyOptions 使用委托配置绑定覆盖了默认值，
当启用多个配置服务时，指定的最后一个配置源优于其他源 。
三、子选项配置
需要配置值的部分应用时可以使用子选项配置
#region ConfigureServices
services.Configure<MyOptions>(Configuration.GetSection("subsection"));
#endregion
访问 /Home/Index 得到的值为：
{"option1":"subvalue_json","option2":55555}
四、重新加载配置数据
使用选项框架时，配置文件默认是热更新的。
我们运行 子选项配置 中的代码
访问 /Home/Index 得到的值为：
{"option1":"subvalue_json","option2":55555}
程序运行时，我们将 appsettings.json 文件中的 subsection 节点改为如下：
"subsection": {
"option1": "subvalue_json new",
"option2": 12345
},
再次访问 /Home/Index 得到的值为：
{"option1":"subvalue_json new","option2":12345}
五、命名选项
命名选项支持允许应用在命名选项配置之间进行区分
#region ConfigureServices
services.Configure<MyOptions>("options_1", Configuration);
services.Configure<MyOptions>("options_2", myOptions =>
{
myOptions.Option1 = "options_2_value1_action";
});
#endregion
#region [ApiController]
private readonly MyOptions _options;
private readonly MyOptions _options_1;
private readonly MyOptions _options_2;
public HomeController(IOptionsMonitor<MyOptions> options)
{
_options = options.CurrentValue;
_options_1 = options.Get("options_1");
_options_2 = options.Get("options_2");
}
[HttpGet]
public List<MyOptions> Index()
{
var result = new List<MyOptions>() {
_options,_options_1,_options_2
};
return result;
}
#endregion
访问 /Home/Index 得到的值为：
[
{"option1":"value_ctor","option2":5},
{"option1":"value_json","option2":-1},
{"option1":"options_2_value1_action","option2":5}
]
可以看到，各个MyOptions 实例的不同，
无命名的取的是默认值，options_1 取的是配置文件的值，options_2 取的是委托配置。
六、配置所有选项
可以使用 ConfigureAll 方法配置所有选项实例。
#region ConfigureServices
services.Configure<MyOptions>("options_1", Configuration);
services.Configure<MyOptions>("options_2", myOptions =>
{
myOptions.Option1 = "options_2_value1_action";
});
services.ConfigureAll<MyOptions>(myOptions =>
{
myOptions.Option1 = "ConfigureAll value";
});
#endregion
访问 /Home/Index 得到的值为：
[
{"option1":"ConfigureAll value","option2":5},
{"option1":"ConfigureAll value","option2":-1},
{"option1":"ConfigureAll value","option2":5}
]
可以看到每个MyOptions实例的 option1 都被覆盖了
七、OptionsBuilder API
OptionsBuilder 简化了创建命名选项的过程，
#region ConfigureServices
services.AddOptions<MyOptions>().Configure(o => o.Option1 = "options_builder");
services.AddOptions<MyOptions>("options_1").Configure(o =>
{
Configuration.Bind(o);
// o.Option1 = "default value";
// o.Option2 = 2000;
});
#endregion
访问 /Home/Index 得到的值为：
[
{"option1":"options_builder","option2":5},
{"option1":"default value","option2":2000},
{"option1":"value_ctor","option2":5}
]
八、使用 DI 服务配置选项
可以使用DI服务进行配置
#region ConfigEntity
public class AppConfig { public string Option1 { get; set; } = "SAP"; }
public class PrjConfig { public int Option2 { get; set; } = 69; }
#endregion
#region ConfigureServices
services.AddScoped<AppConfig>();
services.AddScoped<PrjConfig>();
services.AddOptions<MyOptions>("optionalName")
.Configure<AppConfig, PrjConfig>((o, s, b) =>
{
o.Option1 = s.Option1;
o.Option2 = b.Option2;
});
#endregion
#region [ApiController]
private readonly MyOptions _options;
public HomeController(IOptionsSnapshot<MyOptions> options)
{
_options = options.Get("optionalName");
}
[HttpGet]
public MyOptions Index() { return _options; }
#endregion
访问 /Home/Index 得到的值为：
{"option1":"SAP","option2":69}
九、后期配置
使用 IPostConfigureOptions 设置后期配置
#region ConfigureServices
// PostConfigure 可用于后期配置
services.PostConfigure<MyOptions>(myOptions =>
{
myOptions.Option1 = "post_configured_option1_value";
});
// PostConfigure 可用于对命名选项进行后期配置
services.PostConfigure<MyOptions>("named_options_1", myOptions =>
{
myOptions.Option1 = "post_configured_option1_value";
});
// PostConfigureAll 对所有配置实例进行后期配置
services.PostConfigureAll<MyOptions>(myOptions =>
{
myOptions.Option1 = "post_configured_option1_value";
});
#endregion
十、选项验证
添加验证的时候只能用 OptionsBuilder API。
现在将 HomeController 的 ctor 修改为如下：
#region [ApiController]
private readonly MyOptions _options;
public HomeController(IOptionsSnapshot<MyOptions> options)
{
_options = options.Value;
}
[HttpGet]
public MyOptions Index() { return _options; }
#endregion
添加选项验证有三种方法：
- 直接注册验证函数，调用 Validate
- 使用 Microsoft.Extensions.Options.DataAnnotations 基于数据注释验证
- 实现
IValidateOptions函数
1) 使用Validate 方法验证
#region ConfigureServices
services.AddOptions<MyOptions>().Configure(options =>
{
Configuration.Bind(options);
}).Validate(options =>
{
return options.Option2 > 0;
}, "Option2 必须大于0");
#endregion
因为配置文件中 Option2 等于 -1 所以当我们访问 /Home/Index 时：
可以看到报错的内容为我们填写的 Validate 的第二个参数。
2) 基于数据注释的验证
#region ConfigureServices
services.AddOptions<MyOptions>().Configure(options =>
{
Configuration.Bind(options);
}).ValidateDataAnnotations();
#endregion
#region MyOptions Class
[Range(0, int.MaxValue)]
public int Option2 { get; set; } = 5;
#endregion
因为配置文件中 Option2 等于 -1 所以当我们访问 /Home/Index 时：
3) 实现 IValidateOptions 进行验证
首先我们需要实现 IValidateOptions ：
#region IValidateOptions
public class MyValidateOptions : IValidateOptions<MyOptions>
{
public ValidateOptionsResult Validate(string name, MyOptions options)
{
if (options.Option2 <= 0)
{
return ValidateOptionsResult.Fail("Option2 必须大于0");
}
else
{
return ValidateOptionsResult.Success;
}
}
}
#endregion
#region ConfigureServices
services.AddOptions<MyOptions>().Configure(options =>
{
Configuration.Bind(options);
}).Services.AddSingleton<IValidateOptions<MyOptions>, MyValidateOptions>();
#endregion
因为配置文件中 Option2 等于 -1 所以当我们访问 /Home/Index 时：
十一、在启动期间访问选项
可用于 Startup.Configure 中，因为在 Configure 方法执行之前已生成服务
public void Configure(IApplicationBuilder app,
IOptionsMonitor<MyOptions> optionsAccessor)
{
var option1 = optionsAccessor.CurrentValue.Option1;
}
参考文档
ASP.NET Core 中的选项模式