Use the WSK to create a basic VM image

  • Article

In this walkthrough, we'll show you how to use the different components of the Windows System Kit to build a baseline Factory OS image on a VM. We'll show you how to use feature manifests and image configuration files to configure your image.

To run through this lab, you'll need:

  • Technician PC with:
    • The Windows System Kit installed
    • Hyper-V manager installed
  • A sample driver (optional)
  • A sample UWP app (optional)

  1. Mount your Windows System Kit ISO.

  2. Open the Image building environement by running SetImagGenEnv.cmd as administrator. SetImagGenEnv.cmd is in the root of the mounted WSK.

  3. Create a workspace

    We'll start by creating a Workspace. Workspaces are a collection of files you need to make image. When you create a Workspace, you'll need to choose what architecture, product, layout, boot type, and image type. Based on your selections, the Windows System Kit will create a Workspace with an OEMInput file that serves as a starting point for image configuration. In this lab, we'll build a Factory OS image that we can deploy to a VM:

    PrepWSKWorkspace "C:\Workspace" -Product FactoryOS -VM

    Note

    The %WSKWorkspaceRoot% variable that you'll see throughout this lab is automatically set when you run prepwskworkspace. If you close and reopen the Windows System Kit environment, you can set the workspace root by navigating to your workspace folder and running SetWSKWorkspaceRoot.cmd.

  4. Add a driver to your image (optional)

    When you created your Workspace, the Windows System Kit created a file called OEMDriversFM.xml. This file allows you to define the drivers you want to include in your image. The OEMDrivers.xml file that's generated by the Windows System Kit doesn't contain any information about additional drivers. If you have a sample driver you'd like to add:

    1. Copy the driver .inf file(s) and all its associated support files (.cab, .sys, etc.) to C:\Workspace\DCHUDrivers.

    2. Run a script to automatically update the OEMDriversFM.xml:

      UpdateWSKDriversFM

    See Driver feature manifest to see learn more about adding drivers, including how to mark drivers as optional and how to generate a new Apps FM.

  5. Add an app to your image

    When you created your Workspace, the Windows System Kit created a file called OEMAppsFM.xml. This file defines what's necessary to add a particular app to your image. The sample file is configured to add the Calculator app as an optional feature to your image. Your image configuration file already has the Calculator app included, as well as its dependencies. Here's how to add an additional app:

    1. Copy an .appx bundle, its license file, and any dependencies into %WSKWorkspaceRoot%\Apps folder.

    2. From the Build Environment, run:

      UpdateWSKAppsFM

    3. You'll have an updated OEMAppsFM.xml file that includes the apps that are in the Apps folder. When you ran UpdateWSKAppsFM, the added applications are not marked as optional. If you want them to be optional, edit the XML file and set Optional = True for the apps you want optional.

    4. Apps that aren't set as optional will be included in your image (as long as the FM file is included in your image configuration file). If you've set an app as optional and want to add it to your image configuration file, you have to add it's ID to the AppXOptionalPackages section. Here's how adding the Calculator app looks (since it was set as optional when you built your workspace).

      Look at the Entry in OEMAppsFM.xml:

      <PackageFile Optional="true" ID="Microsoft.WindowsCalculator_8wekyb3d8bbwe" LicenseFile="Microsoft.WindowsCalculator_8wekyb3d8bbwe.xml" Name="Microsoft.WindowsCalculator_8wekyb3d8bbwe.appxbundle" Path="$(mspackageroot)\Appx\Calculator"/>

      Note the ID (Microsoft.WindowsCalculator_8wekyb3d8bbwe), we'll use this to add the app.

      Copy the ID and paste it into the image configuration file. It will look like this:

      <AppXOptionalPackages>
<!-- Add optional APPX packages here. -->
    <AppXID>Microsoft.WindowsCalculator_8wekyb3d8bbwe</AppXID>
</AppXOptionalPackages>

    5. Save your image configuration file.

    If you'd like to make more apps available in your image, see App feature manifest.

  6. Include Feature Manifests in your image configuration file

    When you created your workspace, the Windows System Kit created an image configuration file that automatically includes OEMAppsFM.xml and OEMDriversFM.xml. If you create additional feature manifests, you need to add them under the AdditionalFMs element in the image configuration file. This makes the features defined in the feature manifests available to add to your image. All the features that are in your image configuration file are defined in feature manifests. Adding a feature manifest to your image configuration file makes all the features defined in that feature manifest available to add to your image.

    Open your Image Configuration file in an XML editor and verify that OEMAppsFM.xml and OEMDriversFM.xml are listed. Apps and drivers included in these FMs will automatically be included in your image, unless specified as optional. You can learn more about marking a feature as optional at Feature manifests.

    Open your image configuration file. You should see the following FMs listed in your file. If the feature manifests for your apps and drivers aren't listed, add them so it looks like this:

    <AdditionalFMs>
<!-- You MUST include GenericDeviceFM.xml and FOSNonProductionFM.xml! -->
<AdditionalFM>%WSKContentRoot%\FMFiles\%WSKImageArchitecture%\FactoryOS\GenericDeviceFM.xml</AdditionalFM>
<AdditionalFM>%WSKContentRoot%\FMFiles\%WSKImageArchitecture%\FactoryOS\FOSNonProductionFM.xml</AdditionalFM>
<AdditionalFM>%WSKContentRoot%\FMFiles\%WSKImageArchitecture%\FactoryOS\HardwareValidationFM.xml</AdditionalFM>
<!-- Add OEM FMs here. -->
<AdditionalFM>%WSKWorkspaceRoot%\FMFiles\OEMAppsFM.xml</AdditionalFM>
<AdditionalFM>%WSKWorkspaceRoot%\FMFiles\OEMDriversFM.xml</AdditionalFM>
</AdditionalFMs>

  7. Create an image

    Run the following command to build your image. When we setup our workspace we set the image to be a VM. This will build a VM in a folder called Workspace.Output.

    BuildWSKImage %WSKWorkspaceRoot%\FactoryOS_Development_AMD64_UEFI_SpacesGPT_VM.xml

    Note

    The xml file that's referenced here may be different depending on the options that you chose when you built your workspace. If you get an error when you run this command, make sure the filename is correct.

    Important

    If you try to generate an image in the destination folder that already includes an .FFU images or virtual hard disks with the same name, image creation will fail with the following error:

    imageapp : ERROR : ThreadId18164 OutputFile C:\FactoryOS.Output\FactoryOS_Development_AMD64_UEFI_SpacesGPT_Hardware.ffu already exists.

    Prior to generating an image, make sure that your output folder doesn't already contain a generated image of the same name.

  8. Create a Virtual Machine that uses the virtual hard drive you created. Once you're booted, you can connect to the device using Device Portal, SSH, or TShell.