Validation OS customization using Validation OS Image Builder

Article
05/30/2024

You can add driver packages and Validation OS customization packages to ensure that Validation OS can boot and support the apps for your scenarios. You can use customization packages to add support for several on-demand functionalities covered later in the document.

Validation OS does not ship with inbox drivers, so you will have to make sure you add drivers before you can apply your image to your PC.

Overall process

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

Mount the Validation OS ISO file to a specific location on the technician PC filesystem;
Start the appropriate ValidationOSImageBuilder.exe based on the native architecture of the technician PC (x64 or arm64);
Follow the steps in Validation OS ImageBuilder
1. [Optional] Select the location of the generated Validation OS image;
2. [Optional] Add the drivers to the mounted Validation OS image;
3. [Optional] Add one or more desired on-demand features;
4. [Optional] Set/override registry keys in the Validation OS image;
5. [Optional] Include custom binaries/applications in the Validation OS image;
6. [Optional] Create a Visual Studio solution with references to the SDK matching the generated Validation OS image.

Getting started with Validation OS Image Builder

Validation OS Image Builder is a GUI tool that enables you to easily generate a custom Validation OS image for your specific scenario. It allows you to add

optional packages such as Audio, Bluetooth, Camera, Multimedia, USB, etc.
drivers for your specific hardware
other software applications that you want to include in the Validation OS image
registry keys that you want enabled in the Validation OS image upon startup
startup commands that you want to run on OS startup

It also allows you to generate an SDK that can be used for the specific Validation OS image being generated.

The list of available optional featuire packages can be found here: Feature Packages

Using Validation OS Image Builder

The following is a step-by-step usage guide to the basic flow of Validation OS Image Builder from the Validation OS ISO package.

Mount the Validation OS ISO package, and navigate to <ISO_ROOT>:\ImageBuilder folder where <ISO_ROOT>: is the drive where the ISO was mounted.
Run ValidationOSImageBuilder.exe to start Validation OS Image Builder and accept the prompt where you are asked to run the program with Administrator privileges
Click "Get started" to go to the Features screen
In the Features screen, select the features you want to add to the Validation OS image and click Next to go to the Drivers screen (see the list of available features in the section above)
In the optional Drivers screen, select the folder where the drivers for your device are located
In this screen, you may also optionally add the following components to your image
1. Optional software folder: this allows you to include a folderthat contains optional .EXE files that will be included in the Validation OS image
2. Registry file: this allows you to upload a .REG file containing Registry entries which will be included in the Validation OS image at boot time
3. Startup commands: this allows you to add a .EXE file to the Validation OS image which will execute at boot time
Click Next to go to the Output screen
In the Output screen, you can
1. choose the folder where the output WIM file and other components will be generated (default is C:\ValidationOS)
2. specify whether the Validation OS image (WIM) will boot from a USB drive or a hard drive (default is USB)
3. choose whether Validation OS Image Builder should generate an associated SDK for the custom Validation OS image generated or not
4. save the most recently used Validation OS Image Builder settings to a template file for use in the future
Click Next to go to the Review & Finish screen which will show you all the Features, Drivers and Output settings you chose one final time.
Click Create to generate the Validation OS image.
Once the Validation OS image is generated you will see an option to navigate to the output folder where you will see the newly generated ValidationOS.wim.

Note

ValidationOS-2.wim is also generated in the GenImageOutput folder. This is an optimized image containing only the partition relevant to the boot type you selected in the Drivers screen

Using the Validation OS Image Builder Command Line

All the functionality that is available in the Validation OS Image Builder GUI is also available through the Validation OS Image Builder command line. To use the Validation OS Image Builder command ine, navigate to <ISO_ROOT>:\IBCLI folder where <ISO_ROOT>: is the drive where the ISO was mounted.

The Validation OS Image Builder command line utility is called ValidationOSImageBuilderCLI.exe.

The following is a list of command line options available:

-l, --list List all features included in the ISO

-i, --info <info> Get the description of a specific feature

-rp, --resolve <resolve> List all packages included by a set of features

-f, --features <features> Specify features to include

-d, --drivers <drivers> Specify the driver folder path

-s, --software <software> Specify the software folder path

-r, --registry <registry> Specify the registry file path

-sc, --startup-command <startup-command> Specify the startup command file path

-o, --output <output> Specify the output folder path

-sdk, --generate-sdk Generate SDK solution

-st, --save-template Save settings to a template

-g, --generate-image Trigger image generation

-api, --generate-api Generate API Surface from features

-lt, --load-template <load-template> Load a template file

-bt, --boottype <boottype> Specify the boot type (USB/InternalDisk).
        Default is USB

--version Show version information

-?, -h, --help Show help and usage information

Examples of how to use the command line options are displayed when you run ValidationOSImageBuilderCLI -h

Using the generated SDK

To use the generated SDK, you will need Microsoft Visual Studio installed on your computer.

In Explorer, navigate to the output folder (which is usually named C:\ValdationOS<Date-Time of image creation>) where you will see a folder named sdk. Inside this folder you will see a .sln file. Double-click on this file to open it in Visual Studio.

In the Solution Explorer view in Visual Studio, you will see a .cpp file. You may edit this file with your code or add your own code files to this project. To view the Nuget packages your project references, you can right-click References in the Solution Explorer view and select Manage Nuget Packages

To build the solution, select Build from the main menu and select Build Solution which will generate the .exe file from this code for your custom Validation OS image.

Using APIValidator with apisurface.xml

Along with the ValidationOS.wim image, the Image Builder also generates an apisurface.xml file in the api folder. This file contains a reference list of all the API functions the custom ValidationOS.wim image supports.

You can use a tool called APIValidator.exe with any .exe file and this apisurface.xml file as inputs to determine if there are incompatibilities between your .exe file and your custom ValidationOS.wim image.

To install APIValidator.exe, please refer to the instructions in the file <ISO_ROOT>:\SDK\ValidationOS_System_Kit-APIValidator_Usage.txt. You will have to install WDK first. Once installed, a typical command to analyze a .exe file against the API surface file would look like this:

Apivalidator.exe -BinaryPath:"<Path to .exe file>" -SupportedApiXmlFiles:"<Path to apisurface.xml file>"

In the output you will see a list of errors, if any, along with details of the incompatible dependencies.

Validation OS Image Builder SDK Samples

You can view code samples that make use of the various features supplied with Validation OS Image Builder here: https://github.com/microsoft/validation-OS

Share via