使用 GenImage 自訂您的驗證 OS 映像（進階）

發行項
05/30/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）名稱沒有擴展名。這些計程車位於底下 <ISO_ROOT>:\cabs\neutral ，並在下方 <ISO_ROOT>:\cabs\en-us 具有相符的語言套件（如果適當的話）。
使用 +include <package_name>.<ext> 格式包含之另一個功能定義的參考。

包含的套件可以位於與自定義套件定義檔案相同的目錄中，也可以是作為驗證 OS ISO 中<ISO_ROOT>:\GenImage\configs提供的其中一個.pkg檔案。

注意

不需要指定內含套件的檔案路徑。

套件的 wow64 版本不應該新增至組態檔。如果套件存在，GenImage 會自動包含套件的 wow 版本。

注意

如果封裝（.cab）是透過檔案中的重複專案或透過包含的功能定義列出多次，GenImage 只會套用此套件一次。

重要

某些功能具有套件間相依性（cab-to-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\en-us底下<ISO_ROOT>:\cabs\neutral尋找隨選套件，除非由 -PackagePath：命令行參數覆寫。

包含隨選套件而不使用功能定義（`-Packages:`）

-Packages:命令行參數可用來提供自訂驗證OS映像中包含的隨選套件名稱逗號分隔清單。清單必須以雙引弧括住。

新增套件的 wow64 變體仍會由 GenImage 負責，因此不需要使用 -Packages: 參數來指定它們。

由於套件名稱的長度，使用參數很容易建置很長的命令行 -Packages: ，因此建議您建立自定義功能定義來新增多個套件。如需自定義功能定義的詳細資訊，請參閱建立自定義功能套件。

覆寫預設套件位置（`-PackagePath`）

-PackagePath:命令行參數可用來提供隨選驗證 OS 套件的路徑。在提供的路徑下，中性目錄和 en-us 目錄必須存在，其中包含個別的隨選套件檔案（包括適當情況下的哇版本）。

從驗證 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命令行參數可用來產生支援USB磁碟驅動器從 X：案例開機的映像。

注意： -usb 是參數的 -x 別名。

在映像包含自訂檔案（`-AddedSW` 與 `-AddedSWTargetDir`）

命令行參數所指定 -AddedSW: 路徑下的所有檔案都會複製到自定義的驗證OS映射中。根據預設，此路徑的內容將會複製到下 <WIM_ROOT>:\Programs\<folder>，其中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% 何處 PROCESSOR_ARCHITECTURE 使用dism.exe是技術人員計算機的處理器架構（例如 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`）

詳細資訊輸出

顯示文稿使用方式

GenImage 範例

使用 ISO 預設值新增沒有驅動程式的多媒體功能

使用 ISO 預設值新增多媒體和 Wi-Fi 功能與驅動程式，略過確認

使用先前自定義的 WIM 新增不含驅動程式的布建功能

使用驅動程式新增偵錯功能，並包含 Python

完整使用GenImage.cmd

關於使用比對版本的 dism 工具組來建立映像的注意事項

（實驗性）新增 WWAN 支援

其他資源

共用方式為

使用 GenImage 自訂您的驗證 OS 映像 （進階）

整體程序

預先定義的功能套件

建立自定義功能套件

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

包括功能 （-PackagesList:）

包含隨選套件而不使用功能定義 （-Packages:）

覆寫預設套件位置 （-PackagePath）

將 .inf 驅動程式新增至您的驗證 OS 映射 （-Drivers: / -DriversOnly）

選取 [驗證 OS 映射開機目標] （-x）

在映像包含自訂檔案 （-AddedSW 與 -AddedSWTargetDir）

變更登入 （-RegistryImport:）

變更時區 （-TimeZone:）

指定自訂驗證 OS 映像的路徑 （-OutPath: / -WinVOS_Root:）

清理可能卡住的 WIM （-CleanUp）

略過影像處理確認 （-NoWait）

詳細資訊輸出

顯示文稿使用方式

GenImage 範例

使用 ISO 預設值新增沒有驅動程式的多媒體功能

使用 ISO 預設值新增多媒體和 Wi-Fi 功能與驅動程式，略過確認

使用先前自定義的 WIM 新增不含驅動程式的布建功能

使用驅動程式新增偵錯功能，並包含 Python

完整使用GenImage.cmd

關於使用比對版本的 dism 工具組來建立映像的注意事項

（實驗性）新增 WWAN 支援

其他資源

使用 GenImage 自訂您的驗證 OS 映像（進階）

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

包括功能（`-PackagesList:`）

包含隨選套件而不使用功能定義（`-Packages:`）

覆寫預設套件位置（`-PackagePath`）

將 .inf 驅動程式新增至您的驗證 OS 映射（`-Drivers:` / `-DriversOnly`）

選取 [驗證 OS 映射開機目標] （`-x`）

在映像包含自訂檔案（`-AddedSW` 與 `-AddedSWTargetDir`）

變更登入（`-RegistryImport:`）

變更時區（`-TimeZone:`）

指定自訂驗證 OS 映像的路徑（`-OutPath:` / `-WinVOS_Root:`）

清理可能卡住的 WIM （`-CleanUp`）

略過影像處理確認（`-NoWait`）