用途
该技能用于指导 .NET 应用中的配置处理,核心是 Microsoft.Extensions.Options 模式。适用场景包括:将 appsettings.json 中的配置绑定到强类型类;在应用启动时验证配置并快速失败;为设置实现复杂验证逻辑;设计可测试、可维护的配置类;理解 IOptions、IOptionsSnapshot 和 IOptionsMonitor 的区别。
主要能力
技能围绕配置验证展开,强调在启动阶段而非运行时发现配置错误。它提供了多种模式:
- 基础选项绑定:定义 Settings 类,通过 AddOptions<T>().BindConfiguration() 从配置节绑定,并在服务中通过 IOptions<T> 消费。
- 数据注解验证:使用 [Required]、[Range]、[EmailAddress] 等特性,配合 .ValidateDataAnnotations() 和 .ValidateOnStart() 启用。
- IValidateOptions 复杂验证:支持跨属性验证、条件验证、外部服务检查以及在验证器中注入依赖。数据注解先运行,随后运行 IValidateOptions 验证器,所有失败会一并收集。
- 选项生命周期:IOptions<T> 为单例、不随变更重载;IOptionsSnapshot<T> 为作用域、按请求重载;IOptionsMonitor<T> 为单例、支持变更回调,适合后台服务。
- 后配置:通过 PostConfigure 在绑定之后、验证之前修改选项。
使用方式
技能以代码示例展示各模式。基础绑定示例:
builder.Services.AddOptions<SmtpSettings>()
.BindConfiguration(SmtpSettings.SectionName);
启用数据注解验证与启动验证:
builder.Services.AddOptions<SmtpSettings>()
.BindConfiguration(SmtpSettings.SectionName)
.ValidateDataAnnotations()
.ValidateOnStart();
注册自定义验证器:
builder.Services.AddSingleton<IValidateOptions<SmtpSettings>, SmtpSettingsValidator>();
后台服务使用 IOptionsMonitor 并注册 OnChange 回调以获取实时更新。
适用场景
需要从 appsettings.json 读取配置并保证其正确性的 .NET 应用;希望在启动时而非业务逻辑深处暴露配置错误的项目;需要跨属性或条件验证的复杂设置;后台服务需要动态响应配置变更的场景。
限制与注意事项
技能列出了应避免的反模式:直接通过 IConfiguration 手动读取配置会绕过验证且难以测试;在构造函数中验证为时已晚;忘记调用 .ValidateOnStart() 会导致验证仅在首次访问时运行;在 IValidateOptions 中抛出异常会破坏验证链,应返回 ValidateOptionsResult.Fail。
参考文件 advanced-patterns.md 包含带依赖的验证器、命名选项、完整生产示例(AkkaSettings)以及验证器测试,但该文件的具体内容在提供的资料中暂未提供。