.NET Core 選項模式【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 。

這三個接口初看起來很相似，因此很容易引發困惑，什麼場景下該用哪一個接口呢？

1. IOptions

• 不支持
  • 在應用啓動後讀取配置數據。
  • 命名選項
• 註冊爲單一實例，能夠注入到任何服務生存期。

2. IOptionsSnapshot

• 做用域容器配置熱更新使用它
• 註冊爲範圍內，所以沒法注入到單一實例服務
• 支持命名選項

3. 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<>最簡單，也許是一個不錯的選擇。