配置向导:步骤、应用与完成边界
UI/ColorVision.UI.Desktop/Wizards/ 负责通用向导窗口;IWizardStep 和 IWizardInitializer 定义在 ColorVision.Common,具体步骤由主程序或插件提供。向导是有副作用的配置流程,不是只读说明页;它也不是设置窗口的另一个外观。
ColorVision/App.xaml.cs 在一次性维护参数要求进入向导、恢复选择要求重新配置,或 WizardCompletionKey 为 false 时显示非模态 WizardWindow,否则进入 StartWindow。完整启动和恢复分流见主程序运行时与首次启动。
运行中可通过应用搜索查找“初始化向导/向导/setup”。这是搜索专用高级维护入口,不恢复普通菜单,也没有默认快捷键。执行前通过共享策略检查 maintenance.setup.open 动作和 application 资源,默认要求应用管理员;允许后直接以主窗口为 Owner 打开 new WizardWindow(runInitializers: false) 对话框,不确认或重启。入口不把 WizardCompletionKey 改为 false,也不清空现有配置;动作授权不表示窗口中后续步骤已获 Windows 权限或设备许可。运行期维护动作与启动交接见运行时维护入口。
发现、排序与初始化
WizardManager 和 WizardWindow 实际都在 Wizards/WizardWindow.xaml.cs,没有独立的 WizardManager.cs。每次窗口初始化都会调用 manager 的 Initialized(),清空列表并从 AssemblyHandler.GetAssemblies() 的缓存/过滤视图重新扫描非抽象类型,分别无参构造 IWizardStep 和 IWizardInitializer,各自按 Order 升序排序。
该扫描不去重,也没有逐程序集/逐类型的异常隔离;反射或构造失败可能中断发现,并且发生在窗口延迟初始化的异常处理之外。实现两个接口的同一类型会分别构造,不保证共享同一实例。DLL 在磁盘上或已被任意方式加载,都不足以证明它进入了该扫描视图。
IWizardStep 没有 IsVisible 或统一的隐藏/跳过属性,manager 也不按可见性筛选。不要把其它菜单或属性编辑器的可见性规则套到向导,或推断“不可见步骤会连同启动初始化一起跳过”。
原无参构造保持启动行为;显式 runInitializers: false 仍发现并构造步骤和 initializer 对象、刷新和应用步骤,但不执行 IWizardInitializer.Initialize 链。它不是“只读查看”模式,步骤自己仍可能修改配置或安装软件。
默认构造下,IWizardInitializer 是独立的同步链,不是 StartWindow 执行的 IInitializer 链:
| 条件 | 窗口何时执行向导 initializer |
|---|---|
没有任何步骤声明 RunsBeforeInitializers | 延迟初始化时先运行 initializer,再显示第一步 |
| 存在先行步骤 | 前进到一个非先行步骤前,检查此前所有先行步骤的 ConfigurationStatus;都为 true 时运行 |
| 到完成入口仍未运行 | 当前页 Apply 成功后运行 |
RunsBeforeInitializers 默认等于 IsRequired,不重排 Order。前进门禁只检查目标页之前的先行步骤,不保证排在后面的先行步骤已经完成;实现步骤时必须一并核对实际排序。
窗口在调用前就设置 _initializersRun=true,没有统一的失败重试/补偿协议。每个 initializer 得到含 Owner、IsFirstRun 的 context;RequestSkipWizard() 会停止后续 initializer,并直接进入“置完成标记 → 保存 → 关闭或发起重启”的流程,不是仅跳过当前页面。
导航不是无副作用的翻页
| 动作 | 当前执行契约 |
|---|---|
| 显示一步 | 设置当前 DataContext、列表选择和进度,调用 RefreshAsync();刷新异常只记录警告,不自动把配置状态改成失败 |
| 下一步 | 检查转换状态、索引及 CanContinue,先调用当前步 ApplyAsync();返回 false 或抛异常时停留,否则按初始化时序前进 |
| 上一步 | 检查转换状态和索引,切到前一步并 Refresh;不 Apply 当前页,也不撤销此前操作 |
| 配置按钮 | 调用该步骤的 Command,实际行为由步骤实现,不能由通用窗口推断 |
默认 CanContinue 为 !IsBusy && (!IsRequired || ConfigurationStatus),HasError 本身不是独立阻塞条件。WizardStepBase.ConfigurationStatus 初始为 true,默认 ApplyAsync 也返回 true;这些默认值不是配置检查或外部服务健康证据。窗口转换中的 _isTransitioning 与步骤自己的 IsBusy 也不是同一个状态。
例如,ColorVision/Wizards/RecommendedSoftwareWizardStep.ApplyAsync 会安装选中的推荐软件;全部取消选择也允许该步骤完成。AI 不能为了查看后一页而默认执行“下一步”,更不能将前进或后退当作安装事务的提交/撤销。
ColorVision/Wizards/ApplicationUpdateWizardStep 是安装服务之前的第一步(Order=-1100),属于 initializer 之前的可选步骤。进入时复用主程序更新元数据检查,只显示当前版本及检查结果;发现新版后,只有用户点击“更新到…”才通过现有 AutoUpdater.StartUpdatePlan 下载并交接更新,不检查或更新插件。断网、更新服务不可用或检查异常都允许“下一步”;失败响应携带的缓存更新计划不作为可执行的新版本。该页的“下一步”只将本次步骤标为已处理,不下载或启动更新。
显式更新前先将 WizardCompletionKey=false 并保存配置,因此即便从运行中的维护入口重新打开向导,更新后下次正常启动也会再次显示安装向导,从版本检查开始继续安装服务和后续配置;不把更新当作完成配置。保存失败时恢复原内存标记并阻止更新。更新交接期间禁用步骤操作和前进,防止尚在下载时完成向导覆盖该标记;下载或启动失败后恢复操作,可重试或跳过。更新制品、实际应用替换及重启仍由既有更新链路负责,保存向导标记不证明更新成功。
CameraDriverWizardStep 是推荐软件之后、initializer 之前的可选相机驱动步骤。进入时异步检查 Windows 已登记的 ColorVision 相机 INF 及系统目录内 FW/IO 两个驱动文件的版本,不要求相机已经连接;卸载注册表项只作为残留安装线索,不能单独证明安装完成。检查范围是此驱动家族的安装信息,不验证签名、当前设备绑定、固件启动或采集,也不因检测到旧版驱动就自动升级。
“驱动安装与修复”打开 ColorVision/ToolPlugins/CameraDriver/CameraDriverWindow,常用工具中也有“相机驱动”入口。窗口显示系统登记、FW 与 IO 驱动版本,提供重新检测以及“下载并安装/下载并重新安装”;检测到已安装仍允许显式重装,以便处理设备无法识别的情况,不主动卸载或删除系统驱动。
安装和重装均通过现有 IDownloadService 打开下载管理器,使用工具包缓存与配置的下载认证,从软件下载服务器 Tool/ColorVisionDriver/ColorVisionDriver240301win10.exe 下载完整 EXE;/browse/Tool/ColorVisionDriver 是浏览页,文件使用 /download/Tool/ColorVisionDriver/ColorVisionDriver240301win10.exe 地址。主程序不捆绑该 EXE。当前选择固定为 240301 版,下载后检查文件路径与已核对的 SHA-256;以后更新制品时同步核对 URL、文件名、哈希及驱动身份,不从目录中自动执行任意 EXE。
用户应先断开相机 USB,再点击下载并安装/重装。下载完成且窗口仍打开时,以管理员权限启动原厂完整安装包,保留交互窗口,禁止外层安装器自动重启;安装日志写到当前用户的 LocalApplicationData/ColorVision/Logs/DriverInstallation/。进程退出后重新检测,退出码为零但安装文件不完整仍显示失败,3010 提示重启,取消管理员授权不记为安装成功。操作期间阻止窗口内重复下载/安装;关闭窗口会取消后续自动安装,但不会杀掉已经启动的系统安装器,也不会删除或停止下载管理器中的任务。
该步骤的“下一步”明确表示跳过可选安装,只将本次步骤标为已处理,不启动安装器;远程客户端和暂不接相机的部署可因此继续 initializer。即使显示驱动已安装,也应在主程序内连接相机并验证采集。
完成标记、文件保存和重启是三个结果
ConfigurationComplete_Click 按以下顺序处理:
- 寻找任何未完成的必需步骤;找到则跳回该步并 Refresh,结束本次完成操作。
- 检查当前步
CanContinue,调用当前步ApplyAsync;失败则不继续。 - 如尚未运行,执行向导 initializer;initializer 可请求跳过整个向导。
- 计算所有步骤的
ConfigurationStatus,包括非必需步骤;先写入WizardCompletionKey,再直接调用ConfigHandler.GetInstance().SaveConfigs()。 - 若结果为 false,询问是否跳过未完成项;选“不”时先前的 false 和配置已经走过保存,选“是”则置 true 并再次保存。
- 调用
CompleteWizard(),关闭向导或发起应用重启。
必需步骤检查发生在本次 Apply 之前,不是保存前的末端统一再验收。普通未完成项可经确认跳过,initializer 也能直接置完成标记;因此 WizardCompletionKey=true 表示向导流程的放行状态,不表示所有软件已安装、数据库/设备连接健康或所有步骤都完成。
向导先改内存标记,再保存文件;保存异常没有向导级回滚或补偿。点击“完成”本身不保证设置已经保存到磁盘,必须确认 SaveConfigs 正常返回;底层写入契约见配置持久化,不能从一个按钮点击推导整个系统事务成功。这里直接使用 ConfigHandler,与选项菜单经 ConfigService 保存的入口不同。
CompleteWizard 在自身为 Application.Current.MainWindow 时,先用 Process.Start 发起新应用进程,再 Application.Current.Shutdown();否则只 Close()。没有等待新进程健康的交接协议。App 退出时清理恢复记录的有关分支依据“本次显示过向导且当前标记为 true”,也不是重启已经验证成功。
关闭不等于取消或恢复原状
当前 XAML 没有专用“取消”按钮;如果问题中的“取消”指关窗,应按关闭路径判断。窗口没有取消 token 或回滚处理,调用 RefreshAsync / ApplyAsync 时也未传入可取消 token。关窗不能证明在途操作已停止,已安装软件或改过的配置更不会因此撤销。
WindowConfig 挂接的 Closing 只更新内存中的窗口位置和尺寸,不是取消配置;进程退出还可能通过 ConfigHandler 的退出保存路径写入配置。关闭本身不置 WizardCompletionKey=true:若完成标记仍为 false,下次正常启动仍会显示向导,异常退出还可能先进入恢复分流;恢复选择也能在标记为 true 时要求重新配置。
源码与验证边界
| 责任 | 源码 |
|---|---|
| 发现、Refresh/Apply、initializer、完成和关闭 | UI/ColorVision.UI.Desktop/Wizards/WizardWindow.xaml.cs |
| 按钮、选择列表和状态显示 | UI/ColorVision.UI.Desktop/Wizards/WizardWindow.xaml |
| 步骤默认实现与跳过上下文 | UI/ColorVision.Common/Interfaces/IWizardStep.cs |
| 完成标记与窗口几何 | UI/ColorVision.UI.Desktop/Wizards/WizardWindowConfig.cs、UI/ColorVision.Common/Interfaces/Window/WindowConfig.cs |
| 启动分流与退出恢复处理 | ColorVision/App.xaml.cs |
| 有副作用的步骤示例 | ColorVision/Wizards/RecommendedSoftwareWizardStep.cs |
下载管理器的网络过程、原厂子安装器交互和设备兼容性应在获授权的测试机核对。
用实际宿主核对发现失败、保存失败和重启交接。安装、配置写入或服务操作需要相应授权。
