.NET 中的选项模式

选项模式使用类来提供对相关设置组的强类型访问。 当配置设置由方案隔离到单独的类时,应用遵循两个重要软件工程原则:

选项还提供验证配置数据的机制。 有关详细信息,请参阅选项验证部分。

绑定分层配置

读取相关配置值的首选方法是使用选项模式。 选项模式可以通过 IOptions<TOptions> 接口实现,其中泛型类型参数 TOptions 被约束为 class。 以后可以通过依赖关系注入来提供 IOptions<TOptions>。 有关详细信息,请参阅 .NET 中的依赖关系注入

例如,若要读取以下配置值,请执行以下操作:

"TransientFaultHandlingOptions": {
    "Enabled": true,
    "AutoRetryDelay": "00:00:07"
},

创建以下 TransientFaultHandlingOptions 类:

public class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

在使用选项模式时,选项类:

  • 必须是非抽象类,有一个公共无参数构造函数
  • 包含要绑定的公共读写属性(字段不绑定)

下面的代码:

  • 调用 ConfigurationBinder.BindTransientFaultHandlingOptions 类绑定到 "TransientFaultHandlingOptions" 部分。
  • 显示配置数据。
IConfigurationRoot configurationRoot = configuration.Build();

TransientFaultHandlingOptions options = new();
configurationRoot.GetSection(nameof(TransientFaultHandlingOptions))
                 .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

在上面的代码中,已读取在应用启动后对 JSON 配置文件所做的更改。

ConfigurationBinder.Get<T> 绑定并返回指定的类型。 使用 ConfigurationBinder.Get<T> 可能比使用 ConfigurationBinder.Bind 更方便。 下面的代码演示如何将 ConfigurationBinder.Get<T>TransientFaultHandlingOptions 类配合使用:

IConfigurationRoot configurationRoot = configuration.Build();

var options =
    configurationRoot.GetSection(nameof(TransientFaultHandlingOptions))
                     .Get<TransientFaultHandlingOptions>();

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

在上面的代码中,已读取在应用启动后对 JSON 配置文件所做的更改。

重要

ConfigurationBinder 类公开了几个 API,例如不被约束为 class.Bind(object instance).Get<T>()。 使用任何一个选项接口时,都必须遵守前面提到的选项类约束

使用选项模式时的另一种方法是绑定 "TransientFaultHandlingOptions" 部分,并将其添加到依赖关系注入服务容器中。 在以下代码中,TransientFaultHandlingOptions 已通过 Configure 被添加到了服务容器并已绑定到了配置:

services.Configure<TransientFaultHandlingOptions>(
    configurationRoot.GetSection(
        key: nameof(TransientFaultHandlingOptions)));

要访问 servicesconfigurationRoot 对象,必须使用 ConfigureServices 方法 — IConfiguration 作为 HostBuilderContext.Configuration 属性提供。

Host.CreateDefaultBuilder(args)
    .ConfigureServices((context, services) =>
    {
        var configurationRoot = context.Configuration;
        services.Configure<TransientFaultHandlingOptions>(
            configurationRoot.GetSection(nameof(TransientFaultHandlingOptions)));
    });

提示

key 参数是要搜索的配置部分的名称。 它不必与代表它的类型名称相匹配。 例如,你可以有一个名为 "FaultHandling" 的部分,该部分可以由 TransientFaultHandlingOptions 类来表示。 在这种情况下,可以改为将 "FaultHandling" 传递到 GetSection 函数。 在命名部分与其对应的类型相匹配时,为了方便,使用 nameof 运算符。

通过使用前面的代码,以下代码将读取位置选项:

using System;
using Microsoft.Extensions.Options;

namespace ConsoleJson.Example
{
    public class ExampleService
    {
        private readonly TransientFaultHandlingOptions _options;

        public ExampleService(IOptions<TransientFaultHandlingOptions> options) =>
            _options = options.Value;

        public void DisplayValues()
        {
            Console.WriteLine($"TransientFaultHandlingOptions.Enabled={_options.Enabled}");
            Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={_options.AutoRetryDelay}");
        }
    }
}

在上面的代码中,不会读取在应用启动后对 JSON 配置文件所做的更改。 若要读取在应用启动后的更改,请使用 IOptionsSnapshot

选项接口

IOptions<TOptions>:

IOptionsSnapshot<TOptions>:

IOptionsMonitor<TOptions>:

IOptionsFactory<TOptions> 负责新建选项实例。 它具有单个 Create 方法。 默认实现采用所有已注册 IConfigureOptions<TOptions>IPostConfigureOptions<TOptions> 并首先运行所有配置,然后才进行后期配置。 它区分 IConfigureNamedOptions<TOptions>IConfigureOptions<TOptions> 且仅调用适当的接口。

IOptionsMonitorCache<TOptions>IOptionsMonitor<TOptions> 用于缓存 TOptions 实例。 IOptionsMonitorCache<TOptions> 可使监视器中的选项实例无效,以便重新计算值 (TryRemove)。 可以通过 TryAdd 手动引入值。 在应按需重新创建所有命名实例时使用 Clear 方法。

选项接口优点

使用泛型包装器类型,可以将选项的生存期从 DI 容器中解耦出来。 IOptions<TOptions>.Value 接口对选项类型提供了一个抽象层,包括泛型约束。 这提供了以下好处:

  • T 配置实例的评估推迟到在访问 IOptions<TOptions>.Value 时进行,而不是在注入时进行。 这一点很重要,因为你可以从各种不同的位置使用 T 选项,并选择生存期语义,而无需更改关于 T 的任何内容。
  • 注册 T 类型的选项时,不需要显式注册 T 类型。 如果你使用简单的默认值创建库,并且不想强制调用方将选项注册到具有特定生存期的 DI 容器中,这可以带来很多便利。
  • 从 API 的角度来看,它允许对类型 T 进行约束(在本例中,T 被约束为引用类型)。

使用 IOptionsSnapshot 读取已更新的数据

当你使用 IOptionsSnapshot<TOptions> 时,在访问每个请求时会计算一次选项,并在请求的生存期内缓存这些选项。 当使用支持读取已更新的配置值的配置提供程序时,将在应用启动后读取对配置所做的更改。

IOptionsMonitorIOptionsSnapshot 之间的区别在于:

  • IOptionsMonitor 是一种单一示例服务,可随时检索当前选项值,这在单一实例依赖项中尤其有用。
  • IOptionsSnapshot 是一种作用域服务,并在构造 IOptionsSnapshot<T> 对象时提供选项的快照。 选项快照旨在用于暂时性和有作用域的依赖项。

以下代码使用 IOptionsSnapshot<TOptions>

using System;
using Microsoft.Extensions.Options;

namespace ConsoleJson.Example
{
    public class ScopedService
    {
        private readonly TransientFaultHandlingOptions _options;

        public ScopedService(IOptionsSnapshot<TransientFaultHandlingOptions> options) =>
            _options = options.Value;

        public void DisplayValues()
        {
            Console.WriteLine($"TransientFaultHandlingOptions.Enabled={_options.Enabled}");
            Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={_options.AutoRetryDelay}");
        }
    }
}

以下代码注册 TransientFaultHandlingOptions 绑定的配置实例:

services.Configure<TransientFaultHandlingOptions>(
    configurationRoot.GetSection(
        nameof(TransientFaultHandlingOptions)));

在上面的代码中,已读取在应用启动后对 JSON 配置文件所做的更改。

IOptionsMonitor

以下代码注册 TransientFaultHandlingOptions 绑定的配置实例。

services.Configure<TransientFaultHandlingOptions>(
    configurationRoot.GetSection(
        nameof(TransientFaultHandlingOptions)));

下面的示例使用 IOptionsMonitor<TOptions>

using System;
using Microsoft.Extensions.Options;

namespace ConsoleJson.Example
{
    public class MonitorService
    {
        private readonly IOptionsMonitor<TransientFaultHandlingOptions> _monitor;

        public MonitorService(IOptionsMonitor<TransientFaultHandlingOptions> monitor) =>
            _monitor = monitor;

        public void DisplayValues()
        {
            TransientFaultHandlingOptions options = _monitor.CurrentValue;

            Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
            Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");
        }
    }
}

在上面的代码中,已读取在应用启动后对 JSON 配置文件所做的更改。

提示

某些文件系统(例如 Docker 容器和网络共享)可能无法可靠地发送更改通知。 在这些环境中使用 IOptionsMonitor<TOptions> 接口时,请将 DOTNET_USE_POLLING_FILE_WATCHER 环境变量设置为 1true,以便轮询文件系统的更改。 轮询更改的时间间隔是四秒,此间隔不可配置。

有关 Docker 容器的详细信息,请参阅容器化 .NET 应用

命名选项支持使用 IConfigureNamedOptions

命名选项:

  • 当多个配置节绑定到同一属性时有用。
  • 区分大小写。

请考虑使用以下 appsettings.json 文件:

{
  "Features": {
    "Personalize": {
      "Enabled": true,
      "ApiKey": "aGEgaGEgeW91IHRob3VnaHQgdGhhdCB3YXMgcmVhbGx5IHNvbWV0aGluZw=="
    },
    "WeatherStation": {
      "Enabled": true,
      "ApiKey": "QXJlIHlvdSBhdHRlbXB0aW5nIHRvIGhhY2sgdXM/"
    }
  }
}

下面的类用于每个节,而不是创建两个类来绑定 Features:PersonalizeFeatures:WeatherStation

public class Features
{
    public const string Personalize = nameof(Personalize);
    public const string WeatherStation = nameof(WeatherStation);

    public bool Enabled { get; set; }
    public string ApiKey { get; set; }
}

下面的代码将配置命名选项:

ConfigureServices(services =>
{
    services.Configure<Features>(
        Features.Personalize,
        Configuration.GetSection("Features:Personalize"));

    services.Configure<Features>(
        Features.WeatherStation,
        Configuration.GetSection("Features:WeatherStation"));
});

下面的代码将显示命名选项:

public class Service
{
    private readonly Features _personalizeFeature;
    private readonly Features _weatherStationFeature;

    public Service(IOptionsSnapshot<Features> namedOptionsAccessor)
    {
        _personalizeFeature = namedOptionsAccessor.Get(Features.Personalize);
        _weatherStationFeature = namedOptionsAccessor.Get(Features.WeatherStation);
    }
}

所有选项都是命名实例。 IConfigureOptions<TOptions> 实例将被视为面向 Options.DefaultName 实例,即 string.EmptyIConfigureNamedOptions<TOptions> 还可实现 IConfigureOptions<TOptions>IOptionsFactory<TOptions> 的默认实现具有适当地使用每个实例的逻辑。 null 命名选项用于面向所有命名实例,而不是某一特定命名实例。 ConfigureAllPostConfigureAll 使用此约定。

OptionsBuilder API

OptionsBuilder<TOptions> 用于配置 TOptions 实例。 OptionsBuilder 简化了创建命名选项的过程,因为它只是初始 AddOptions<TOptions>(string optionsName) 调用的单个参数,而不会出现在所有后续调用中。 选项验证和接受服务依赖关系的 ConfigureOptions 重载仅可通过 OptionsBuilder 获得。

OptionsBuilder选项验证部分中使用。

使用 DI 服务配置选项

在配置选项时,可以通过以下两种方式通过依赖关系注入访问服务:

建议将配置委托传递给 Configure,因为创建服务较复杂。 在调用 Configure 时,创建类型等效于框架执行的操作。 调用 Configure 会注册临时泛型 IConfigureNamedOptions<TOptions>,它具有接受指定的泛型服务类型的构造函数。

选项验证

通过选项验证,可以验证选项值。

请考虑使用以下 appsettings.json 文件:

{
  "MyCustomSettingsSection": {
    "SiteTitle": "Amazing docs from Awesome people!",
    "Scale": 10,
    "VerbosityLevel": 32
  }
}

下面的类绑定到 "MyCustomSettingsSection" 配置节,并应用若干 DataAnnotations 规则:

using System;
using System.ComponentModel.DataAnnotations;

namespace ConsoleJson.Example
{
    public class SettingsOptions
    {
        public const string ConfigurationSectionName = "MyCustomSettingsSection";

        [RegularExpression(@"^[a-zA-Z''-'\s]{1,40}$")]
        public string SiteTitle { get; set; }

        [Range(0, 1000,
            ErrorMessage = "Value for {0} must be between {1} and {2}.")]
        public int Scale { get; set; }

        public int VerbosityLevel { get; set; }
    }
}

在前面的 SettingsOptions 类中,ConfigurationSectionName 属性包含要绑定到的配置部分的名称。 在此方案中,选项对象提供其配置部分的名称。

提示

配置部分名称独立于所绑定到的配置对象。 换句话说,名为 "FooBarOptions" 的配置部分可以绑定到名为 ZedOptions 的选项对象。 虽然为二者提供相同的名称很常见,但这并 是必要的,且可能会导致名称冲突。

下面的代码:

services.AddOptions<SettingsOptions>()
    .Bind(Configuration.GetSection(SettingsOptions.ConfigurationSectionName))
    .ValidateDataAnnotations();

ValidateDataAnnotations 扩展方法在 Microsoft.Extensions.Options.DataAnnotations NuGet 包中定义。

下面的代码显示配置值或验证错误:

using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;

namespace ConsoleJson.Example
{
    public class ValidationService
    {
        private readonly ILogger<ValidationService> _logger;
        private readonly IOptions<SettingsOptions> _config;

        public ValidationService(
            ILogger<ValidationService> logger,
            IOptions<SettingsOptions> config)
        {
            _config = config;
            _logger = logger;

            try
            {
                SettingsOptions options = _config.Value;
            }
            catch (OptionsValidationException ex)
            {
                foreach (string failure in ex.Failures)
                {
                    _logger.LogError(failure);
                }
            }
        }
    }
}

下面的代码使用委托应用更复杂的验证规则:

services.AddOptions<SettingsOptions>()
    .Bind(Configuration.GetSection(SettingsOptions.ConfigurationSectionName))
    .ValidateDataAnnotations()
    .Validate(config =>
    {
        if (config.Scale != 0)
        {
            return config.VerbosityLevel > config.Scale;
        }

        return true;
    }, "VerbosityLevel must be > than Scale.");

用于复杂验证的 IValidateOptions

下面的类实现了 IValidateOptions<TOptions>

using System.Text.RegularExpressions;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Options;

namespace ConsoleJson.Example
{
    class ValidateSettingsOptions : IValidateOptions<SettingsOptions>
    {
        public SettingsOptions _settings { get; private set; }

        public ValidateSettingsOptions(IConfiguration config) =>
            _settings = config.GetSection(SettingsOptions.ConfigurationSectionName)
                              .Get<SettingsOptions>();

        public ValidateOptionsResult Validate(string name, SettingsOptions options)
        {
            string result = "";
            var rx = new Regex(@"^[a-zA-Z''-'\s]{1,40}$");
            Match match = rx.Match(options.SiteTitle);
            if (string.IsNullOrEmpty(match.Value))
            {
                result += $"{options.SiteTitle} doesn't match RegEx\n";
            }

            if (options.Scale < 0 || options.Scale > 1000)
            {
                result += $"{options.Scale} isn't within Range 0 - 1000\n";
            }

            if (_settings.Scale is 0 && _settings.VerbosityLevel <= _settings.Scale)
            {
                result += "VerbosityLevel must be > than Scale.";
            }

            return result != null 
                ? ValidateOptionsResult.Fail(result)
                : ValidateOptionsResult.Success;
        }
    }
}

IValidateOptions 允许将验证代码移入类中。

使用前面的代码,使用以下代码在 ConfigureServices 中启用验证:

services.Configure<SettingsOptions>(
    Configuration.GetSection(
        SettingsOptions.ConfigurationSectionName));
services.TryAddEnumerable(
    ServiceDescriptor.Singleton
        <IValidateOptions<SettingsOptions>, ValidateSettingsOptions>());

选项后期配置

使用 IPostConfigureOptions<TOptions> 设置后期配置。 后期配置在所有 IConfigureOptions<TOptions> 配置发生后运行,在需要重写配置的场景中非常有用:

services.PostConfigure<CustomOptions>(customOptions =>
{
    customOptions.Option1 = "post_configured_option1_value";
});

PostConfigure 可用于对命名选项进行后期配置:

services.PostConfigure<CustomOptions>("named_options_1", customOptions =>
{
    customOptions.Option1 = "post_configured_option1_value";
});

使用 PostConfigureAll 对所有配置实例进行后期配置:

services.PostConfigureAll<CustomOptions>(customOptions =>
{
    customOptions.Option1 = "post_configured_option1_value";
});

另请参阅