Customize your Validation OS image using GenImage (Advanced)

Article
05/30/2024

GenImage provides a flexible and highly customizable command line interface to produce Validation OS images exactly to your scenarios. Validation OS Image Builder uses GenImage, but it creates an abstraction layer for a convenient -- but somewhat limited -- UI-based workflow. GenImage is capable of much more than what is exposed on the Validation OS Image Builder UI, and this section details the nuances of generation a fully customizable Validation OS image.

Note

Fully custom images mean that the Validation OS image created using an arbitrary list of customization packages may result in a non-functional operating system.
GenImage will not generate a Visual Studio solution template.

Overall process

The overall process to create a Validation OS image is the following:

Mount the Validation OS ISO file to a specific location on the technician PC filesystem;
Start an elevated command prompt and navigate to the <ISO_ROOT>:\cabs folder;
[Optional] add the drivers to the Validation OS image;
[Optional] create a custom feature configuration file;
[Optional] add the desired on-demand features or packages to the Validation OS image;
[Optional] set/override registry keys in the Validation OS image;
[Optional] include custom binaries/applications in the Validation OS image;
[Optional] set the time zone of the Validation OS image;

Predefined feature packages

The Validation OS ISO contains pre-defined feature package definitions in the <ISO_ROOT>:\GenImage\configs folder. These .pkg files can be opened in a text editor to examine their content. The top section of these files contains more information about the specific feature.

Creating a custom feature package

If the pre-defined feature package definitions provided on the Validation OS ISO are not appropriate for a given scenario, a custom feature package can be easily defined following the same user-friendly format the predefined .pkg files have:

Anything after a # is considered a comment.
One line per package (.cab) name without the file extension. These cabs reside under <ISO_ROOT>:\cabs\neutral and with matching language packages under <ISO_ROOT>:\cabs\en-us (if appropriate).
A reference to another feature definition to be included using the +include <package_name>.<ext> format.

Included packages can reside either in the same directory as the custom package definition file, or they can be one of the .pkg file provided as part of the Validation OS ISO under <ISO_ROOT>:\GenImage\configs.

Note

There is no need to specify a file path for included packages.

The wow64 version of the package should not have to be added to the configuration file. GenImage will automatically include the wow version of the package if it exists.

Note

If a package (.cab) is listed multiple times either via duplicate entry in the file or via an included feature definition, GenImage will only apply this package once.

Important

Some features have inter-package (cab-to-cab) dependencies, meaning that the generated Validation OS image won't work unless all required packages are included. These dependencies are not enforceable by GenImage, so it is possible to generate a non-functional or partially functional Validation OS image when using custom feature definitions.

Specifying the base image (`-ImagePath` and `-ImageFile`)

The -ImageFile: command line parameter can be used to provide the name of the base Validation OS image.

When working with the provided Validation OS ISO file, this parameter can be skipped as GenImage will default to ValidationOS.wim.

The -ImagePath: command line parameter can be used to provide the path to the base Validation OS image.

When working with the provided Validation OS ISO file, this parameter can be skipped as GenImage will default to the mount root of the ISO.

Including features (`-PackagesList:`)

The -PackagesList: command line argument allows the use of one or more predefined or custom features by providing the path to the configuration file.

When specifying multiple .pkg files, either use this parameter multiple times:

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

or use the following syntax:

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

When using the latter format, please make sure the comma separated list is enclosed with double quotes.

-PackageList and `-PkgLst: are aliases for -PackagesList:

GenImage will be looking for the on-demand package under <ISO_ROOT>:\cabs\neutral and <ISO_ROOT>:\cabs\en-us, unless overridden by the -PackagePath: command line parameter.

Including on-demand packages without using feature definitions (`-Packages:`)

The -Packages: command line parameter can be used to provide a comma separated list of on-demand package names to be included in the customized Validation OS image. The list must be enclosed with double quotes.

Adding the wow64 variants of the packages will still be taken care of by GenImage, there is no need to specify them using the -Packages: parameter.

Because of the length of the package names, it is easy to build a very long command line using the -Packages: parameter, so it is encouraged to create a custom feature definition for adding multiple packages. For details on custom feature definitions see Creating a custom feature package.

Overriding the default package location (`-PackagePath`)

The -PackagePath: command line parameter can be used to provide the path to the on-demand Validation OS packages. Under the provided path a neutral and an en-us directories must exist containing the respective on-demand package files (including wow versions if appropriate).

When running GenImage from the Validation OS ISO, this parameter can be skipped, as GenImage will default to <ISO_ROOT>:\cabs.

Add .inf drivers to your Validation OS image (`-Drivers:` / `-DriversOnly`)

The -Drivers: command line parameter can be used to provide the path to a device specific repository of drivers. GenImage will recursively add all drivers under the specified path.

If the drivers are structured under <WinVOS_Root>\Drivers\<my_device>, the -HW:<my_device> command line parameter can be used as shortcut can be used to include those drivers. See "Specifying the path of the customized Validation OS image" for more details about WinVOS_Root.

When drivers are included in the customized Validation OS image, GenImage will automatically add the <ISO_ROOT>\GenImage\configs\usb.pkg feature package to ensure drivers have the most basic class drivers to work. However, using the -SkipDeviceFeatures command line switch will override this behavior.

Using the -DriversOnly command line switch allows the addition of drivers without including any features or individual packages.

Selecting Validation OS image boot target (`-x`)

The customized Validation OS WIM image can be generated to target two different usage scenarios: apply the image directly to internal hard drive of a target device (boot from C:) or use the generated .wim file to replace boot.wim on a WinPE USB drive (boot from X:).

To accommodate both scenarios, the base ValidationOS.wim shipping in the root of the ISO contains two partitions: partition 1 is used to be compatible with recovering to C:, and partition 2 to support the USB (boot from X:) scenarios.

By default, GenImage will produce ValidationOS.wim to be recovered on the internal hard drive of a target computer (boot from C:).

The -x command line parameter can be used to generate an image supporting the USB drive to boot from X: scenario.

Note: -usb is an alias to the -x parameter.

Including custom files in the image (`-AddedSW` and `-AddedSWTargetDir`)

All files under the path specified for the -AddedSW: command line parameter will be copied into the customized Validation OS image. By default, the contents of this path will be copied under <WIM_ROOT>:\Programs\<folder>, where folder is the name of the folder to be included. For example -AddedSW:D:\Test\MyFiles will be copied into <WIM_ROOT>:\Programs\MyFiles.

-AddedSW can be specified multiple times pointing to different locations.

The -AddedSWTargetDir: command line parameter can be used to override the target location withing the customized Validation OS image.

The -NoPackages command line switch can be used to post process an already customized Validation OS image and add files as a separate step.

Changing the registry (`-RegistryImport:`)

The -RegistryImport: command line parameter can be used to apply a standard Windows Registry Editor Version 5.00 .reg file to the customized Validation OS image.

The -NoPackages command line switch can be used to post process an already customized Validation OS image and customize the registry as a separate step.

Changing the time zone (`-TimeZone:`)

The -TimeZone: command line parameter can be used to modify the time zone of the customized Validation OS image. The provided string must be a valid Windows time zone, otherwise GenImage will fail.

Specifying the path of the customized Validation OS image (`-OutPath:` / `-WinVOS_Root:`)

When running GenImage from the mounted Validation OS ISO it will default produce its output (and all intermediate content) into the C:\WinVOS\out\<date>-<time> directory (e.g. C:\WinVOS\out\240116-1242). This behavior can be changed but using either the -OutPath: or the -WinVOS_Root: command line parameters. The difference between these two are as follows:

-OutPath: will specify the exact output location, so the customized Validation OS WIM and all intermediate content will be created under this directory.

Important

Using the same -OutPath: for a subsequent execution of GenImage can result in unexpected side effects.

-WinVOS_Root: will create an out\<date>-<time> subfolder under the specified directory.

Tip

Using -WinVOS_Root: is preferred instead of using -OutPath: to avoid issues with clash of temporary files or .wim files left mounted.

By default, GenImage will use -OutPath: to mount the WIM for processing. The -MountDir: command line parameter can be used to override the location of this intermediate mount point.

Cleaning up potentially stuck mounted WIMs (`-CleanUp`)

If GenImage is interrupted or a mounted WIM is stuck, the -CleanUp command line parameter can be used to attempt an automatic cleanup.

This parameter can only be used on its own.

Skip confirmation of image processing (`-NoWait`)

The -NoWait command line parameter can be used to skip the confirmation after displaying the image generation option and proceeding with the image processing.

Verbose output

The -v command line parameter can be used to change the logging level of GenImage to verbose.

Using this switch will generate a lot of output, and it is recommended to redirect standard out into a file.

Show script usage

The -h command line parameter can be used to display script usage information.

-? and -help are aliases for -h

GenImage examples

Assuming the Validation OS ISO is mounted to J:, here are some examples for generating customized Validation OS WIMs

Add multimedia feature with no drivers using ISO defaults

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

Add multimedia and Wi-Fi features with drivers using ISO defaults, skipping confirmation

Assuming drivers are placed under D:\Drivers\MyDevice

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

... or ...

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

Add provisioning feature with no drivers using previously customized WIM

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

Add debug feature with drivers and include Python

Assuming Python is extracted under D:\Staging\Python and drivers are placed under D:\Drivers\MyDevice

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

Full usage of GenImage.cmd

GenImage.cmd is highly customizable to support several custom scenarios. Here is the full list of parameters it takes, along with a few examples of usage:

            [-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"

Note about using matching version of dism toolset for image creation

When running GenImage.cmd from the mounted ISO the script will prefer using the dism.exe that is shipped on the ISO along with GenImage.cmd. This is the recommended version of dism for any image manipulation task because it matches the tool version used to create the shipped ValidationOS.wim and the optional packages.

(Experimental) Add WWAN Support

Caution

This is an experimental feature with very limited support.

Validation OS has introduced early support for WWAN, to provide interaction with the modem through AT commands.

Two packages need to be added to the image composition: Microsoft-WinVOS-WWAN-Package and Microsoft-WinVOS-PnP-Settings.

This scenario is not supported by GenImage, meaning the packages must be applied using dism.exe provided on the Validation OS ISO. Please make sure to use dism.exe from <ISO_ROOT>:\GenImage\Tools\DISM\%PROCESSOR_ARCHITECTURE% where PROCESSOR_ARCHITECTURE is the processor architecture of the technician's computer (e.g. AMD64).

Share via

Customize your Validation OS image using GenImage (Advanced)

Overall process

Predefined feature packages

Creating a custom feature package

Specifying the base image (`-ImagePath` and `-ImageFile`)

Including features (`-PackagesList:`)

Including on-demand packages without using feature definitions (`-Packages:`)

Overriding the default package location (`-PackagePath`)

Add .inf drivers to your Validation OS image (`-Drivers:` / `-DriversOnly`)

Selecting Validation OS image boot target (`-x`)

Including custom files in the image (`-AddedSW` and `-AddedSWTargetDir`)

Changing the registry (`-RegistryImport:`)

Changing the time zone (`-TimeZone:`)

Specifying the path of the customized Validation OS image (`-OutPath:` / `-WinVOS_Root:`)

Cleaning up potentially stuck mounted WIMs (`-CleanUp`)

Skip confirmation of image processing (`-NoWait`)

Verbose output

Show script usage

GenImage examples

Add multimedia feature with no drivers using ISO defaults

Add multimedia and Wi-Fi features with drivers using ISO defaults, skipping confirmation

Add provisioning feature with no drivers using previously customized WIM

Add debug feature with drivers and include Python

Full usage of GenImage.cmd

Note about using matching version of dism toolset for image creation

(Experimental) Add WWAN Support

Additional resources

Share via

Customize your Validation OS image using GenImage (Advanced)

Overall process

Predefined feature packages

Creating a custom feature package

Specifying the base image (-ImagePath and -ImageFile)

Including features (-PackagesList:)

Including on-demand packages without using feature definitions (-Packages:)

Overriding the default package location (-PackagePath)

Add .inf drivers to your Validation OS image (-Drivers: / -DriversOnly)

Selecting Validation OS image boot target (-x)

Including custom files in the image (-AddedSW and -AddedSWTargetDir)

Changing the registry (-RegistryImport:)

Changing the time zone (-TimeZone:)

Specifying the path of the customized Validation OS image (-OutPath: / -WinVOS_Root:)

Cleaning up potentially stuck mounted WIMs (-CleanUp)

Skip confirmation of image processing (-NoWait)

Verbose output

Show script usage

GenImage examples

Add multimedia feature with no drivers using ISO defaults

Add multimedia and Wi-Fi features with drivers using ISO defaults, skipping confirmation

Add provisioning feature with no drivers using previously customized WIM

Add debug feature with drivers and include Python

Full usage of GenImage.cmd

Note about using matching version of dism toolset for image creation

(Experimental) Add WWAN Support

Additional resources

Specifying the base image (`-ImagePath` and `-ImageFile`)

Including features (`-PackagesList:`)

Including on-demand packages without using feature definitions (`-Packages:`)

Overriding the default package location (`-PackagePath`)

Add .inf drivers to your Validation OS image (`-Drivers:` / `-DriversOnly`)

Selecting Validation OS image boot target (`-x`)

Including custom files in the image (`-AddedSW` and `-AddedSWTargetDir`)

Changing the registry (`-RegistryImport:`)

Changing the time zone (`-TimeZone:`)

Specifying the path of the customized Validation OS image (`-OutPath:` / `-WinVOS_Root:`)

Cleaning up potentially stuck mounted WIMs (`-CleanUp`)

Skip confirmation of image processing (`-NoWait`)