【转】[C#] 项目里的配置文件与选项对比

博客园 - z5337

【转】禁用 Chrome 浏览器的自动更新【转】Avalonia 12 最小信创项目模板【转】Avalonia 周边介绍【转】国产操作系统对 Avalonia 的支持情况【转】国产操作系统优化篇 [openKylin] 入门知识点【转】国产操作系统优化篇 [openKylin] 第一步 - Qt + VMware 【转】p2055dn 打印机配置 IP 地址【转】Windows 锁屏后屏幕不熄灭排查【转】既然 java 8 因为组件容易被攻击，.net core 也有大量第三方组件，是不是也容易出问题【转】最小 web api 学习【转】使用记事本区分图片格式【转】蓝牙耳机的播放控制【转】JoyToKey 键位映射【转】[C#] 要从接口取时间，单个订单查询和批量查询，写一个接口还是两个接口合适？【转】[C#] Web API 中的常见层次【转】[C#] .net core 项目的目标框架设置【转】[C#] GlobalUsing 的使用【转】[.net core] 项目的 Windows 服务器部署【转】《三字经》全文【转】[IDEA] 调试时怎么判断使用哪个配置文件【转】PO、DO、VO、BO、DTO、DAO、POJO 的区别【转】[web]怎么移除网页最上层的水印【转】[C#] 30+个.NET开发最佳实践【转】[C#] WPF 保留选中的高亮色【转】Windows Server 系统的桌面上显示此电脑图标【转】[C#] 参数前加 in 的作用【转】[C#] Enum 的 Flags 特性【转】[C#] Tuples 元组介绍【转】[C#] Record 的使用【转】[C#] 预处理指令

z5337 · 2025-10-17 · via 博客园 - z5337

参考：https://furion.net/docs/configuration

参考：https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/configuration/options?view=aspnetcore-9.0&preserve-view=true

优点
- 能够在系统运行时快速读取
- 无需额外配置
缺点
- 存在重复读取
- 通过硬编码字符串读取，容易出错
- 不能设置默认值
- 不能在运行环境中动态配置
- 不能验证配置有效性
- 不支持更改通知

如果只需要一次性读取配置信息，则使用配置，否则应该使用《4.2 选项》代替。

选项是 ASP.NET Core 推荐的动态读取配置的方式，这种方式将配置文件数据用一个强类型来托管，能够实现配置验证、默认值配置、实时读取等功能。

选项实际上也是配置，但在后者的基础上添加了配置验证、默认值/后期配置设定及提供了多种接口读取配置信息，同时还支持供配置更改通知等强大灵活功能。

所以，除了一次性读取使用的配置以外，都应该选用选项替换配置。

假设我们需要在系统运行时获取系统名称、版本号及版权信息，这些信息可能随时变化而且需要在多个地方使用。这时就需要将这些信息配置起来。具体步骤如下：

4.2.3.1 配置 `appsettings.json` 信息

{
  "AppInfo": {
    "Name": "Furion",
    "Version": "1.0.0",
    "Company": "Baiqian"
  }
}

4.2.3.2 创建 `AppInfoOptions` 强类型类

using Furion.ConfigurableOptions;

namespace Furion.Application
{
    public class AppInfoOptions : IConfigurableOptions
    {
        public string Name { get; set; }
        public string Version { get; set; }
        public string Company { get; set; }
    }
}

温馨提示

建议所有选项类都应该以 Options 命名结尾。

另外，Furion 框架提供了非常灵活的注册选项服务的方法，只需要继承 IConfigurableOptions 接口即可，该接口位于 Furion.ConfigurableOptions 命名空间下。

4.2.3.3 注册 `AppInfoOptions` 服务

选项不同于配置，需在应用启动时注册

Furion.Web.Core\FurWebCoreStartup.cs

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;

namespace Furion.Web.Core
{
    [AppStartup(800)]
    public sealed class FurWebCoreStartup : AppStartup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddConfigurableOptions<AppInfoOptions>();
        }
    }
}

4.2.3.4 读取 `AppInfoOptions` 信息

在 Furion 框架中，提供了多种读取方式：

通过 App.GetConfig<TOptions>(path) 读取（不推荐）
通过依赖注入以下实例读取：
- IOptions<TOptions>
- IOptionsSnapshot<TOptions>
- IOptionsMonitor<TOptions>
通过 App 静态类提供的静态方法获取：
- App.GetOptions<TOptions>()
- App.GetOptionsMonitor<TOptions>()
- App.GetOptionsSnapshot<TOptions>()

特别注意

禁止在主机启动时通过 App.GetOptions<TOptions> 获取选项，如需获取配置选项理应通过 App.GetConfig<TOptions>("配置节点", true)。

App.GetConfig<TOptions>(path)
依赖注入方式
App.GetOptions<TOptions>()

using Furion.Application;
using Microsoft.AspNetCore.Mvc;

namespace Furion.Web.Entry.Controllers
{
    [Route("api/[controller]")]
    public class DefaultController : ControllerBase
    {
        [HttpGet]
        public string Get()
        {

4.2.3.5 如何选择读取方式

如果选项需要在多个地方使用，则无论任何时候都不推荐使用 App.GetOptions<TOptions>()
在可依赖注入类中，依赖注入 IOptions[Snapshot|Monitor]<TOptions> 读取
在静态类/非依赖注入类中，选择 App.GetOptions[Snapshot|Monitor]<TOptions>() 读取

ASP.NET Core 应用提供了多种读取选项的接口：

IOptions<TOptions>：
- 不支持：
  - 在应用启动后读取配置数据
  - 命名选项
- 注册为单一实例且可以注入到任何服务生存期
IOptionsSnapshot<TOptions>：
- 在每次请求时应重新计算选项的方案中有用
- 注册为范围内，因此无法注入到单一实例服务
- 支持命名选项
IOptionsMonitor<TOptions>：
- 用于检索选项并管理 TOptions 实例的选项通知。
- 注册为单一实例且可以注入到任何服务生存期。
- 支持：
  - 更改通知
  - 命名选项
  - 可重载配置
  - 选择性选项失效 (IOptionsMonitorCache<TOptions>)

注意事项

在使用 IConfigurableOptionsListener 监听选项后，如要获取最新的配置信息，请使用 App.GetOptionsMonitor<TOptions>() 而不是 App.GetOptions<TOptions>()。

我们知道，选项实际上需要和配置文件特定键值挂钩，那 Furion 是如何准确的找到配置文件中的键值的呢？

4.2.5.1 选项查找键流程

没有贴 [OptionsSettings] 特性
- 以 Options 结尾，则去除 Options 字符串
- 否则返回 类名称
贴了 [OptionsSettings] 特性
- 如果配置了 Path 属性，则返回 Path 的值
- 否则返回 类名称

无[OptionsSettings]
有[OptionsSettings]

以 Options 结尾，则键名为：AppInfo

public class AppInfoOptions : IConfigurableOptions
{
    public string Name { get; set; }
    public string Version { get; set; }
    public string Company { get; set; }
}

不以 Options 结尾，则键名为：AppInfoSettings

public class AppInfoSettings : IConfigurableOptions
{
    public string Name { get; set; }
    public string Version { get; set; }
    public string Company { get; set; }
}

选项类可以通过 [OptionsSettings] 来配置查找路径值。

Path：对应配置文件中的键，支持分层键字符串，参见：《4.1 配置 - 4.1.3 路径符查找节点》
PostConfigureAll：选项后期配置，默认 false。ASP.NET Core - 选项 - 选项后期配置

选项支持验证配置有效性，在 Furion 框架中，通过 services.AddConfigurableOptions<TOptions>() 注册选项默认启用了验证支持。

包括：

特性方式 DataAnnotations
自定义复杂验证 IValidateOptions<TOptions>

特性方式
复杂验证

using Furion.ConfigurableOptions;
using System.ComponentModel.DataAnnotations;

namespace Furion.Application
{
    public class AppInfoOptions : IConfigurableOptions
    {
        [Required(ErrorMessage = "名称不能为空")]
        public string Name { get; set; }
        [Required, RegularExpression(@"^[0-9][0-9\.]+[0-9]$", ErrorMessage = "不是有效的版本号")]
        public string Version { get; set; }
        [Required, MaxLength(100)]
        public string Company { get; set; }
    }
}

特别说明

IConfigurableOptions<TOptions, TOptionsValidation> 继承自 IConfigurableOptions<TOptions>，也就是自定义复杂验证默认具有 PostConfigure(TOptions options) 选项后期配置方法。关于《4.2.8 选项后期配置》将在下一小节说明。

选项后期配置通俗一点来说，可以在运行时解析值或设定默认值/后期配置等。

在 Furion 框架中，配置选项后期配置很简单，只需要继承 IConfigurableOptions<TOptions> 接口并实现 PostConfigure(TOptions options) 方法。

using Furion.ConfigurableOptions;
using Microsoft.Extensions.Configuration;
using System.ComponentModel.DataAnnotations;

namespace Furion.Application
{
    public class AppInfoOptions : IConfigurableOptions<AppInfoOptions>
    {
        [Required(ErrorMessage = "名称不能为空")]
        public string Name { get; set; }
        [Required]
        public string Version { get; set; }
        [Required, MaxLength(100)]
        public string Company { get; set; }

        public void PostConfigure(AppInfoOptions options, IConfiguration configuration)
        {
            options.Name ??= "Furion";
            options.Version ??= "1.0.0";
            options.Company ??= "Baiqian";
        }
    }
}

特别说明

IConfigurableOptions<TOptions, TOptionsValidation> 继承自 IConfigurableOptions<TOptions>，也就是自定义复杂验证默认具有 PostConfigure(TOptions options, IConfiguration configuration) 选项后期配置方法。

Furion 框架提供了非常简单且灵活的方式监听选项更改，也就是 appsettings.json 或自定义配置文件发生任何更改都会触发处理方法。

使用非常简单，只需要继承 IConfigurableOptionsListener<TOptions> 接口并实现 void OnListener(TOptions options, IConfiguration configuration) 方法即可。

using Furion.ConfigurableOptions;

namespace Furion.Application
{
    public class AppInfoOptions : IConfigurableOptionsListener<AppInfoOptions>
    {
        public string Name { get; set; }
        public string Version { get; set; }
        public string Company { get; set; }

        public void OnListener(AppInfoOptions options, IConfiguration configuration)
        {
            var name = options.Name;

特别说明

IConfigurableOptionsListener<TOptions> 继承自 IConfigurableOptions<TOptions>。

4.2.9.1 关于多次触发问题

在 Furion 底层使用的是 ChangeToken.OnChange 监听文件更改，但是此方式会导致 OnListener 触发两次，这并非是框架的 bug，而是 .NET Core 本身存在的问题，详见：https://github.com/dotnet/aspnetcore/issues/2542

所以，Furion 框架也给出另一种解决方案可替代 IConfigurableOptionsListener 的方式，也就是通过局部注入 IOptionsMonitor 的方式，如：

public class YourService : IYourService, IDisposable
{
    private readonly IDisposable _optionsReloadToken;

    private YourOptions _options;

    public YourService(IOptionsMonitor<YourOptions> options)
    {
        (_optionsReloadToken, _options) = (options.OnChange(ReloadOptions), options.CurrentValue);

这种方式虽然啰嗦，但是可以很好和业务代码契合。

优点
- 强类型配置
- 提供多种读取方式
- 支持热加载
- 支持设置默认值/后期配置
- 支持在运行环境中动态配置
- 支持验证配置有效性
- 支持更改通知
- 支持命名选项
缺点
- 需要定义对应类型
- 需要在启动时注册

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

博客园 - z5337

4.2.3.1 配置 appsettings.json 信息

4.2.3.2 创建 AppInfoOptions 强类型类

4.2.3.3 注册 AppInfoOptions 服务

4.2.3.4 读取 AppInfoOptions 信息

4.2.3.5 如何选择读取方式

4.2.5.1 选项查找键流程

4.2.9.1 关于多次触发问题

4.2.3.1 配置 `appsettings.json` 信息

4.2.3.2 创建 `AppInfoOptions` 强类型类

4.2.3.3 注册 `AppInfoOptions` 服务

4.2.3.4 读取 `AppInfoOptions` 信息