使用 GenImage 自定义验证 OS 映像（高级）

项目
06/06/2024

GenImage 提供了一个灵活且高度可自定义的命令行接口，可以根据方案生成验证 OS 映像。验证 OS 映像生成器使用 GenImage，但它为基于 UI 的工作流提供了方便但有些有限的抽象层。 GenImage 的功能远远超过验证 OS 映像生成器 UI 上显示的功能，本节详细介绍了生成完全可自定义的验证 OS 映像的细微差别。

注意

完全自定义映像意味着使用自定义包的任意列表创建的验证 OS 映像可能导致操作系统无法正常工作。
GenImage 不会生成 Visual Studio 解决方案模板。

整体进程

创建验证 OS 映像的整个过程如下：

将验证 OS ISO 文件装载到技术人员电脑文件系统上的特定位置；
启动提升的命令提示符并导航到 <ISO_ROOT>:\cabs 文件夹；
[可选] 将驱动程序添加到验证 OS 映像；
[可选] 创建自定义功能配置文件；
[可选] 将所需的按需功能或包添加到验证 OS 映像；
[可选] 在验证 OS 映像中设置/替代注册表项；
[可选] 在验证 OS 映像中包含自定义二进制文件/应用程序；
[可选] 设置验证 OS 映像的时区；

预定义的功能包

验证 OS ISO 在 <ISO_ROOT>:\GenImage\configs 文件夹中包含预定义的功能包定义。可以在文本编辑器中打开这些 .pkg 文件以检查其内容。这些文件的顶部部分包含有关特定功能的详细信息。

创建自定义功能包

如果验证 OS ISO 上提供的预定义功能包定义不适用于给定方案，则可以按照预定义 .pkg 文件相同的用户友好格式轻松定义自定义功能包：

# 之后的任何内容都被视为注释
每个包 (.cab) 名称一行，不带文件扩展名。这些 cab 位于 <ISO_ROOT>:\cabs\neutral 下，并在 <ISO_ROOT>:\cabs\en-us 下具有匹配的语言包（如果适用）。
对使用 +include <package_name>.<ext> 格式包含的另一个功能定义的引用。

包含的包可以与自定义包定义文件位于同一目录中，也可以是作为 <ISO_ROOT>:\GenImage\configs 下的验证 OS ISO 的一部分提供的 .pkg 文件之一。

注意

无需为包含的包指定文件路径。

不应将包的 wow64 版本添加到配置文件中。 GenImage 将自动包含包的 wow 版本（如果存在）。

注意

如果包 (.cab) 通过文件中的重复条目或通过包含的功能定义多次列出，GenImage 将仅应用此包一次。

重要

某些功能具有包间（cab 到 cab）依赖关系，这意味着除非包含所有必需的包，否则生成的验证 OS 映像将不起作用。 GenImage 无法强制执行这些依赖关系，因此在使用自定义功能定义时，可以生成非功能性或部分功能的验证 OS 映像。

指定基础映像（`-ImagePath` 和 `-ImageFile`）

-ImageFile: 命令行参数可用于提供基本验证 OS 映像的名称。

使用提供的验证 OS ISO 文件时，可以跳过此参数，因为 GenImage 默认为 ValidationOS.wim。

-ImagePath: 命令行参数可用于提供基本验证 OS 映像的路径。

使用提供的验证 OS ISO 文件时，可以跳过此参数，因为 GenImage 将默认为 ISO 的装载根。

包括功能 (`-PackagesList:`)

-PackagesList：命令行参数允许通过提供配置文件的路径，来使用一个或多个预定义或自定义功能。

指定多个 .pkg 文件时，可以多次使用此参数：

-PackagesList:<file1> -PackagesList:<file2> [...]

或使用以下语法：

-PackagesList:"<file1>,<file2>[,...]"

使用后一种格式时，请确保用双引号括住逗号分隔的列表。

-PackageList 和 `-PkgLst：是 -PackagesList 的别名：

GenImage 将在 <ISO_ROOT>:\cabs\neutral 和 <ISO_ROOT>:\cabs\en-us 下查找按需包，除非被 -PackagePath: 命令行参数替代。

包括按需包而不使用功能定义 (`-Packages:`)

-Packages: 命令行参数可用于提供要包含在自定义验证 OS 映像中的按需包名称的逗号分隔列表。该列表必须用双引号引起来。

添加包的 wow64 变体仍由 GenImage 负责，无需使用 -Packages: 参数指定它们。

由于包名称的长度，使用 -Packages: 参数可以轻松生成很长的命令行，因此建议创建用于添加多个包的自定义功能定义。有关自定义功能定义的详细信息，请参阅“创建自定义功能包”。

替代默认包位置 (`-PackagePath`)

-PackagePath: 命令行参数可用于提供按需验证 OS 包的路径。在提供的路径下，必须存在一个中立目录和一个 en-us 目录，其中包含相应的按需包文件（如果合适，包括 wow 版本）。

从验证 OS ISO 运行 GenImage 时，可以跳过此参数，因为 GenImage 默认为 <ISO_ROOT>:\cabs。

将 .inf 驱动程序添加到验证 OS 映像 (`-Drivers:` / `-DriversOnly`)

-Drivers: 命令行参数可用于提供特定于设备的驱动程序存储库的路径。 GenImage 将以递归方式在指定路径下添加所有驱动程序。

如果驱动程序结构在 <WinVOS_Root>\Drivers\<my_device>, 下，则 -HW:<my_device> 命令行参数可以用作快捷方式，可以用于包括这些驱动程序。有关 WinVOS_Root 的更多详细信息，请参阅“指定自定义验证 OS 映像的路径”。

当驱动程序包含在自定义验证 OS 映像中时，GenImage 将自动添加 <ISO_ROOT>\GenImage\configs\usb.pkg 功能包，以确保驱动程序具有最基本的类驱动程序以正常工作。但是，使用 -SkipDeviceFeatures 命令行开关将替代此行为。

使用 -DriversOnly 命令行开关可以添加驱动程序，而无需包括任何功能包或单个包。

选择验证 OS 映像启动目标 (`-x`)

可以生成自定义验证 OS WIM 映像以面向两种不同的使用方案：将映像直接应用到目标设备的内部硬盘驱动器（从 C: 启动），或使用生成的 .wim 文件替换 WinPE USB 驱动器上的 boot.wim（从 X: 启动）。

为了适应这两种方案，ISO 根目录中的基本 ValidationOS.wim 包含两个分区：分区 1 用于兼容恢复到 C:，分区 2 用于支持 USB（从 X: 启动）方案。

默认情况下，GenImage 将生成要在目标计算机的内部硬盘驱动器上恢复的 ValidationOS.wim（从 C: 启动）。

-x 命令行参数可用于生成支持 U 盘从 X: 方案启动的映像。

注意：-usb 是 -x 参数的别名。

在映像中包含自定义文件（`-AddedSW` 和 `-AddedSWTargetDir`）

为 -AddedSW: 命令行参数指定的路径下的所有文件都将复制到自定义的验证 OS 映像中。默认情况下，此路径的内容将复制到 <WIM_ROOT>:\Programs\<folder> 下，其中文件夹是要包含的文件夹的名称。例如，-AddedSW:D:\Test\MyFiles 将复制到 <WIM_ROOT>:\Programs\MyFiles。

-AddedSW 可以指定多次指向不同的位置。

-AddedSWTargetDir: 命令行参数可用于替代自定义验证 OS 映像中的目标位置。

-NoPackages 命令行开关可以用于后期处理已经自定义的验证 OS 映像，并作为单独的步骤添加文件。

更改注册表 (`-RegistryImport:`)

-RegistryImport: 命令行参数可用于将标准 Windows 注册表编辑器版本 5.00 .reg 文件应用到自定义的验证 OS 映像。

-NoPackages 命令行开关可以用于后期处理已经自定义的验证 OS 映像，并作为单独的步骤自定义注册表。

更改时区 (`-TimeZone:`)

-TimeZone: 命令行参数可用于修改自定义验证 OS 映像的时区。提供的字符串必须是有效的 Windows 时区，否则 GenImage 将失败。

指定自定义验证 OS 映像的路径 (`-OutPath:` / `-WinVOS_Root:`)

从装载的验证 OS ISO 运行 GenImage 时，默认会将其输出（以及所有中间内容）生成到 C:\WinVOS\out\<date>-<time> 目录中（例如，C:\WinVOS\out\240116-1242）。但可以使用 -OutPath: 或 -WinVOS_Root: 命令行参数更改此行为。两者之间的差异如下：

-OutPath: 将指定确切的输出位置，因此将在此目录下创建自定义的验证 OS WIM 和所有中间内容。

重要

对 GenImage 的后续执行使用相同的 -OutPath: 操作可能会导致意外的副作用。

-WinVOS_Root: 将在指定目录下创建 out\<date>-<time> 子文件夹。

提示

最好使用 -WinVOS_Root:，而不是使用 -OutPath:，以避免临时文件或 .wim 文件装载时发生冲突的问题。

默认情况下，GenImage 将使用 -OutPath: 装载 WIM 进行处理。 -MountDir: 命令行参数可用于替代此中间装载点的位置。

清理可能卡住的已装载 WIM (`-CleanUp`)

如果 GenImage 中断或装载的 WIM 被卡住，则 -CleanUp 命令行参数可用于尝试自动清理。

此参数只能单独使用。

跳过图像处理确认 (`-NoWait`)

-NoWait 命令行参数可用于在显示图像生成选项并继续进行图像处理后跳过确认。

详细输出

-v 命令行参数可用于将 GenImage 的日志记录级别更改为详细。

使用此开关将生成大量输出，建议将标准重定向到文件中。

显示脚本使用情况

-h 命令行参数可用于显示脚本使用情况信息。

-? 和 -help 是 -h 的别名

GenImage 示例

假设已将验证 OS ISO 装载到 J:，下面是生成自定义验证 OS WIM 的一些示例

使用 ISO 默认值添加没有驱动程序的多媒体功能

J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\multimedia.pkg

使用 ISO 默认值并跳过确认添加具有驱动程序的多媒体和 Wi-Fi 功能

假设驱动程序位于 D:\Drivers\MyDevice 下

J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\multimedia.pkg -PackagesList:J:\GenImage\configs\wifi.pkg -drivers:D:\Drivers\MyDevice -NoWait

... 或 ...

J:\GenImage>GenImage.cmd -PackagesList:"J:\GenImage\configs\multimedia.pkg,J:\GenImage\configs\wifi.pkg" -drivers:D:\Drivers\MyDevice -NoWait

使用以前自定义的 WIM 添加没有驱动程序的预配功能

J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\provisioning.pkg -ImagePath:C:\WinVOS\out\240116-1530

为驱动程序添加调试功能，并包括 Python

假设 Python 被提取到 D:\Staging\Python 下，并且驱动程序被放置在 D:\Drivers\MyDevice 下

J:\GenImage>GenImage.cmd -PackagesList:J:\GenImage\configs\debug.pkg -ImagePath:J:\ -Drivers:D:\Drivers\MyDevice -AddedSW:D:\Staging\Python

充分利用 GenImage.cmd

GenImage.cmd 可高度自定义，以支持多个自定义方案。以下是它所采用的参数的完整列表，以及一些用法示例：

            [-Packages:|-PackagesList:|-DriversOnly|-NoPackages]
            [-Drivers:|-HW]
            [-WinVOS_Root:] [-MountDir:]
            [-wim|-vhd|-vhdx] [-usb|-x] [-inc]
            [-TimeZone:]
            [-AddedSW: [-AddedSWTargetDir:]]
            [-RegistryImport:] [-StartupCommand:]
            [-NoWait] [-v]
            NOTE: Running From ISO: [YES]
            -?|-h|-help This screen

-ImageFile:                             <file_name> File name of the image file to be processes.
                                        Defaults to ValidationOS.wim
                                        -wim, -vhd and -vhdx are ignored

-ImagePath:<file_path>                  Path to the image file to be processed.
                                        Default/Current: [J:\]

-PackagePath:<path>                     Path to the cab files to be added to the image.
                                        Defaults to J:\cab or J:\Packages

                                        Neutral and localized packages are placed into their respective
                                        folders under "cab": "neutral" and "en-us".

-OutPath:<path>                         Location of the generated image
                                        Default/Current: [C:\WinVOS\out\240116-1640]

-Packages:<list>                        Comma or space separated list of packages.
                                        Use double quotes around the list.

-PackagesList|PackageList|PkgLst:<file> Use a text file to specify which 
                                        packages will be added to the image
                                        One package name per line, use # for comments

-NoPackages                             Do not include any packages

-DriversOnly                            Do not include any packages, add drivers only
                                        Requires specifying either -Drivers or -HW, but not both

-Drivers:<path>                         Path to drivers
                                        If neither -HW nor -Drivers are not specified
                                        no drivers will be added to the image.
                                        If -HW was used defaults to C:\WinVOS\Drivers\%HW%

-HW:<hardware>                          Hardware variant used for driver installation.
                                        If neither -HW nor -Drivers are specified, no
                                        drivers will be added to the image.

                                        The value specified for this parameter will be appended
                                        to [C:\WinVOS\Drivers]

-SkipDeviceFeatures                     Do NOT automatically include USB support when
                                        drivers are added to the image

-WinVOS_Root:<path>                     Root of the directory structure to process
                                        Default/Current: [C:\WinVOS]

-MountDir:<path>                        Path to mount the image to for processing
                                        Default/Current: C:\WinVOS\out\240116-1640\mnt

-wim                                    Assume the image is a wim file
                                        This is default extension unless -ImageFile, -vhd(x) are specified.

-vhd|-vhdx                              Assume the image is a vhdx file
                                        .wim is default extension unless -ImageFile is specified.

-usb|-x                                 Assume USB boot and set the image index to 2 during mount
                                        Default image index is 1

-TimeZone:<time zone>                   Sets the time zone of the image to the specified value.
                                        NOTE: The validity of this setting is not checked.

-AddedSW:<path>                         Files and folders under path will be copied into the
                                        generated image.

                                        Default target location is \Programs, can be overriden with
                                        -AddedSWTargetDir

-AddedSWTargetDir:<path>                Target - in image - path to copy the contents specified by AddedSW.
                                        Default is \Programs

-RegistryImport:<file>                  Path the a .reg file to be imported into the generated image.
                                        This file can multiple hives under HKLM. Supported hives:
                                        COMPONENTS DEFAULT DRIVERS SAM SECURITY SOFTWARE SYSTEM

-StartupCommand:<file>                  Path the an executablefile to be used as the ValidationOS Shell
                                        On boot this file will be executed first. If the file does not spawn
                                        a new CMD window, the shell will be this new executable.

-inc|-incremental                       Do not restore the package from backup

-CleanUp                                Clean up lingering mounted images.
                                        Will attempt to clean up the mounted into /MountDir.
                                        If /MountDir is not specified it will attempt to clean up
                                        any corrupted and/or prevously mounted images.

                                        NOTE: Not using /MountDir with /Cleanup is a drastic cleaup tactic.

-NoWait                                 Don't pause after displaying image generation settings.

-v                                      Verbose logging

Examples:

* Add all packages in the default "cab" folder under the default package path [J:\cabs] to the default image
  file [ValidationOS.wim] under the default path [J:\] without including drivers:

    GenImage

* Add all packages under the "cab" folder to a ValidationOS.wim and include the drivers for "SP6"

    GenImage -ImageFile:ValidationOS.wim -ImagePath:C:\WinVOS\release\25108.1001.220429-1329\amd64fre -HW:SP6

* Add packages specified in custom.pkg under the "cab" folder to a ValidationOS.vhdx without including drivers:

    GenImage -ImagePath:C:\WinVOS\release\25108.1001.220429-1329\amd64fre -vhdx -PackagesList:custom.pkg

* Incrementally add "Microsoft-WinVOS-NetFx45-Package" to ValidationOS.wim. The package is located in "cab" under the specified image path folder.

    GenImage -inc -ImageFile:ValidationOS.wim -ImagePath:C:\WinVOS\release\25108.1001.220429-1329\amd64fre -Packages:"Microsoft-WinVOS-NetFx45-Package"

有关使用匹配版本的 dism 工具集创建映像的说明

从装载的 ISO 运行 GenImage.cmd 时，脚本首选使用 ISO 上随附的 dism.exe 以及 GenImage.cmd。对于任何映像操作任务，这是建议的 dism 版本，因为它与用于创建已交付的 ValidationOS.wim 和可选包的工具版本相匹配。

（试验）添加 WWAN 支持

注意

这是一项试验功能，支持非常有限。

验证 OS 引入了对 WWAN 的早期支持，以便通过 AT 命令与调制解调器进行交互。

图像合成中需要添加两个包：Microsoft-WinVOS-WWAN-Package 和 Microsoft-WinVOS-PnP-Settings。

GenImage 不支持此方案，这意味着必须使用验证 OS ISO 上提供的 dism.exe 应用包。请确保使用 <ISO_ROOT>:\GenImage\Tools\DISM\%PROCESSOR_ARCHITECTURE% 中的 dism.exe，其中 PROCESSOR_ARCHITECTURE 是技术人员计算机的处理器体系结构（例如，AMD64）。

通过

使用 GenImage 自定义验证 OS 映像（高级）

整体进程

预定义的功能包

创建自定义功能包

指定基础映像（-ImagePath 和 -ImageFile）

包括功能 (-PackagesList:)

包括按需包而不使用功能定义 (-Packages:)

替代默认包位置 (-PackagePath)

将 .inf 驱动程序添加到验证 OS 映像 (-Drivers: / -DriversOnly)

选择验证 OS 映像启动目标 (-x)

在映像中包含自定义文件（-AddedSW 和 -AddedSWTargetDir）

更改注册表 (-RegistryImport:)

更改时区 (-TimeZone:)

指定自定义验证 OS 映像的路径 (-OutPath: / -WinVOS_Root:)

清理可能卡住的已装载 WIM (-CleanUp)

跳过图像处理确认 (-NoWait)