配置持久化、重载与对象所有权
ConfigHandler 负责应用设置 JSON 的读取、实例缓存、合并写入和备份恢复;ConfigService 只是可替换的 IConfigService 入口。文件保存、运行期对象发布和订阅者重绑定是不同完成条件,不能用“保存方法返回”统一代表。
本主题不处理设备资源的 MySQL 保存,也不定义属性编辑事务:分别见设备资源配置和属性编辑器契约。配置恢复点的界面入口由配置页维护控件负责;软件设置、流程和结果各自的备份范围见导入导出边界。
配置路径由谁决定
ConfigHandler.GetInstance(name) 第一次创建实例时调用 Load,初始化路径并注册 ConfigService.Instance;后续即使传入不同名称,也返回既有实例,不切换配置文件。仅 new ConfigHandler() 不会自动执行 Load。
InitializePaths 默认文件名前缀为入口程序集名加 Config,显式 ConfigDIFileName 可替代这个前缀:
| 条件 | 主文件与备份目录 |
|---|---|
当前工作目录中已存在相对 Config 目录 | Config/<ConfigDIFileName>.json 与 Config/Backup |
| 不存在该相对目录 | ApplicationData/<入口程序集公司名>/Config/<ConfigDIFileName>.json 与其 Backup 子目录;公司名缺失时使用程序集名 |
最终路径用 Path.GetFullPath 规范化。这里判断的是工作目录,不是可执行文件所在目录;启动方式改变工作目录可能选择另一份配置。Load 会创建必要目录,且坏文件加载可能触发备份恢复写回,所以首次获取单例不是保证无副作用的只读查询。
Load 时若 IsAutoSave=true,会安排一次约两分钟后的备份;不是持续的周期保存。退出处理器会注册,并在退出时检查 IsAutoSave 决定是否保存。关闭该标志不会禁止显式保存/备份,也不会取消已安排的延迟备份。
配置类型、延迟构造与适配器
IConfig 是标记接口,不要求配置类实现 Load / Save。ConfigHandler 用 ConcurrentDictionary<Type,IConfig> Configs 缓存已取得的对象;读取正常 JSON 后,先保留 JObject,等 GetRequiredService(type) 才按需反序列化。
内存键是 Type,JSON 节名由 ConfigSectionNames.GetSectionName(type) 决定:标注 [ConfigSection("名称")] 时使用声明的名称,否则使用 type.FullName,包括命名空间,且不包含程序集版本。例如主程序与 Spectrum 分别使用 ColorVision.MainWindowConfig 和 Spectrum.MainWindowConfig,不会因类名相同而互相覆盖。
读取按 GetReadCandidates 的顺序取第一个存在的键:声明名称、Aliases 中的旧名称、完整类型名,最后是旧的 type.Name 节,以保留旧数据库连接等配置。排在前面的键已存在但值为空、无效或无法反序列化时,不再用后面的键覆盖它,而是进入原有默认回退。未标注的类型改名、命名空间改名不自动迁移旧的完整键;需要改名的配置类型应先标注 ConfigSection,把原完整类型名作为名称或别名。
单节、全量、备份和导出保存均以此节名写入已实例化的配置,保留合并来源中未覆盖的旧短键和插件节。新旧键同时存在时优先读取完整键。已有旧同名节中被覆盖的值无法自动还原;尚未分别保存的同名类型仍可能从同一个旧节取得初始值,各自保存后使用独立完整键。全量快照遇到相同完整键会报告冲突并拒绝写入。
缺少可读取的节或反序列化/解密失败时尝试无参默认构造,失败的反序列化会记日志;默认构造自身失败仍可能抛出。反序列化或解密失败时,原节先另存到 <BackupFolderPath>/Quarantine/<ConfigDIFileName>_<节名>_<时间>.json,之后的保存仍可能用默认值覆盖主文件中的这一节。隔离文件不参与滚动备份清理,也不会被自动读回;恢复需人工比对后写回。未设置 BackupFolderPath 的 handler 不写隔离文件。
ConfigService.SetInstance 只替换服务引用,不加载文件或迁移旧对象。不同实现不能混用持久化假设:
| 实现 | 对象解析责任 | 文件保存/加载 |
|---|---|---|
ConfigHandler | 按类型缓存,从 JSON 或默认构造取得对象 | 实现本页文件契约 |
SelfManagedConfigServiceAdapter | 延迟读取公开静态 Instance 并缓存 | SaveConfigs、LoadConfigs、Save<T> 均抛 NotSupportedException |
HybridConfigServiceAdapter | 显式注册优先,否则解析静态 Instance;重新注册会清除此类型解析缓存 | 同上,不实现持久化 |
AspNetCoreConfigServiceAdapter | 委托 IServiceProvider.GetService,生命周期由外部容器决定 | 同上,不实现持久化 |
两个静态实例适配器的缓存是普通字典,不具备 ConfigHandler 的保存事务机制。不要因接口相同就推断全部实现都支持配置落盘或重载通知。
重载会替换对象,不是原地更新
ApplyLoadedConfig 替换内部 jsonObject,并把整个 Configs 换成新的空字典。之后取得的配置对象是新实例;旧对象、其集合和事件订阅不会自动迁移。
| 入口 | 行为与失败语义 |
|---|---|
Reload() | 先 SaveConfigs,再 LoadConfigs;可能先把旧内存值覆盖到外部修改过的文件,不是纯粹接纳磁盘修改 |
ReloadFromDisk() | 不先保存;读失败则抛错,在文件验证阶段保留已加载对象;成功后替换缓存并额外重绑 Authorization.Instance |
LoadConfigs(fileName) / 无参版本 | 加载指定文件或主文件;缺失/损坏时进入备份/默认回退;指定文件名不改变后续保存使用的 ConfigFilePath |
LoadDefaultConfigs() | 名称虽是“默认”,仍先尝试最新有效备份;本方法自己不发布 ConfigsReloaded,异常记录后吞掉 |
普通 LoadConfigs 不负责重绑 Authorization.Instance;启动 Load 和 ReloadFromDisk 分别另做这一步。不能把重载理解为所有静态对象已经刷新。
LoadConfigs / ReloadFromDisk 在状态替换和事务结束后同步直接调用 ConfigsReloaded。它不是统一的 UI Dispatcher 派发,也没有逐订阅者异常隔离;一个订阅者抛错可能阻止后续订阅者,且已替换的缓存不会因此回滚。订阅者应重新取得配置,解除旧对象订阅,并在自身线程/生命周期边界处理未结束工作;保留旧引用的模块仍可能继续使用旧值。
ConfigSettingManager 的设置元数据也缓存 Source 对象。InvalidateCache 只清设置项缓存,不清程序集类型缓存,也不会自动改写已打开控件的绑定。配置服务本身不自动替所有使用方调用该方法;窗口发现、搜索和页面复用见设置窗口,具体编辑器和导入链分别见属性编辑、导入导出。
保存是合并目标文件,不是完整内存镜像
SaveConfigs(fileName) 先序列化 Configs.ToArray() 中已实例化的配置,再在锁内重新读取目标文件,移除 ConfigOptions 和 MarketplaceServiceConfig 两个明确过期节,然后把快照中的节覆盖到目标 JSON。其余未被覆盖的目标节保留。
这带来三个边界:
- 保存主文件时,未实例化节通常由现有主文件保留;并非保存前自动实例化所有配置。
- 通过
SaveConfigs(fileName)导出到新文件时,只写已实例化节。滚动备份另有恢复用途,会包含主文件中的未实例化节。 - 保存到已有其它文件时,可能保留那个目标里的旧节;不是“精确替换为当前内存所有内容”。
任一已实例化节序列化失败,CreateConfigSnapshot 汇总错误并抛出,不写部分成功节。已有目标文件若不是一个完整 JSON 对象,保存会拒绝覆盖;尾随其它内容也视为无效。目标不存在时才从空对象开始。
TrySave<T>(candidate) 同样先移除过期节,再只把 typeof(T) 的节名对应节合并到主文件,保留其它目标节;它既不把 candidate 自动注册进 Configs,也不更新内部 jsonObject。另建候选对象保存成功后,已有缓存可能仍旧;尚未实例化的类型也可能继续从旧加载快照取值。运行期发布应由调用方明确完成,不能假设保存方法已重绑所有消费者。
单文件写入、锁和事务版本
文件锁、读取校验和原子写入由内部的 ConfigFileStore 负责,ConfigHandler 与 ConfigMaintenanceResetService 共用它。ConfigFileStore.Write 在目标同目录创建独占临时文件,写入 UTF-8 JSON,刷新写入及磁盘,重新读取验证后,已有目标用 File.Replace,新目标用 File.Move 提交。提交前的序列化/写入失败不会先截断旧文件;临时文件在 finally 尝试清理,清理失败只记警告。File.Replace 没有创建备份文件,历史备份是独立机制。
互斥分为两层:
- 每个 handler 的保存状态锁和
_saveTransactionVersion排序保存/重载。全量快照在事务外生成;期间若本 handler 保存或重载已提交,版本不符就重新取快照,避免写入已失效快照。 - 文件锁用规范化绝对路径的大写形式计算 SHA-256,取得名为
Local\ColorVision.ConfigSave.<hash>的命名 Mutex,等待上限 30 秒;废弃 Mutex 视为成功取得。不同 handler 针对同一路径的读—合并—写可由它串行化。
这里的版本是 handler 内部事务计数,不是配置 schema 版本或跨进程乐观锁。普通属性赋值、其它 handler 的内存变化或绕过此实现的直接文件写入不受该计数保护;Local Mutex 也不是跨会话/跨机器锁。ConcurrentDictionary 不会把所有配置对象和集合变成线程安全快照。
序列化会经 Application.Current.Dispatcher 同步执行;没有应用 Dispatcher 时在当前线程执行。保存不仅是后台文件 I/O。文件替换的原子提交不等于内存对象图、多个文件和外部副作用的一次原子事务。
IConfigSecure 的边界
加载成功反序列化的 IConfigSecure 对象时调用 Decrypt;失败会记录并回退默认实例。保存时先把 candidate 序列化/反序列化为副本,只对副本调用 Encryption,再序列化副本写盘。
加密钩子失败时保留原 candidate。加密范围、密钥管理和属性访问的副作用由实际实现决定。配置 JSON 仍按敏感资料保护。
落盘、内存发布与回滚
TrySaveAndPublish(candidate, onPersisted, out error) 先完成文件提交、释放文件 Mutex,再调用同步 Action onPersisted;handler 保存事务在发布结束后才结束。这个回调由调用者负责内存更新/通知,不是自动的 ConfigsReloaded。
| 返回状态 | 已完成什么 | 未自动完成什么 |
|---|---|---|
NotPersisted | 本次写盘未成功,错误通过 error 返回 | 不撤销调用者此前对活对象的修改 |
PersistedAndPublished | 文件提交成功,所提供的发布回调正常返回 | 不证明每个业务消费者已生效,也不等待回调之外的异步工作 |
PersistedButPublishFailed | 文件已提交,发布回调抛错 | 不回滚磁盘;回调已做的一部分内存更新也不自动撤销 |
发布阶段以 AsyncLocal 标记防止同一 handler 重入保存,继承该执行上下文的任务也会被拒绝;不要在发布回调里再触发保存。文件 Mutex 已释放,其它 handler 此时仍可提交自己的写入,不能把“落盘 + 发布”当作全局隔离事务。
TrySave 不传发布回调,返回 true 只证明这次持久化路径成功。Save<T>() 取得缓存对象后调用 TrySave,丢弃布尔结果和错误信息;它正常返回不证明文件保存成功。SaveConfigs 则直接传播序列化/写入错误。处理故障时先区分“写盘失败”“已写盘但发布失败”“保存包装方法吞掉结果”,不能统一声称已经回滚。
在应用日志中搜索 ConfigSectionsSaved 可核对主配置落盘的时间、机器、文件及有变化的配置节。日志省略节内容和 IConfigSecure 节,避免把加密重新生成的密文误判为设置变化。这个事件记录文件提交,与后续内存发布的结果独立。
备份、损坏文件与导入范围
先区分设置值不合适、文件损坏和恢复默认,不把它们都当作同一种恢复操作:
| 情况 | 当前行为与核对点 |
|---|---|
| 选项改错,但文件仍能解析为 JSON 对象 | LoadConfigs 正常加载,不因选项不合适而自动选择旧备份;先确定需要恢复哪些配置节及备份范围 |
| 主文件缺失或内容损坏 | 普通 LoadConfigs 尝试下面的最新有效滚动备份;ReloadFromDisk 读失败时拒绝重载,不自动恢复 |
调用 LoadDefaultConfigs | 先尝试滚动备份;备份不可用或恢复失败时进入默认回退,不能按方法名理解为直接恢复出厂设置 |
| 从备份成功加载配置 | 缓存对象会被替换,仍需使用方重新取得对象并处理订阅;不保证已打开窗口自动刷新 |
主程序另行注册非关键配置节白名单,提供 ConfigMaintenanceResetService 选择性维护重置:只记录计划,在下一次配置 Load、正常加载与实例化之前处理,完整原文件备份成功后才提交。它不使用 LoadDefaultConfigs 的旧备份回退,也不在运行中替换对象。独立备份、启动准入、取消、崩溃幂等与部分失败语义由存储清理与设置重置定义,不能将它与下面的滚动 BackupConfigs 混为一谈。
BackupConfigs 以最新有效主文件为基础保留未实例化节,再覆盖当前已实例化节。主文件缺失时使用上次加载的 JSON 作为基础,主文件损坏时跳过本次备份,避免不完整快照被选作恢复点。备份写入 <ConfigDIFileName>Backup_yyyyMMdd_HHmmss.json,同一秒使用同一目标。按文件名倒序最多保留 10 个备份。异常记日志。
普通加载遇到主文件缺失或损坏时,按文件名倒序寻找最新有效备份。扫描后在主文件锁内重新读取,若另一实例已修复主文件,则加载当前内容。主文件仍不可用时,才把有效备份写回并加载。恢复失败或仍无有效文件时扫描已加载程序集构造默认配置,跳过无法构造的类型。显式 LoadDefaultConfigs 仍可用备份替换可读主文件。
默认回退不会保证已修复损坏的主文件;若坏文件仍在,后续保存仍可能被“拒绝覆盖无效 JSON”的保护拦下。ReloadFromDisk 不使用这套自动恢复,它在读文件失败时拒绝重载。
“配置恢复点”使用独立的 MaintenanceBackups 完整文件备份,不参与上述 Backup 滚动备份选择;不要混用两种目录及恢复假设。配置文件加载也不恢复数据库、插件和全部资源,具体范围见设置导入导出契约。单文件提交不构成跨文件迁移或整个运行状态的回滚保证。
验证入口与缺口
真实多进程的配置并发和故障恢复需在实际环境验证。
工作目录切换、未实例化节的导出完整性、订阅者抛错后的其它消费者、跨会话写入、进程崩溃/磁盘故障和实际导入补偿仍需专门验证;本主题不授权对真实配置进行保存、导入、回退或备份清理。
