Configure settings

  • Article

This topic describes how to configure classic settings customizations for your Factory OS images. These settings will be included in an image, and will apply to all devices that are flashed with the image.

Generate a settings customization file

Use the CreateWSKCustomizationsXML script in the WSK to generate a Settings customization file:

  1. Mount the WSK ISO and open the Windows System Kit environment as an administrator:

    D:\SetWSKImagGenEnv.cmd

  2. Set your workspace as the workspace root:

    cd c:\workspace
SetWSKWorkspaceRoot.cmd

  3. Generate a customization XML file:

    CreateWSKCustomizationsXML

    • You can optionally create a set of customization XML files by adding the -categorize option. This generates a set of customization XML files, divided by category:

      CreateWSKCustomizationsXML -Categorize

    • You can also manually separate each customization XML further, provided the customization XML files you create don't have the same <FeatureArea> repeated in more than one customization XML.

    CreateWSKCustomizationsXML leverages the Workspace configuration file, to reduce the number of required parameters. The following optional parameters are available:

    Parameters Options
    -Categorize Splits the CustomizationXML into multiple files, one file per customization. If this option isn't used, one large customization file will be created
    -OutputFolder Specifies the folder where the customization XML is created

    Note

    This script will overwrite any existing customization XML file in the output directory. If you have an existing customization XML file, either back it up prior to running this script, or use the -OutputFolder option to specify a different output folder.

  4. After the script runs, you'll have one or more settings configuration files in your workspace, in %WSKWorkspaceRoot%\OEMCustomization\CustomizationXML.

Customize your settings customization file

  1. Open you settings customization file in a text editor.

  2. Set the attributes in the <Identity> element:

    <Identity OwnerName="OEMName" ReleaseType="Test" />
    Attribute Description
    OwnerName The name of the entity creating the image
    ReleaseType This should match the image's ReleaseType OEMinput element. Valid value is: Test. See below to learn how to choose the correct value.

  3. Configure settings. Each setting is in an XML element called <Customization>. Here's what a <Customization> element looks like:

    <Customization Name="SplitLayoutFile">
  <ReadOnlyMetadata Description="OEM/SV-owned split layout file. (File must be named DeviceLayoutOEM.xml)" Type="FILE" DefaultValue="" SupportedExtensions="xml" />
  <Value />
</Customization>

    This example shows various attributes for the setting that cover information about the setting and possible values. It also has an empty element named <Value>, which you'll use to configure the setting.

  4. Customize a setting by modifying the <Value> elements of the settings you want to customize. When you're done, save the XML file.

    The below snippet shows the SplitLayoutFile setting populated with the path to the DeviceLayoutOEM.xml file path.

    <Customization Name="SplitLayoutFile">
  <ReadOnlyMetadata Description="OEM/SV-owned split layout file. (File must be named DeviceLayoutOEM.xml)" Type="FILE" DefaultValue="" SupportedExtensions="xml" />
  <Value>%WSKWorkspaceRoot%\OEMCustomization\DeviceLayout\DeviceLayoutOEM.xml</Value>
</Customization>

Generate settings customization packages and add them to your OEMInput file

Note

For faster customizations testing, once you generate your customization packages, you can add them directly to a test image.

  1. Open the Windows System Kit environment as an administrator

  2. Set your workspace root:

    cd c:\workspace
SetWSKWorkspaceRoot.cmd

  3. The CreateWSKCustomizationsFM script in the WSK generates settings packages and a settings customization feature manifest that include the settings packages. The script then adds the customization feature manifest to your OEMInput file. By default, CreateWSKCustomizationsFM will process all customization XML files a workspace's %WSKWorkspaceRoot%\OEMCustomization\CustomizationXML folder.

    CreateWSKCustomizationsFM

    Note

    This command no longer accepts the -OEMInput, -OEMName, or -Architecture parameters.

    • If you created a set of categorized customization files, use the -customizationXML option to point to the folder where your customization XML files are saved. For example:

      CreateWSKCustomizationsFM -customizationXML %WSKWorkspaceRoot%\OEMCustomization\CustomizationXML

    CreateWSKCustomizationsFM leverages the Workspace configuration file, to reduce the number of required parameters. You can use the following optional parameters with CreateWSKCustomizationsFM:

    Parameter Options
    -OEMPackagesFolder Specified the folder path where your customization packages are stored. All the customization packages in this folder will be included in the feature manifest. Default path is %WSKWorkspaceRoot%\OEMCustomization\CustomizationXML.
    -Version Allows adding a version number appended to package names. Format is xxxx.y.z.z. Default is 1000.0.0.0.
    -FMFile Allows you to specify the path of the Customization feature manifest file that defines your custom settings. This FM gets added to your OEMInput file so that the settings are included in your image. Default is %WSKWorkspaceRoot%\FMFiles\OEMCustomizationsFM.xml.
    -CustomizationXML Path to a CustomizationXML file or folder that contains customization files. If you specify a folder path, all of the customization settings xml files will be processed and will output a single settings FM. If this option isn't specified, the default path is %WSKWorkspaceRoot%\OEMCustomization\CustomizationXML.xml.

  4. Verify that your OEMCustomizationsFM.xml file is in your OEMInput file. You'll find it in the <AdditionalFMs> element:

    <AdditionalFMs>
...
  <AdditionalFM>%WSKWorkspaceRoot%\FMFiles\OEMAppsFM.xml</AdditionalFM>
  <AdditionalFM>%WSKWorkspaceRoot%\FMFiles\OEMDriversFM.xml</AdditionalFM>
  <AdditionalFM>%WSKWorkspaceRoot%\FMFiles\OEMCustomizationsFM.xml</AdditionalFM>
</AdditionalFMs>

  5. Generate an image. When you generate an image, the settings that you configured will be set in your image.

    Note

    It's possible to add customization packages directly to images for faster iteration while testing. See Patch a Factory OS image for testing for more information.

Settings customization file schema

Settings customization files are made up of several elements that categorize settings into various groups. Settings within each group are related. Each setting has attributes that show how each setting can be configured. To configure a setting, you add a value into the <Value> element of the setting that you want to customize.

<?xml version="1.0" encoding="utf-8"?>
<CustomizationFile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" SchemaVersion="1.0" BuildArch=" " Product=" " BuildInfo=" " xmlns="http://schemas.microsoft.com/embedded/2004/10/ImageUpdate">
  <Identity OwnerName="" ReleaseType="" />
  <Categories>
    <Category Name="Default">
      <FeatureAreas>
        <FeatureArea Name="Area1">
          <Customizations>
            <Customization Name="Example1">
              <ReadOnlyMetadata Description="Attributes in this element describe values for configuring this setting" Type="REG_DWORD" DefaultValue="1" Minimum="0" Maximum="1" />
              <Value />
            </Customization>
            <Customization Name="Example2">
              <ReadOnlyMetadata Description="Set the value element to configure settings" Type="REG_SZ" DefaultValue="" />
              <Value />
            </Customization>
          </Customizations>
        </FeatureArea>
      </FeatureAreas>
    </Category>
    <Category Name="Category2">
      <FeatureAreas>
        <FeatureArea Name="Area2">
          <Customizations>
            <Customization Name="Example3">
              <ReadOnlyMetadata Description="Set the value element to configure settings" Type="REG_SZ" DefaultValue="" />
              <Value />
            </Customization>
          </Customizations>
        </FeatureArea>
      </FeatureAreas>
    </Category>
  </Categories>
</CustomizationFile>

Audit the settings in an image

When you generate an image, your workspace output folder includes a log that contains information about settings. See WCOSCustomizationReport.xml for more information.