jpackage Windows MSI 安装程序 UI 序列InstallUISequence解析从测试快照看 EULA 对话框定制与验证机制【免费下载链接】jdkJDK main-line development https://openjdk.org/projects/jdk项目地址: https://gitcode.com/GitHub_Trending/jd/jdk导读本文围绕 JDK 仓库中 jpackage 测试套件的一份期望快照文件 InstallUISequence.md 展开剖析 jpackage 在使用--license-file打包 Windows MSI 安装程序时对 MSI 数据库标准表InstallUISequence所做的定制用带 EULA 的WelcomeEulaDlg替换标准欢迎对话框并按安装场景全新安装 / 补丁升级挂接不同的执行条件。读完本文你将掌握InstallUISequence表的 Action/Condition 语义、不同 jpackage Windows 参数组合下 UI 序列的差异以及该测试如何借助MsiDatabase从真实 MSI 包中读取数据库表并与快照逐行断言。一、关联文档定位测试套件的期望 MSI 表快照该文档位于 jpackage 测试资源目录test/jdk/tools/jpackage/resources/WinInstallerUiTest/license/InstallUISequence.md它不是一份面向用户的用户手册而是WinInstallerUiTest测试用例的期望数据文件expected data。测试运行时会构建真实的 Windows MSI 安装包通过cscript脚本导出 MSI 数据库中的表再把 jpackage 对InstallUISequence表的实际修改与这份 Markdown 快照逐行比对不一致即断言失败。整个WinInstallerUiTest资源目录按 jpackage 参数组合划分了 8 个子目录dir_chooser、license、shortcut_prompt、ui及它们的组合每个子目录下均有两份快照InstallUISequence.md——InstallUISequence表的期望内容Action / Condition 两列ControlEvents.md——ControlEvent表的期望内容Dialog / Control / Event / Argument / Condition / Ordering 六列。其中 license/InstallUISequence.md 全文如下ActionConditionWelcomeDlgInstalled AND PATCHWelcomeEulaDlgNOT Installed而同目录下的 license/ControlEvents.md 只有表头、没有数据行说明该场景下 jpackage 未对ControlEvent表注入额外的事件绑定。二、InstallUISequence 表Windows Installer 的安装 UI 执行序列InstallUISequence是 MSI 数据库Windows Installer 数据库中的标准表之一定义了安装程序**用户界面阶段UI sequence**中各对话框与动作Action的执行顺序与执行条件。该表的典型列即为Action要执行的对话框或标准动作如WelcomeDlg、LicenseAgreementDlg、InstallDirDlg等均为 MSI 内置对话框Condition一个 MSI 条件表达式逻辑表达式只有条件为真非零时对应 Action 才会执行若条件为0或空则该 Action 被跳过。MSI 条件表达式基于安装属性Property求值。本文快照中出现的三个条件含义如下条件表达式语义NOT Installed属性Installed未被设置即全新安装fresh install场景Installed AND PATCH属性Installed与PATCH同时为真即已安装产品上打补丁patch/upgrade场景0恒为假对应 Action永不执行见下文ui场景快照理解了这张表的语义再回头读快照就一目了然jpackage 在传入--license-file时把标准WelcomeDlg的执行条件收窄为补丁场景并在全新安装场景下注入自定义的WelcomeEulaDlg来承担欢迎 许可协议展示职责。三、快照逐行解读license 场景下 jpackage 如何改造欢迎对话框回到核心文档 license/InstallUISequence.md 的两行数据| WelcomeDlg | Installed AND PATCH | | WelcomeEulaDlg | NOT Installed |逐行拆解WelcomeDlg | Installed AND PATCH标准欢迎对话框只在产品已安装且正在进行补丁安装时出现。也就是说补丁流程仍然走 MSI 默认的欢迎界面不展示额外许可协议因为许可在首次安装时已被接受过。WelcomeEulaDlg | NOT Installed全新安装时jpackage 注入的自定义对话框WelcomeEulaDlg取而代之。从测试上下文--license-file参数可以推断该对话框在欢迎步骤中内嵌了最终用户许可协议EULA的展示与接受入口从而满足安装前必须先同意许可的打包诉求。这两行数据合在一起构成了一个场景分流按Installed/PATCH属性把安装流程分为全新安装与补丁安装两条路径分别挂接不同的欢迎对话框。值得注意的是测试工具链在收集该表时做了针对性过滤从 MsiDatabase.java 的实现可以看到uiAlterations()方法通过var includeActions Set.of(WelcomeEulaDlg, WelcomeDlg);只保留WelcomeEulaDlg与WelcomeDlg两个动作再按sequence排序输出。这说明jpackage 对InstallUISequence表的核心定制点正是这两个欢迎类对话框其他 MSI 内置对话框如InstallDirDlg等不在 jpackage 的定制范畴内因此不进入快照。四、横向对比不同参数组合下的 UI 序列差异将WinInstallerUiTest资源目录下的各份InstallUISequence.md快照放在一起对比可以看到 jpackage 各参数对 UI 序列的影响测试组合目录InstallUISequence.md 内容对应 jpackage 参数license/WelcomeDlgInstalled AND PATCHWelcomeEulaDlgNOT Installed--license-fileui/WelcomeDlgInstalled AND PATCHWelcomeEulaDlg0--win-with-uidir_chooser/WelcomeDlgNOT Installed OR PATCH--win-dir-choosershortcut_prompt/WelcomeDlgNOT Installed OR PATCH--win-shortcut-promptdir_chooserlicense/WelcomeDlgNOT Installed OR PATCH目录选择 许可dir_choosershortcut_prompt/WelcomeDlgNOT Installed OR PATCH目录选择 快捷方式提示licenseshortcut_prompt/WelcomeDlgNOT Installed OR PATCH许可 快捷方式提示几个关键结论只有--license-file且不带--win-dir-chooser/--win-shortcut-prompt时才会注入WelcomeEulaDlg并采用场景分流的两行配置--win-with-ui纯 UI 模式下同样注入了WelcomeEulaDlg但条件为0即该对话框在序列中被显式禁用——UI 模式带来的定制集中在ControlEvent层面的对话框切换而非欢迎对话框的执行dir_chooser与shortcut_prompt系组合不会动欢迎对话框条件保持NOT Installed OR PATCH即标准 MSI 默认行为它们的定制点分别落在InstallDirNotEmptyDlg自定义目录对话框与ShortcutPromptDlg快捷方式提示对话框上——这两者正是 MsiDatabase.java 中注释所标注的 Custom jpackage dialogs。需要补充的是快照目录与参数组合并非一一对应地简单叠加在 WinInstallerUiTest.java 的expectedFilesDir()中可以看到带 UI--win-with-ui的组合会复用不带 UI组合的期望目录即 UI 模式不改变InstallUISequence快照的归属这也与ui/目录单独成册、而dir_chooserui等组合不单列目录的结构相印证。五、源码级验证机制快照如何被生成与断言5.1 断言流程WinInstallerUiTest.java 中TestSpec.run()是断言的核心读取期望快照Files.readAllLines(expectedFilesDir.resolve(InstallUISequence.md))通过WindowsHelper.getUIAlterations(cmd)从构建出的 MSI 包中提取真实的 UI 修改调用actionSequenceToMarkdownTable(...)把真实的InstallUISequence行转换为与快照完全相同的 Markdown 表格格式用TKit.assertStringListEquals(expected, actual, ...)逐行比较失败信息会明确指出期望文件路径便于定位。其中actionSequenceToMarkdownTable生成的表头固定为[Action, Condition]与快照文件格式一一对应同时toMarkdownTable还会把值中的|转义为#124;保证表格格式的稳定性。5.2 数据来源真实 MSI 包 → .idt → 内存表MsiDatabase 的读取链路MsiDatabase.java为通过cscript.exe //Nologo调用资源脚本resources/msi-export.js把 MSI 包中的指定表导出为.idt文本档案文件UI_ALTERATIONS_REQUIRED_TABLES Set.of(CONTROL_EVENT, INSTALL_UI_SEQUENCE)限定只导出与 UI 定制相关的两张表再通过MsiTable.loadFromTextArchiveFile将.idt解析为内存表结构供uiAlterations()过滤、排序、格式化。这意味着快照不是人工臆造的而是从真实构建的 MSI 安装包中回读导出的保证了期望值与 jpackage 实际行为的一致性。5.3 快照的再生成当 jpackage 的 UI 定制逻辑发生变更如新增/调整对话框时开发者可通过updateExpectedMsiTables()WinInstallerUiTest.java重新生成全部组合的期望快照public static void updateExpectedMsiTables() { for (var spec : testCases()) { spec.createTest(true).addBundleVerifier(cmd - { spec.save(WindowsHelper.getUIAlterations(cmd)); }).run(Action.CREATE); } }它会为每个组合构建 MSI 包、回读 UI 修改并写回对应的InstallUISequence.md/ControlEvents.md与save()方法WinInstallerUiTest.java配合完成快照更新。5.4 测试用例的生成规则testCases()WinInstallerUiTest.java枚举dir_chooser、license、shortcut_prompt三个布尔开关的 7 种非空组合排除全部为 false 以避开SimplePackageTest的重复再追加一个纯 UI 组合。test()方法还会对每个组合额外派生一个copyWithUi()变体从而覆盖--win-with-ui与各参数的交叉场景。每个组合对应的包名也会体现参数特征如HelloAppWithDcSpLUi见setPackageName。六、如何运行该测试该测试在仓库的 jpackage Windows 测试体系中运行前提是操作系统为 Windows测试头注释中requires (os.family windows)已构建好可用的 JDK 与 jpackage 工具链按 jpackage 测试套件/test/jdk/tools/jpackage/helpers的标准方式驱动jdk.jpackage.test.Main。测试头中的运行入口形如run main/othervm/timeout720 -Xmx512m jdk.jpackage.test.Main --jpt-runWinInstallerUiTest若在 SQE系统质量评估测试环境中还会排除部分冗余组合--jpt-exclude(dir_chooser) --jpt-exclude(license) --jpt-excludeui普通开发者通常无需手动运行该测试但理解其断言逻辑有助于在定制 jpackage Windows 打包行为尤其是--license-file与--win-with-ui时预判 MSI 中 UI 序列的最终形态。七、关联文件索引核心快照license/InstallUISequence.md、license/ControlEvents.md其余组合快照ui/InstallUISequence.md、dir_chooser/InstallUISequence.md、shortcut_prompt/InstallUISequence.md、dir_chooserlicense/InstallUISequence.md、licenseshortcut_prompt/InstallUISequence.md、dir_choosershortcut_prompt/InstallUISequence.md测试主类WinInstallerUiTest.javaMSI 数据库读取与过滤MsiDatabase.java结语一张仅两行的 Markdown 表格承载的是 jpackage 对 Windows MSI 安装 UI 序列的精准定制契约--license-file让全新安装走自定义WelcomeEulaDlg、补丁安装走标准WelcomeDlg。通过对比同目录下的多份快照、阅读WinInstallerUiTest的断言与再生成逻辑开发者既能理解 MSIInstallUISequence表的工作原理也能掌握一套从真实产物回读数据库表 → 沉淀为 Markdown 期望快照 → 逐行比对回归的扎实测试方法论。【免费下载链接】jdkJDK main-line development https://openjdk.org/projects/jdk项目地址: https://gitcode.com/GitHub_Trending/jd/jdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考