用途
该技能用于在 .NET 中实现 Options 模式,为配置组提供强类型访问。它将配置项绑定到专门的 Options 类,替代直接读取散落的配置键,从而在编译期获得类型检查,并在启动或运行期对配置进行集中校验。
主要能力
技能内容覆盖以下方面:
-
三种 Options 接口的选型说明:
IOptions<T>:单例(Singleton)生命周期,启动时读取一次,不支持重载,不支持命名选项,适用于静态配置。IOptionsSnapshot<T>:作用域(Scoped)生命周期,按请求重新加载,支持重载,支持命名选项,适用于请求级配置。IOptionsMonitor<T>:单例(Singleton)生命周期,支持重载,支持命名选项,适用于单例服务和变更通知场景。
-
Options 类目录结构:示例中 Options 类统一放在
/Application/Options/目录下,如DatabaseOptions.cs、JwtOptions.cs、CacheOptions.cs、EmailOptions.cs、FeatureFlagOptions.cs。 -
基础 Options 类模板:以
DatabaseOptions为例,约定使用Options后缀、提供公共 getter/setter、通过数据注解或IValidateOptions进行验证,并定义SectionName常量。示例包含连接字符串、连接池大小、超时、连接池开关、查询日志开关等属性。 -
数据注解验证模板:以
JwtOptions为例,使用[Required]、[MinLength]、[Range]等特性对 Secret、Issuer、Audience、访问令牌与刷新令牌过期时间进行约束。 -
自定义验证模板:以
CacheOptionsValidator实现IValidateOptions<CacheOptions>为例,演示复杂规则(如启用缓存时必须提供 Redis 连接字符串、滑动过期必须小于默认过期)的校验逻辑,并返回ValidateOptionsResult。 -
依赖注入注册模板:展示在
DependencyInjection.cs中通过services.Configure<T>、services.AddOptions<T>().Bind(...).ValidateDataAnnotations().ValidateOnStart()、注册自定义IValidateOptions、以及PostConfigure的多种注册方式。 -
在单例服务中使用
IOptions<T>:以JwtTokenService为例,通过options.Value读取一次配置,用于生成 JWT 令牌。 -
在作用域服务中使用
IOptionsSnapshot<T>:以SendEmailHandler为例,每次请求获取最新值;文档注明其不能注入到单例服务。 -
在单例中使用
IOptionsMonitor<T>:以FeatureFlagService为例,通过OnChange订阅配置变更并记录日志,通过CurrentValue读取当前值,并在Dispose中释放监听器。 -
命名选项:以
StorageOptions为例,定义Local与Cloud两个命名选项,展示 appsettings.json 结构、注册方式及在FileUploadService中通过optionsSnapshot.Get(...)访问命名选项的用法。 -
后台服务中的 Options:以
OutboxProcessorJob为例,说明后台服务是单例,应使用IOptionsMonitor<T>以获取配置更新而无需重启。
使用方式
按照技能提供的目录结构创建 Options 类,在 appsettings.json 中建立对应配置节,在依赖注入注册代码中完成绑定与验证注册,然后在服务构造函数中注入对应的 IOptions<T>、IOptionsSnapshot<T> 或 IOptionsMonitor<T> 并按需读取值。验证可在启动时通过 ValidateOnStart() 快速失败。
适用场景
适用于采用整洁架构的 .NET 项目,尤其是需要将数据库、JWT、缓存、邮件、功能开关、存储、发件箱等配置组进行强类型化管理,并需要对配置进行启动校验或运行时热更新的场景。
限制
文档明确指出 IOptionsSnapshot<T> 不能注入到单例服务中。各接口的生命周期与重载能力差异需按表格选型。关于具体价格、收费、平台依赖或其他未在资料中提及的功能,暂未提供。