(13)ASP.NET Core 中的選項模式(Options)
1.前言
選項(Options)模式是對配置(Configuration)的功能的延伸。在12章(ASP.NET Core中的配置二)Configuration中有介紹過該功能(繫結到實體類、繫結至物件圖、將陣列繫結至類)而選項模式又有個選項類(TOptions),該選項類作用是指:把選項類中的屬性與配置來源中的鍵關聯起來。舉個例,假設json檔案有個Option1鍵,選項類中也有個叫Option1的屬性名,經過選項配置,這樣就能把json中的鍵的值對映到選項類屬性值中。也可以理解在專案應用中,把一個json檔案序列化到.net類。
2.常規選項配置
選項類必須為包含公共無引數建構函式的非抽象類。在appsettings.json檔案中新增option1、option2、subsection的配置:
{ "option1": "value1_from_json", "option2": -1, "subsection": { "suboption1": "subvalue1_from_json", "suboption2": 200 }, "Logging": { "LogLevel": { "Default": "Warning" } }, "AllowedHosts": "*" }
新建MyOptions類(Models/MyOptions.cs),以下類MyOptions具有三種屬性:Option1和 Option2。設定預設值為可選,但以下示例中的類建構函式設定了Option1的預設值。Option2具有通過直接初始化屬性設定的預設值:
public class MyOptions { public MyOptions() { // Set default value. Option1 = "value1_from_ctor"; } public string Option1 { get; set; } public int Option2 { get; set; } = 5; }
而MyOptions類通過Configure新增到服務容器並繫結到配置:
public void ConfigureServices(IServiceCollection services) { // Example #1: General configuration // Register the Configuration instance which MyOptions binds against. services.Configure<MyOptions>(Configuration); }
也可以使用自定義ConfigurationBuilder從設定檔案載入選項配置時,確認基路徑設定正確,新增到服務容器並繫結到配置:
var configBuilder = new ConfigurationBuilder() .SetBasePath(Directory.GetCurrentDirectory()) .AddJsonFile("appsettings.json", optional: true); var config = configBuilder.Build(); services.Configure<MyOptions>(config);
以下頁面模型通過IOptionsMonitor<TOptions>使用建構函式依賴關係注入來訪問設定 (Pages/Index.cshtml.cs):
public class IndexModel { public IndexModel(IOptionsMonitor<MyOptions> optionsAccessor) { _options = optionsAccessor.CurrentValue; } private readonly MyOptions _options; public void OnGet() { // Example #1: Simple options var option1 = _options.Option1; var option2 = _options.Option2; var simpleOptions = $"option1 = {option1}, option2 = {option2}"; } }
在Home/Index控制器Action下呼叫IndexModel.OnGet方法返回包含選項值的字串:
public HomeController(IOptionsMonitor<MyOptions> optionsAccessor) { _optionsAccessor = optionsAccessor; } private readonly IOptionsMonitor<MyOptions> _optionsAccessor; public IActionResult Index() { IndexModel indexModel = new IndexModel(_optionsAccessor); indexModel.OnGet(); return View(); }
3.通過委託配置簡單選項
使用委託設定選項值。此示例應用程式使用新建MyOptionsWithDelegateConfig類 (Models/MyOptionsWithDelegateConfig.cs):
public class MyOptionsWithDelegateConfig { public MyOptionsWithDelegateConfig() { // Set default value. Option1 = "value1_from_ctor"; } public string Option1 { get; set; } public int Option2 { get; set; } = 5; }
向服務容器新增IConfigureOptions<TOptions>服務。它通過MyOptionsWithDelegateConfig使用委託來配置繫結:
public void ConfigureServices(IServiceCollection services) { // Example #2: Options bound and configured by a delegate services.Configure<MyOptionsWithDelegateConfig>(myOptions => { myOptions.Option1 = "value1_configured_by_delegate"; myOptions.Option2 = 500; }); }
以下頁面模型通過IOptionsMonitor<TOptions>使用建構函式依賴關係注入來訪問設定 (Pages/Index.cshtml.cs):
public class IndexModel { private readonly MyOptionsWithDelegateConfig _optionsWithDelegateConfig; public IndexModel(IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig) { _optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue; } public void OnGet() { // Example #2: Options configured by delegate var delegate_config_option1 = _optionsWithDelegateConfig.Option1; var delegate_config_option2 = _optionsWithDelegateConfig.Option2; var simpleOptionsWithDelegateConfig = $"delegate_option1 = {delegate_config_option1}, " + $"delegate_option2 = {delegate_config_option2}"; } }
在Home/Index控制器Action下呼叫IndexModel.OnGet方法返回包含選項值的字串:
public HomeController(IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig) { _optionsAccessorWithDelegateConfig = optionsAccessorWithDelegateConfig; } private readonly IOptionsMonitor<MyOptionsWithDelegateConfig> _optionsAccessorWithDelegateConfig; public IActionResult Index() { IndexModel indexModel = new IndexModel(_optionsAccessorWithDelegateConfig); indexModel.OnGet(); return View(); }
每次呼叫Configure都會將IConfigureOptions<TOptions>服務新增到服務容器。在前面的示例中,Option1和Option2的值同時在appsettings.json中指定,但Option1和Option2的值被配置的委託替代。當啟用多個配置服務時,指定的最後一個配置源優於其他源,由其設定配置值。執行應用程式時,頁面模型的OnGet方法返回顯示選項類值的字串。
4.子選項配置
將選項繫結到配置時,選項型別中的每個屬性都將繫結到窗體property[:sub-property:]的配置鍵。例如,MyOptions.Option1屬性將繫結到從appsettings.json中的option1屬性讀取的鍵Option1。在以下程式碼中,已向服務容器新增IConfigureOptions<TOptions>服務。它將MySubOptions繫結到appsettings.json檔案的subsection部分:
public void ConfigureServices(IServiceCollection services) { // Example #3: Suboptions // Bind options using a sub-section of the appsettings.json file. services.Configure<MySubOptions>(Configuration.GetSection("subsection")); }
新建MySubOptions類(Models/MySubOptions.cs)將屬性SubOption1和SubOption2定義為保留選項值:
public class MySubOptions { public MySubOptions() { // Set default values. SubOption1 = "value1_from_ctor"; SubOption2 = 5; } public string SubOption1 { get; set; } public int SubOption2 { get; set; } }
以下頁面模型通過IOptionsMonitor<TOptions>使用建構函式依賴關係注入來訪問設定(Pages/Index.cshtml.cs):
public class IndexModel { private readonly MySubOptions _subOptions; public IndexModel(IOptionsMonitor<MySubOptions> subOptionsAccessor) { _subOptions = subOptionsAccessor.CurrentValue; } public void OnGet() { // Example #3: Suboptions var subOption1 = _subOptions.SubOption1; var subOption2 = _subOptions.SubOption2; var subOptions = $"subOption1 = {subOption1}, subOption2 = {subOption2}"; } }
在Home/Index控制器Action下呼叫IndexModel.OnGet方法返回包含選項值的字串:
public HomeController(IOptionsMonitor<MySubOptions> subOptionsAccessor) { _subOptionsAccessor = subOptionsAccessor; } private readonly IOptionsMonitor<MySubOptions> _subOptionsAccessor; public IActionResult Index() { IndexModel indexModel = new IndexModel(_subOptionsAccessor); indexModel.OnGet(); return View(); }
5.通過IOptionsSnapshot重新載入配置資料
IOptionsSnapshot針對請求生命週期訪問和快取選項時,每個請求只能計算一次選項。以下示例演示如何在更改appsettings.json(Pages/Index.cshtml.cs)後建立新的 IOptionsSnapshot<TOptions>。在更改appsettings.json檔案和重新載入配置之前,針對伺服器的多個請求返回appsettings.json檔案提供的配置鍵值。
public class IndexModel { private readonly MyOptions _snapshotOptions; public IndexModel(IOptionsSnapshot<MyOptions> snapshotOptionsAccessor) { _snapshotOptions = snapshotOptionsAccessor.Value; } public void OnGet() { // Example #5: Snapshot options var snapshotOption1 = _snapshotOptions.Option1; var snapshotOption2 = _snapshotOptions.Option2; var snapshotOptions = $"snapshot option1 = {snapshotOption1}, " + $"snapshot option2 = {snapshotOption2}"; } }
下面顯示從appsettings.json檔案載入的初始option1和option2值:
snapshot option1 = value1_from_json, snapshot option2 = -1
將appsettings.json檔案中的值更改為value1_from_json UPDATED和200。儲存appsettings.json 檔案。重新整理瀏覽器,檢視更新的選項值:
snapshot option1 = value1_from_json UPDATED, snapshot option2 = 200
6.包含IConfigureNamedOptions的命名選項支援
命名選項支援允許應用程式在命名選項配置之間進行區分。命名選項通過OptionsServiceCollectionExtensions.Configure進行宣告,其呼叫擴充套件方法ConfigureNamedOptions<TOptions>.Configure:
public void ConfigureServices(IServiceCollection services) { // Example #6: Named options (named_options_1) // Register the ConfigurationBuilder instance which MyOptions binds against. // Specify that the options loaded from configuration are named // "named_options_1". services.Configure<MyOptions>("named_options_1", Configuration); // Example #6: Named options (named_options_2) // Specify that the options loaded from the MyOptions class are named // "named_options_2". // Use a delegate to configure option values. services.Configure<MyOptions>("named_options_2", myOptions => { myOptions.Option1 = "named_options_2_value1_from_action"; }); }
通過OnGet(Pages/Index.cshtml.cs)訪問命名選項:
public class IndexModel { private readonly MyOptions _named_options_1; private readonly MyOptions _named_options_2; public IndexModel(IOptionsSnapshot<MyOptions> namedOptionsAccessor) { _named_options_1 = namedOptionsAccessor.Get("named_options_1"); _named_options_2 = namedOptionsAccessor.Get("named_options_2"); } public void OnGet() { // Example #6: Named options var named_options_1 = $"named_options_1: option1 = {_named_options_1.Option1}, " + $"option2 = {_named_options_1.Option2}"; var named_options_2 = $"named_options_2: option1 = {_named_options_2.Option1}, " + $"option2 = {_named_options_2.Option2}"; var namedOptions = $"{named_options_1} {named_options_2}"; } }
在Home/Index控制器Action下呼叫IndexModel.OnGet方法返回包含選項值的字串:
public HomeController(IOptionsSnapshot<MyOptions> namedOptionsAccessor) { _namedOptionsAccessor = namedOptionsAccessor; } private readonly IOptionsSnapshot<MyOptions> _namedOptionsAccessor; public IActionResult Index() { IndexModel indexModel = new IndexModel(_namedOptionsAccessor); indexModel.OnGet(); return View(); }
5.1使用ConfigureAll方法配置所有選項
使用ConfigureAll方法可以配置所有選項例項。以下程式碼將針對包含公共值的所有配置例項配置Option1。將以下程式碼手動新增到Startup.ConfigureServices方法:
services.ConfigureAll<MyOptions>(myOptions => { myOptions.Option1 = "ConfigureAll replacement value"; });
在Home/Index控制器Action下呼叫IndexModel.OnGet方法返回包含選項值的字串:
參考文獻:
ASP.NET Core 中的選項