系统参数(Aegis.SystemSettings)
Aegis.SystemSettings 将宿主配置中的业务参数按系统、院区和分组组织起来。已知字段使用 IOptionsMonitor<T> 读取配置类,运行时才能确定的分组和参数名使用 ISystemSettings 读取;两种方式都支持院区覆盖默认值。
如何引入
安装 NuGet
dotnet add package Aegis.SystemSettings
启用组件
在宿主项目的 Component.deps.json 中,将 SystemSettings 加入 Load 清单:
{
"Components": {
"Load": [
"SystemSettings"
]
}
}
SystemSettings 不提供请求处理中间件。在 Load 中声明后,宿主会注册参数读取服务和配置类绑定。业务项目引用当前包,即可使用 ISystemSettings、SystemSettingsBindingAttribute 等公共类型。
配置当前系统编码
{
"SystemSettings": {
"SystemCode": "OP-Nurse"
}
}
SystemSettings:SystemCode 是当前宿主的必填系统编码。未单独指定系统的配置类和动态读取默认使用此编码;若在服务注册时调用 SetDefaultSystemCode,默认读取系统采用该调用指定的值。配置类显式声明的系统编码不受此默认值影响。
组件概览
| 字段 | 说明 |
|---|---|
| 组件名称 | 系统参数 |
| 真实类库 | Aegis.SystemSettings |
| 组件定位 | 按系统、院区和分组读取业务参数 |
| 引入方式 | 安装 NuGet,并在 Component.deps.json 中启用 SystemSettings |
| 默认参数来源 | 宿主已加载的 IConfiguration |
| 强类型入口 | IOptionsMonitor<T> |
| 动态入口 | ISystemSettings |
配置类属性与参数编码对应。使用指定院区读取时,组件先读取 _default 下的值,再应用该院区已经配置的字段。
什么时候要用它
适合以下场景:
- 参数属于可调整的业务规则,而不是代码常量。
- 同一套默认参数需要被不同院区局部覆盖。
- 业务代码希望使用强类型配置类,并在参数变化后读取新值。
- 需要在运行时切换系统、院区或分组。
以下内容继续使用其他配置能力:
- 数据库连接串、密钥和宿主端口等基础设施配置,应使用
appsettings.json、环境变量或专用密钥管理。 - 与当前系统无关的技术开关,不应为了集中展示而改造成业务参数。
最小可运行路径
第一步:在 appsettings.json 中准备参数
参数放在宿主已加载的配置中,例如 appsettings.json:
{
"SystemSettings": {
"SystemCode": "OP-Nurse",
"OP-Nurse": {
"_default": {
"Registration": {
"TimeoutSeconds": 60,
"AllowCrossSlot": false
}
},
"A": {
"Registration": {
"TimeoutSeconds": 30
}
}
}
}
}
_default 是全院区默认值,A 是 A 院区覆盖值。院区未配置的字段会继续使用默认值。
第二步:声明强类型配置
using Aegis.SystemSettings.Bindings;
/// <summary>
/// 挂号分组的默认参数及院区覆盖参数。
/// </summary>
[SystemSettingsBinding(GroupCode = "Registration")]
public sealed class RegistrationSettings
{
/// <summary>
/// 挂号操作允许等待的秒数。
/// </summary>
public int TimeoutSeconds { get; set; } = 60;
/// <summary>
/// 是否允许跨时段挂号。
/// </summary>
public bool AllowCrossSlot { get; set; }
}
GroupCode 需要与参数分组编码保持一致。未维护的字段保留 C# 属性初始值。
第三步:在业务服务中读取
using Microsoft.Extensions.Options;
/// <summary>
/// 每次调用均读取当前生效的挂号参数。
/// </summary>
/// <param name="settings">支持默认值和院区命名选项的配置监视器。</param>
public sealed class RegistrationService(IOptionsMonitor<RegistrationSettings> settings)
{
/// <summary>
/// 读取全院区默认参数。
/// </summary>
/// <returns>当前生效的默认挂号参数。</returns>
public RegistrationSettings GetDefault()
{
return settings.CurrentValue;
}
/// <summary>
/// 读取指定院区的覆盖参数,未配置字段沿用默认值。
/// </summary>
/// <param name="hospitalCode">院区编码。</param>
/// <returns>合并默认值和院区覆盖值后的挂号参数。</returns>
public RegistrationSettings GetForHospital(string hospitalCode)
{
return settings.Get(hospitalCode);
}
}
CurrentValue 读取全院区默认值;Get(hospitalCode) 先加载默认值,再叠加指定院区的覆盖值。院区编码由业务上下文显式传入,组件不读取隐式请求上下文。
院区参数覆盖
取值顺序是“全院区默认值打底,指定院区局部覆盖”。
| 读取方式 | TimeoutSeconds | AllowCrossSlot |
|---|---|---|
settings.CurrentValue | 60 | false |
settings.Get("A") | 30 | false |
settings.Get("B") | 60 | false |
B 院区没有单独配置时,整个结果来自全院区默认值。
按运行时坐标读取
编译期无法确定分组或参数编码时,注入 ISystemSettings:
using Aegis.SystemSettings.Bindings;
/// <summary>
/// 按运行时给定的院区、分组和参数名读取系统参数。
/// </summary>
/// <param name="settings">当前系统的参数读取入口。</param>
public sealed class DynamicSettingsService(ISystemSettings settings)
{
/// <summary>
/// 读取默认院区的挂号超时秒数。
/// </summary>
/// <returns>当前超时秒数;缺失或无法转换时返回 60。</returns>
public int GetDefaultTimeout()
{
return settings.Get("Registration", "TimeoutSeconds", 60);
}
/// <summary>
/// 读取指定院区的挂号超时秒数。
/// </summary>
/// <param name="hospitalCode">院区编码。</param>
/// <returns>院区值、默认院区值或缺省值 60。</returns>
public int GetHospitalTimeout(string hospitalCode)
{
return settings
.For(hospitalCode)
.Get("Registration", "TimeoutSeconds", 60);
}
/// <summary>
/// 读取业务要求必需存在的字符串参数。
/// </summary>
/// <param name="groupCode">参数所属分组。</param>
/// <param name="key">参数编码。</param>
/// <returns>已配置的字符串值。</returns>
/// <exception cref="InvalidOperationException">参数缺失或无法读取为字符串。</exception>
public string GetRequiredValue(string groupCode, string key)
{
return settings.Require<string>(groupCode, key);
}
}
| API | 语义 |
|---|---|
Get<T>(groupCode, key, defaultValue) | 参数缺失或无法转换时返回默认值 |
Require<T>(groupCode, key) | 参数缺失或无法转换时抛出异常 |
For(hospitalCode) | 切换到当前系统的指定院区 |
ForSystem(systemCode, hospitalCode) | 切换到指定系统和院区 |
Group(groupCode).As<T>() | 将分组绑定为一次性强类型快照 |
Group(groupCode).As<T>() 返回调用时的快照,后续参数变更不会修改已返回的对象。
跨系统读取
配置类固定读取另一个系统时,在绑定特性中指定 SystemCode:
using Aegis.SystemSettings.Bindings;
/// <summary>
/// 固定读取结算系统中的折扣参数。
/// </summary>
[SystemSettingsBinding(SystemCode = "Settle", GroupCode = "Discount")]
public sealed class BillingDiscountSettings
{
/// <summary>
/// 自费结算适用的折扣比例。
/// </summary>
public decimal SelfPayDiscountRate { get; set; }
}
系统编码由运行时参数决定时,使用 ISystemSettings:
var rate = settings
.ForSystem("Settle", hospitalCode)
.Get("Discount", "SelfPayDiscountRate", 1m);
一个强类型配置类只能对应一个系统和分组坐标。
绑定声明决定读取哪个系统和分组,参数仍需存在于宿主配置中。例如上面的配置类读取 SystemSettings:Settle:_default:Discount;按院区读取时,再叠加 SystemSettings:Settle:院区编码:Discount。
默认自动扫描项目程序集与 Aegis.* 框架程序集。配置类位于额外第三方程序集时,在宿主服务注册阶段追加其扫描范围:
services.AddSystemSettingsBindings(typeof(BillingDiscountSettings).Assembly);
这段注册用于补充扫描范围,不再对同一类型追加显式绑定。
显式注册配置类
配置类不适合添加 [SystemSettingsBinding] 特性时,可以在宿主中显式声明绑定:
services.AddSystemSettingsBinding<RegistrationSettings>(groupCode: "Registration");
指定另一个系统时:
services.AddSystemSettingsBinding<BillingDiscountSettings>(groupCode: "Discount", systemCode: "Settle");
同一类型不能同时使用特性绑定和显式绑定,冲突会在宿主启动时报错。
采用显式注册时,配置类不保留前面示例中的 [SystemSettingsBinding]。在 AddSystemSettings 回调内使用 AddBinding<T> 也遵循相同规则,同一类型只声明一次。
读取参数变化
IOptionsMonitor<T> 可以被任意生命周期的服务注入。宿主 IConfiguration 发出重载通知后,组件清除默认值和已读取过的院区缓存,后续读取会重新绑定。配置来源本身需要支持并触发重载;修改不支持重载的来源不会自动刷新参数。
业务只需要读取当前参数时,保存监视器,并在每次使用时获取对应院区的值:
using Microsoft.Extensions.Options;
/// <summary>
/// 按需读取 A 院区当前生效的挂号参数。
/// </summary>
/// <param name="settings">由系统参数组件维护的挂号参数监视器。</param>
public sealed class RegistrationPolicyReader(IOptionsMonitor<RegistrationSettings> settings)
{
/// <summary>
/// 每次读取时从监视器获取 A 院区的有效超时秒数。
/// </summary>
public int TimeoutSeconds => settings.Get("A").TimeoutSeconds;
}
配置缓存由监视器维护,每次属性访问通过 Get("A") 获取当时的有效配置。更新生效后,后续读取取得新值,之前保存的配置对象不会原地变化。
业务需要在参数变化时重建本地资源,可以按其生命周期订阅 OnChange,并协调初始构建与变更处理的并发。回调中的 name 不一定是某个院区编码,需要指定院区的新值时重新调用 Get(hospitalCode);订阅返回的 IDisposable 应在服务停止时释放。
JSON 字符串参数
IConfiguration.Bind 不会将一个值中的 JSON 文本自动反序列化为列表或嵌套对象。参数值本身是 JSON 字符串时,先读取字符串,再显式反序列化:
using System.Text.Json;
var raw = settings
.For(hospitalCode)
.Get<string>("Registration", "ExcludedDepartments");
var departments = string.IsNullOrEmpty(raw)
? []
: JsonSerializer.Deserialize<List<string>>(raw) ?? [];
int、bool、decimal 和 string 等基本类型可以直接读取。
接入后怎么确认生效
- 启动宿主,确认
ISystemSettings和已标注配置类的IOptionsMonitor<T>可以从 DI 解析。 - 读取
CurrentValue,确认与全院区默认值一致。 - 传入已配置的院区编码,确认只覆盖该院区已维护的字段。
- 读取不存在的参数,分别确认
Get返回默认值、Require抛出异常。
边界与限制
SystemSettings:SystemCode指定宿主的默认系统;配置类显式声明的SystemCode可以指向其他系统,并应与目标配置节的系统编码匹配。- 院区编码、分组编码和参数编码由业务代码与参数来源约定,应保持稳定。
IOptionsMonitor<T>适合已知字段的强类型读取;ISystemSettings适合运行时坐标,不提供编译期字段检查。Group(groupCode).As<T>()是一次性快照,不会自动更新已返回的对象。- 一个配置类只能使用一种绑定声明,不能同时使用特性和显式注册。
- 将 JSON 存入单个参数值时,需要由业务代码显式反序列化。
- 动态读取不会校验参数名是否拼写正确;关键参数可以使用
Require<T>,避免将默认值误认为已配置值。
常见问题
为什么读到的都是配置类默认值
按顺序检查 SystemCode、GroupCode、院区编码和属性名。系统编码需要匹配 SystemSettings 下的系统节,分组编码需要匹配绑定声明,配置类属性名需要与参数编码对应。
参数变化后会修改已取得的配置对象吗
不会。IOptionsMonitor<T> 在下一次读取时返回重新绑定的对象;业务代码长期保留的旧对象和 Group(groupCode).As<T>() 已返回的快照不会就地变化。