.NET Core 選項模式【Options】的使用

ASP.NET Core引入了Options模式，使用類來表示相關的設置組。簡單的來說，就是用強類型的類來表達配置項，這帶來了很多好處。利用了系統的依賴註入，並且還可以利用配置系統。它使我們可以採用依賴註入的方法直接使用綁定的一個POCO對象，這個POCO對象就叫做Options對象。也可以叫做配置 ...

ASP.NET Core引入了Options模式，使用類來表示相關的設置組。簡單的來說，就是用強類型的類來表達配置項，這帶來了很多好處。利用了系統的依賴註入，並且還可以利用配置系統。它使我們可以採用依賴註入的方法直接使用綁定的一個POCO對象，這個POCO對象就叫做Options對象。也可以叫做配置對象。

以下大多內容來自官方文檔，我只是個翻譯官或者叫搬運工吧！

引入Options擴展包

PM>Package-install Microsoft.Extensions.Options

綁定分層配置

在appsetting.json文件增加如下配置

"Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }

創建以下 PositionOptions 類：

public class PositionOptions
{
    public const string Position = "Position";

    public string Title { get; set; }
    public string Name { get; set; }
}

選項類：

必須是包含公共無參數構造函數的非抽象類。
類型的所有公共讀寫屬性都已綁定。
不會綁定欄位。在上面的代碼中，Position 未綁定。由於使用了 Position 屬性，因此在將類綁定到配置提供程式時，不需要在應用中對字元串 "Position" 進行硬編碼。

類綁定

調用 ConfigurationBinder.Bind 將 PositionOptions 類綁定到 Position 部分。然後就可以用了，當然這種方式在開發.NET Core種並不常用，一般採用依賴註入的方式註入。

var positionOptions = new PositionOptions();
Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);

使用 ConfigurationBinder.Get 可能比使用 ConfigurationBinder.Bind 更方便。

positionOptions = Configuration.GetSection(PositionOptions.Position).Get<PositionOptions>();

依賴項註入服務容器

修改ConfigureServices方法

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(Configuration.GetSection(
                                        PositionOptions.Position));
    services.AddRazorPages();
}

通過使用前面的代碼，以下代碼將讀取位置選項：

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

    public Test2Model(IOptions<PositionOptions> options)
    {
        _options = options.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Title: {_options.Title} \n" +
                       $"Name: {_options.Name}");
    }
}

選項介面

初學者會發現這個框架有3個主要的面向消費者的介面：IOptions、IOptionsMonitor以及IOptionsSnapshot。

這三個介面初看起來很類似，所以很容易引起困惑，什麼場景下該用哪個介面呢？

IOptions

不支持
- 在應用啟動後讀取配置數據。
- 命名選項
註冊為單一實例，可以註入到任何服務生存期。

IOptionsSnapshot

作用域容器配置熱更新使用它
註冊為範圍內，因此無法註入到單一實例服務
支持命名選項

IOptionsMonitor

用於檢索選項並管理 TOptions 實例的選項通知。
註冊為單一實例且可以註入到任何服務生存期。
支持
- 更改通知
- 命名選項
- 可重載配置
- 選擇性選項失效

使用 IOptionsSnapshot 讀取已更新的數據

IOptionsMonitor 和 IOptionsSnapshot 之間的區別在於：

IOptionsMonitor 是一種單一示例服務，可隨時檢索當前選項值，這在單一實例依賴項中尤其有用。
IOptionsSnapshot 是一種作用域服務，併在構造 IOptionsSnapshot 對象時提供選項的快照。選項快照旨在用於暫時性和有作用域的依賴項。

public class TestSnapModel : PageModel
{
    private readonly MyOptions _snapshotOptions;

    public TestSnapModel(IOptionsSnapshot<MyOptions> snapshotOptionsAccessor)
    {
        _snapshotOptions = snapshotOptionsAccessor.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Option1: {_snapshotOptions.Option1} \n" +
                       $"Option2: {_snapshotOptions.Option2}");
    }
}

IOptionsMonitor

public class TestMonitorModel : PageModel
{
    private readonly IOptionsMonitor<MyOptions> _optionsDelegate;

    public TestMonitorModel(IOptionsMonitor<MyOptions> optionsDelegate )
    {
        _optionsDelegate = optionsDelegate;
    }

    public ContentResult OnGet()
    {
        return Content($"Option1: {_optionsDelegate.CurrentValue.Option1} \n" +
                       $"Option2: {_optionsDelegate.CurrentValue.Option2}");
    }
}

命名選項支持使用 IConfigureNamedOptions

命名選項：

當多個配置節綁定到同一屬性時有用。
區分大小寫。

appsettings.json文件

{
  "TopItem": {
    "Month": {
      "Name": "Green Widget",
      "Model": "GW46"
    },
    "Year": {
      "Name": "Orange Gadget",
      "Model": "OG35"
    }
  }
}

下麵的類用於每個節，而不是創建兩個類來綁定 TopItem:Month 和 TopItem:Year

public class TopItemSettings
{
    public const string Month = "Month";
    public const string Year = "Year";

    public string Name { get; set; }
    public string Model { get; set; }
}

依賴註入容器

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<TopItemSettings>(TopItemSettings.Month,
                                       Configuration.GetSection("TopItem:Month"));
    services.Configure<TopItemSettings>(TopItemSettings.Year,
                                        Configuration.GetSection("TopItem:Year"));

    services.AddRazorPages();
}

服務應用

public class TestNOModel : PageModel
{
    private readonly TopItemSettings _monthTopItem;
    private readonly TopItemSettings _yearTopItem;

    public TestNOModel(IOptionsSnapshot<TopItemSettings> namedOptionsAccessor)
    {
        _monthTopItem = namedOptionsAccessor.Get(TopItemSettings.Month);
        _yearTopItem = namedOptionsAccessor.Get(TopItemSettings.Year);
    }
}

使用 DI 服務配置選項

在配置選項時，可以通過以下兩種方式通過依賴關係註入訪問服務：

將配置委托傳遞給 OptionsBuilder 上的 Configure

services.AddOptions<MyOptions>("optionalName")
    .Configure<Service1, Service2, Service3, Service4, Service5>(
        (o, s, s2, s3, s4, s5) => 
            o.Property = DoSomethingWith(s, s2, s3, s4, s5));

創建實現 IConfigureOptions 或 IConfigureNamedOptions 的類型，並將該類型註冊為服務

建議將配置委托傳遞給 Configure，因為創建服務較複雜。在調用 Configure 時，創建類型等效於框架執行的操作。調用 Configure 會註冊臨時泛型 IConfigureNamedOptions，它具有接受指定的泛型服務類型的構造函數。

選項驗證

appsettings.json 文件

{
  "MyConfig": {
    "Key1": "My Key One",
    "Key2": 10,
    "Key3": 32
  }
}

下麵的類綁定到 "MyConfig" 配置節，並應用若幹 DataAnnotations 規則：

public class MyConfigOptions
{
    public const string MyConfig = "MyConfig";

    [RegularExpression(@"^[a-zA-Z''-'\s]{1,40}$")]
    public string Key1 { get; set; }
    [Range(0, 1000,
        ErrorMessage = "Value for {0} must be between {1} and {2}.")]
    public int Key2 { get; set; }
    public int Key3 { get; set; }
}

啟用DataAnnotations驗證

public void ConfigureServices(IServiceCollection services)
{
    services.AddOptions<MyConfigOptions>()
        .Bind(Configuration.GetSection(MyConfigOptions.MyConfig))
        .ValidateDataAnnotations();

    services.AddControllersWithViews();
}

使用IValidateOptions更複雜的配置

public class MyConfigValidation : IValidateOptions<MyConfigOptions>
{
    public MyConfigOptions _config { get; private set; }

    public  MyConfigValidation(IConfiguration config)
    {
        _config = config.GetSection(MyConfigOptions.MyConfig)
            .Get<MyConfigOptions>();
    }

    public ValidateOptionsResult Validate(string name, MyConfigOptions options)
    {
        string vor=null;
        var rx = new Regex(@"^[a-zA-Z''-'\s]{1,40}$");
        var match = rx.Match(options.Key1);

        if (string.IsNullOrEmpty(match.Value))
        {
            vor = $"{options.Key1} doesn't match RegEx \n";
        }

        if ( options.Key2 < 0 || options.Key2 > 1000)
        {
            vor = $"{options.Key2} doesn't match Range 0 - 1000 \n";
        }

        if (_config.Key2 != default)
        {
            if(_config.Key3 <= _config.Key2)
            {
                vor +=  "Key3 must be > than Key2.";
            }
        }

        if (vor != null)
        {
            return ValidateOptionsResult.Fail(vor);
        }

        return ValidateOptionsResult.Success;
    }
}

IValidateOptions 允許將驗證代碼移出 StartUp 並將其移入類中。

使用前面的代碼，使用以下代碼在 Startup.ConfigureServices 中啟用驗證

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyConfigOptions>(Configuration.GetSection(
                                        MyConfigOptions.MyConfig));
    services.TryAddEnumerable(ServiceDescriptor.Singleton<IValidateOptions
                              <MyConfigOptions>, MyConfigValidation>());
    services.AddControllersWithViews();
}

選項後期配置

使用 IPostConfigureOptions 設置後期配置。進行所有 IConfigureOptions 配置後運行後期配置

services.PostConfigure<MyOptions>(myOptions =>
{
    myOptions.Option1 = "post_configured_option1_value";
});

使用 PostConfigureAll 對所有配置實例進行後期配置

在啟動期間訪問選項

IOptions 和 IOptionsMonitor 可用於 Startup.Configure 中，因為在 Configure 方法執行之前已生成服務。

public void Configure(IApplicationBuilder app, 
    IOptionsMonitor<MyOptions> optionsAccessor)
{
    var option1 = optionsAccessor.CurrentValue.Option1;
}

結論

IOptions<>是單例，因此一旦生成了，除非通過代碼的方式更改，它的值是不會更新的。

IOptionsMonitor<>也是單例，但是它通過IOptionsChangeTokenSource<> 能夠和配置文件一起更新，也能通過代碼的方式更改值。

IOptionsSnapshot<>是範圍，所以在配置文件更新的下一次訪問，它的值會更新，但是它不能跨範圍通過代碼的方式更改值，只能在當前範圍（請求）內有效。

所以你應該根據你的實際使用場景來選擇到底是用這三者中的哪一個。
一般來說，如果你依賴配置文件，那麼首先考慮IOptionsMonitor<>，如果不合適接著考慮IOptionsSnapshot<>，最後考慮IOptions<>。

有一點需要註意，在ASP.NET Core應用中IOptionsMonitor可能會導致同一個請求中選項的值不一致,當你正在修改配置文件的時候,這可能會引發一些奇怪的bug。

如果這個對你很重要，請使用IOptionsSnapshot，它可以保證同一個請求中的一致性，但是它可能會帶來輕微的性能上的損失。
如果你是在app啟動的時候自己構造Options（比如在Startup類中）：

services.Configure<TestOptions>(opt => opt.Name = "Test");

IOptions<>最簡單，也許是一個不錯的選擇。