asp.net core 系列 12 選項 TOptions
一.概述
本章講的選項模式是對Configuration配置的功能擴充套件。 講這篇時有個專用名詞叫“選項類(TOptions) ” 。該選項類作用是指：把選項類中的屬性與配置來源中的鍵關聯起來。舉個例，假設json檔案有個Option1鍵，選項類中也有個叫Option1的屬性名，經過選項配置，這樣就能把json中的鍵的值對映到選項類屬性值中。也可以理解在專案應用中，把一個json檔案序列化到.net類。
1.1選項介面介紹
在官方文件中選項介面有很多，這裡列舉了這些選項介面。所有選項介面基本都繼承了TOptions介面。
// Used for notifications when TOptions instances change
public interface IOptionsMonitor<out TOptions>
{
//
// 摘要:
//Returns the current TOptions instance with the Microsoft.Extensions.Options.Options.DefaultName.
TOptions CurrentValue { get; }
//...
}
// Used to create TOptions instances
public interface IOptionsFactory<TOptions> where TOptions : class, new()
{
//
// 摘要:
//Returns a configured TOptions instance with the given name.
TOptions Create(string name);
}
// Represents something that configures the TOptions type. Note: These are run before all
public interface IConfigureOptions<in TOptions> where TOptions : class
{
//
// 摘要:
//Invoked to configure a TOptions instance.
//
// 引數:
//options:
//The options instance to configure.
void Configure(TOptions options);
}
public interface IPostConfigureOptions<in TOptions> where TOptions : class
{
//
// 摘要:
//Invoked to configure a TOptions instance.
//
// 引數:
//name:
//The name of the options instance being configured.
//
//options:
//The options instance to configured.
void PostConfigure(string name, TOptions options);
}
public interface IConfigureNamedOptions<in TOptions> : IConfigureOptions<TOptions> where TOptions : class
{
//
// 摘要:
//Invoked to configure a TOptions instance.
//
// 引數:
//name:
//The name of the options instance being configured.
//
//options:
//The options instance to configure.
void Configure(string name, TOptions options);
}
// Used by IOptionsMonitor<TOptions> to cache TOptions instances.
public interface IOptionsMonitorCache<TOptions> where TOptions : class
{
//
// 摘要:
//Clears all options instances from the cache.
void Clear();
//
// 摘要:
//Gets a named options instance, or adds a new instance created with createOptions.
//
// 引數:
//name:
//The name of the options instance.
//
//createOptions:
//The func used to create the new instance.
//
// 返回結果:
//The options instance.
TOptions GetOrAdd(string name, Func<TOptions> createOptions);
//
// 摘要:
//Tries to adds a new option to the cache, will return false if the name already
//exists.
//
// 引數:
//name:
//The name of the options instance.
//
//options:
//The options instance.
//
// 返回結果:
//Whether anything was added.
bool TryAdd(string name, TOptions options);
//
// 摘要:
//Try to remove an options instance.
//
// 引數:
//name:
//The name of the options instance.
//
// 返回結果:
//Whether anything was removed.
bool TryRemove(string name);
}
// Used to access the value of TOptions for the lifetime of a request
public interface IOptionsSnapshot<out TOptions> : IOptions<TOptions> where TOptions : class, new()
{
//
// 摘要:
//Returns a configured TOptions instance with the given name.
TOptions Get(string name);
}
//Used to retrieve configured TOptions instances
public interface IOptions<out TOptions> where TOptions : class, new()
{
//
// 摘要:
//The default configured TOptions instance
TOptions Value { get; }
}
View Code
(1) IOptionsMonitor<TOptions>
IOptionsMonitor<TOptions>用於TOptions例項更改時的通知，用於管理 TOptions選項類 。該IOptionsMonitor<TOptions>支援以下方案：
(1) 更改通知。當配置檔案發生修改時，會監聽同步到選項類。
(2) 命名選項。IConfigureNamedOptions支援命名選項。介面繼續關係 IConfigureNamedOptions:IConfigureOptions
(3) 重新載入配置。通過 IOptionsSnapshot 重新載入配置資料，IOptionsMonitor也支援該功能。 介面繼續關係IOptionsSnapshot ：IOptions
(4) 選擇性選項失效 (IOptionsMonitorCache<TOptions>)。
(2) 其它介面
IOptionsFactory<TOptions> 負責產生TOptions選項例項，它具有單個 Create 方法。
預設實現採用所有已註冊 IConfigureOptions<TOptions> 和 IPostConfigureOptions<TOptions> 並首先執行所有配置(所有的來源配置)，
然後才進行選項後期配置IPostConfigureOptions<TOptions> 。
IOptionsMonitorCache<TOptions>用於快取TOptions例項。
1.2 常規選項配置
TOptions選項類必須為包含公共無引數建構函式的非抽象類。下面示例中選項類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新增到服務容器，並繫結到配置IConfiguration上 //Registers a configuration instance which TOptions will bind against. services.Configure<MyOptions>(Configuration);
private readonly MyOptions _options;
//OtherPages/Page1
public Page1Model( IOptionsMonitor<MyOptions> optionsAccessor)
{
_options = optionsAccessor.CurrentValue;
}
public void OnGet() {
var option1 = _options.Option1;
var option2 = _options.Option2;
varSimpleOptions = $"option1 = {option1}, option2 = {option2}";
｝
// 此時SimpleOptions值："option1 = value1_from_ctor, option2 = 5"
//下面在appsettings.json 檔案新增 option1 和 option2 的值。 "option1": "value1_from_json", "option2": -1,
當配置檔案appsettings.json中option1和option2鍵的值改變後，MyOptions 選項類中的屬性option1和option2的值也會改變。 下面再次執行OtherPages/Page1
//此時SimpleOptions的值為："option1 = value1_from_json, option2 = -1"
為什麼MyOptions類中option1,option2會取到appsettings.json檔案中的值呢？因為MyOptions選項類注入到Iconfiguration服務後與appsettings.json檔案中鍵相同,形成了對映。
1.3 通過委託配置簡單選項
使用委託設定選項值。 此示例應用使用 MyOptionsWithDelegateConfig 類 ,這裡仍然是使用相同的鍵Option1，Option2。 它通過 MyOptionsWithDelegateConfig 使用委託來配置繫結。
public class MyOptionsWithDelegateConfig
{
public MyOptionsWithDelegateConfig()
{
// Set default value.
Option1 = "value1_from_ctor";
}
public string Option1 { get; set; }
public int Option2 { get; set; } = 5;
}
services.Configure<MyOptions>(Configuration);
//第二個注入服務
services.Configure<MyOptionsWithDelegateConfig>(myOptions =>
{
// 在Page1Model構造方法中生成MyOptionsWithDelegateConfig例項時呼叫
myOptions.Option1 = "value1_configured_by_delegate";
myOptions.Option2 = 500;
});
public Page1Model(
IConfiguration configuration,
IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig,
IOptionsMonitor<MyOptions> optionsAccessor
)
{
_optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
_options = optionsAccessor.CurrentValue;
Configuration = configuration;
}
public IConfiguration Configuration { get; }
private readonly MyOptions _options;
private readonly MyOptionsWithDelegateConfig _optionsWithDelegateConfig;
public string BindGUIDMsg { get; set; }
public void OnGet()
{
BindGUIDMsg = $"option1 = {_options.Option1}, option2 = {_options.Option2}";
BindGUIDMsg += "</br>";
BindGUIDMsg += $"delegate_option1 = {_optionsWithDelegateConfig.Option1}, " +
$"delegate_option2 = {_optionsWithDelegateConfig.Option2}";
}
每次呼叫 Configure 都會將 IConfigureOptions<TOptions> 服務新增到服務容器。 在前面的示例中，Option1 和 Option2 的值同時在 appsettings.json 中指定，但 Option1 和 Option2 的值被配置的委託替代。
當啟用多個配置服務時，指定的最後一個配置源優於其他源，由其設定配置值。
執行應用時，頁面模型的
OnGet
方法返回顯示選項類值的字串:
// myOptions例項取值如下: SimpleOptions：option1 = -1，option2 = 5 // MyOptionsWithDelegateConfig例項取值如下: delegate_option1 = value1_configured_by_delegate，delegate_option2 = 500
1.4 子選項配置
當配置檔案中的子節點需要與選項類進行關聯對映時，可以通過服務注入bind到指定的Configuration節點。在以下程式碼中，已向服務容器新增第三個 IConfigureOptions<TOptions> 服務。 它將 MySubOptions 繫結到 appsettings.json 檔案的 subsection 部分：
"Option1": "value1_from_json",
"Option2": -1,
"subsection": {
"suboption1": "subvalue1_from_json",
"suboption2": 200
}
public class MySubOptions
{
public MySubOptions()
{
// Set default values.
SubOption1 = "value1_from_ctor";
SubOption2 = 5;
}
public string SubOption1 { get; set; }
public int SubOption2 { get; set; }
}
//第三個IConfigureOptions<TOptions>注入服務
services.Configure<MySubOptions>(Configuration.GetSection("subsection"));
//OtherPages/Page1
public Page1Model(
IConfiguration configuration,
IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig,
IOptionsMonitor<MyOptions> optionsAccessor,
IOptionsMonitor<MySubOptions> subOptionsAccessor
)
{
_optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
_options = optionsAccessor.CurrentValue;
_subOptions = subOptionsAccessor.CurrentValue;
Configuration = configuration;
}
public IConfiguration Configuration { get; }
private readonly MyOptions _options;
private readonly MyOptionsWithDelegateConfig _optionsWithDelegateConfig;
private readonly MySubOptions _subOptions;
// OnGet方法
SubOptions = $"subOption1 = {_subOptions.SubOption1}, subOption2 = {_subOptions.SubOption2}"
//執行應用時，OnGet 方法返回顯示子選項類值的字串： // MySubOptions例項取值如下: subOption1 = subvalue1_from_json，subOption2 = 200
1.5 IConfigureNamedOptions選項命名
IConfigureNamedOptions：是用於對選項類在注入服務時，進行命名。下面是把MyOptions選項類注入到服務，並取了別名named_options_1。 如下所示：
services.Configure<MyOptions>("named_options_1", Configuration);
//在要使用的頁面，如下所示：
private readonly MyOptions _named_options_1;
public IndexModel(
IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
_named_options_1 = namedOptionsAccessor.Get("named_options_1");
}
// IOptionsSnapshot原始碼
public interface IOptionsSnapshot<out TOptions> : IOptions<TOptions> where TOptions : class, new()
{
//
// 摘要:
//Returns a configured TOptions instance with the given name.
TOptions Get(string name);
}
1.6 ConfigureAll
上面介紹的選項類，在注入服務時都是使用的services.Configure，它是針對選項類的當前例項，例如：在page1和page2都使用了例項MyOptions( private readonly MyOptions _options)但它們屬於不同的例項。
//使用 ConfigureAll 方法配置所有選項例項
services.ConfigureAll<MyOptions>(myOptions =>
{
//所有MyOptions例項配置 Option1的值
myOptions.Option1 = "ConfigureAll replacement value";
});
//新增程式碼後執行示例應用將產生以下結果： named_options_1: option1 = ConfigureAll replacement value, option2 = -1 named_options_2: option1 = ConfigureAll replacement value, option2 = 5
總結:
選項模式是對Configuration配置的功能擴充套件，主要用於把json檔案序列化到.net類(選項類)。通過注入services. Configure或services.ConfigureAll把選項類注入到服務並繫結到Configuration上。 選項這篇還有其它功能如：選項後期配置( IPostConfigureOptions), 啟動期間訪問選項, 選項驗證等，詳細瞭解檢視官網
參考文獻
官方資料:asp.net core 選項