GenImage を使用して検証 OS イメージをカスタマイズする (詳細)

[アーティクル]
06/05/2024

GenImage は、シナリオにぴったり合った検証 OS イメージを生成するための、柔軟で高度にカスタマイズ可能なコマンドラインインターフェイスを提供します。検証 OS Image Builder は GenImage を使用しますが、便利ではあるもののやや制限のある UI ベースのワークフローのための抽象化レイヤーを作成します。 GenImage は、Validation OS Image Builder UI で公開されている機能よりもはるかに多くの機能を備えており、このセクションでは、完全にカスタマイズ可能な Validation OS イメージの生成の詳細について説明します。

Note

完全にカスタマイズされたイメージとは、任意のカスタマイズパッケージのリストを使用して作成された検証 OS イメージによって、機能しないオペレーティングシステムが生成される可能性があることを意味します。
GenImage は Visual Studio ソリューションテンプレートを生成しません。

全体的なプロセス

検証 OS イメージを作成する全体的なプロセスは次のとおりです。

検証 OS ISO ファイルをテクニシャン PC ファイルシステム上の特定の場所にマウントします。
管理者特権のコマンドプロンプトを起動し、 <ISO_ROOT>:\cabs フォルダーに移動します。
[オプション] ドライバーを検証 OS イメージに追加します。
[オプション] カスタム機能構成ファイルを作成します。
[オプション] 必要なオンデマンド機能またはパッケージを検証 OS イメージに追加します。
[オプション] 検証 OS イメージ内のレジストリキーを設定/上書きします。
[オプション] 検証OSイメージにカスタムバイナリ/アプリケーションを含めます。
>[オプション] 検証 OS イメージのタイムゾーンを設定します。

定義済み機能パッケージ

検証 OS ISO には、 <ISO_ROOT>:\GenImage\configs フォルダーに事前定義された機能パッケージ定義が含まれています。これらの .pkg ファイルをテキストエディタで開いて、その内容を調べることができます。これらのファイルの上部セクションには、特定の機能に関する詳細情報が含まれています。

カスタム機能パッケージの作成

検証 OS ISO で提供されている定義済みの機能パッケージ定義が特定のシナリオに適していない場合は、定義済みの .pkg ファイルと同じユーザーフレンドリーな形式に従って、カスタム機能パッケージを簡単に定義できます。

# 以降はすべてコメントとみなされます。
ファイル拡張子なしのパッケージ (.cab) 名ごとに 1 行。これらの cab は <ISO_ROOT>:\cabs\neutral の下に存在し、一致する言語パッケージは <ISO_ROOT>:\cabs\en-us (該当する場合) の下にあります。
+include <package_name>.<ext> 形式を使用して含める別の機能定義への参照。

含まれるパッケージは、カスタムパッケージ定義ファイルと同じディレクトリに存在することも、 <ISO_ROOT>:\GenImage\configs で検証 OS ISO の一部として提供される .pkg ファイルの 1 つであることもできます。

Note

含まれるパッケージのファイルパスを指定する必要はありません。

wow64 バージョンのパッケージを構成ファイルに追加する必要はありません。 GenImage は、パッケージの wow バージョンが存在する場合はそれを自動的に含めます。

Note

ファイル内の重複エントリまたは含まれる機能定義によってパッケージ (.cab) が複数回リストされている場合、GenImage はこのパッケージを 1 回だけ適用します。

重要

一部の機能にはパッケージ間 (cab 間) の依存関係があります。つまり、必要なパッケージがすべて含まれていないと、生成された検証 OS イメージは機能しません。これらの依存関係は GenImage では強制できないため、カスタム機能定義を使用すると、機能しない、または部分的に機能する検証 OS イメージが生成される可能性があります。

ベースイメージの指定（`-ImagePath` と `-ImageFile`）

-ImageFile: コマンドラインパラメータを使用して、ベース検証 OS イメージの名前を指定できます。

提供された検証 OS ISO ファイルを使用する場合は、GenImage がデフォルトで ValidationOS.wim になるため、このパラメータをスキップできます。

-ImagePath: コマンドラインパラメータを使用して、基本検証 OS イメージへのパスを指定できます。

提供された検証 OS ISO ファイルを操作する場合、GenImage はデフォルトで ISO のマウントルートを使用するため、このパラメータはスキップできます。

機能を含む（`-PackagesList:`）

-PackagesList: コマンドライン引数を使用すると、構成ファイルへのパスを指定して、1 つ以上の定義済み機能またはカスタム機能を使用できます。

複数の .pkg ファイルを指定する場合は、このパラメータを複数回使用します。

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

または、次の構文を使用します。

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

後者の形式を使用する場合は、コンマ区切りのリストがダブルクォートで囲まれていることを確認してください。

-PackageList と `-PkgLst: は -PackagesList: のエイリアスです。

-PackagePath: コマンドラインパラメーターでオーバーライドされない限り、GenImage は <ISO_ROOT>:\cabs\neutral と <ISO_ROOT>:\cabs\en-us でオンデマンドパッケージを検索します。

機能定義を使用せずにオンデマンドパッケージを含める（`-Packages:`）

-Packages: コマンドラインパラメータを使用すると、カスタマイズされた検証 OS イメージに含めるオンデマンドパッケージ名のカンマ区切りのリストを提供できます。リストはダブルクォートで囲む必要があります。

パッケージの wow64 バリアントの追加は引き続き GenImage によって処理され、 -Packages: パラメータを使用してそれらを指定する必要はありません。

パッケージ名が長いため、 -Packages: パラメータを使用して非常に長いコマンドラインを簡単に作成できるため、複数のパッケージを追加するためのカスタム機能定義を作成することをお勧めします。カスタム機能定義の詳細については、「カスタム機能パッケージの作成」を参照してください。

デフォルトのパッケージの場所を上書きする (`-PackagePath`)

-PackagePath: コマンドラインパラメーターを使用して、オンデマンド検証 OS パッケージへのパスを指定できます。指定されたパスの下に、それぞれのオンデマンドパッケージファイル (該当する場合は wow バージョンを含む) を含む、neutral ディレクトリと 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 イメージは、2 つの異なる使用シナリオを対象として生成できます。イメージをターゲットデバイスの内部ハードドライブ (C: からブート) に直接適用するか、生成された .wim ファイルを使用して WinPE USB 上の boot.wim を置き換えます。ドライブ (X: から起動)。

両方のシナリオに対応するために、ISO のルートに含まれる基本の ValidationOS.wim には 2 つのパーティションが含まれています。パーティション 1 は C: へのリカバリと互換性を保つために使用され、パーティション 2 は USB (X: からのブート) シナリオをサポートするために使用されます。

デフォルトでは、GenImage はターゲットコンピューター (C: からブート) の内蔵ハードドライブに復元される ValidationOS.wim を生成します。

-x コマンドラインパラメータを使用すると、X: シナリオから起動する USB ドライブをサポートするイメージを生成できます。

注: -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:`)

マウントされた Validation OS ISO から GenImage を実行すると、デフォルトでその出力 (およびすべての中間コンテンツ) が C:\WinVOS\out\<date>-<time> ディレクトリ (例: C:\WinVOS\out\240116-1242) に生成されます。この動作は、 -OutPath: または -WinVOS_Root: コマンドラインパラメータを使用して変更できます。これら 2 つの違いは次のとおりです。

-OutPath: は正確な出力場所を指定するため、カスタマイズされた検証 OS WIM とすべての中間コンテンツがこのディレクトリの下に作成されます。

重要

以降の GenImage の実行に同じ -OutPath: を使用すると、予期しない副作用が発生する可能性があります。

-WinVOS_Root: は指定されたディレクトリの下に out\<date>-<time> サブフォルダを作成します。

ヒント

一時ファイルの衝突やマウントされたままの .wim ファイルの問題を回避するには、 -OutPath: を使用する代わりに -WinVOS_Root: を使用することをお勧めします。

デフォルトでは、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 を実行する場合、スクリプトは GenImage.cmd とともに ISO に同梱されている dism.exe の使用を優先します。これは、付属の ValidationOS.wim およびオプションのパッケージの作成に使用されるツールのバージョンと一致するため、あらゆるイメージ操作タスクに推奨される dism のバージョンです。

(実験的) WWAN サポートを追加

注意事項

これは実験的な機能であり、サポートが非常に限定されています。

検証 OS は、AT コマンドを介してモデムとの対話を提供するために、WWAN の早期サポートを導入しました。

2 つのパッケージ、 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`)

詳細出力

スクリプトの使用法を表示する

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 サポートを追加

その他のリソース

ベースイメージの指定（`-ImagePath` と `-ImageFile`）

機能を含む（`-PackagesList:`）

機能定義を使用せずにオンデマンドパッケージを含める（`-Packages:`）

デフォルトのパッケージの場所を上書きする (`-PackagePath`)

.inf ドライバーを検証 OS イメージに追加します (`-Drivers:` / `-DriversOnly`)

検証OSイメージのブートターゲットを選択しています（`-x`）

画像にカスタムファイルを含める (`-AddedSW` および `-AddedSWTargetDir`)

レジストリの変更 (`-RegistryImport:`)

タイムゾーンを変更する(`-TimeZone:`)

カスタマイズされた検証 OS イメージのパスを指定する (`-OutPath:` / `-WinVOS_Root:`)

マウントされた WIM がスタックしている可能性のあるクリーンアップ(`-CleanUp`)

画像処理の確認をスキップ(`-NoWait`)