What's new in MakePRI.exe configuration

  • Статья

This topic describes configuration changes for the MakePRI.exe tool to support the resource pack generation pipeline for Windows 8.1 and later.

  • majorVersion attribute
    • Schema for majorVersion
    • Example for majorVersion
    • Deprecating /vma message
  • targetOsVersion attribute
    • Schema for targetOsVersion
    • Example for targetOsVersion
    • Internal PRI version
    • targetOsVersion in dump file
    • File compatibility
  • isDeploymentMergeable attribute
    • Schema for isDeploymentMergeable
    • Example for isDeploymentMergeable
    • isDeploymentMergeable in dump file
  • Packaging node
    • Example of AutoResourcePackage along a specific dimension
    • Example of manual ResourcePackage
    • Nongoals of packaging node
  • Parsing the packaging node
  • Handling candidates (found in the index) with multi-qualifier-sets
  • Default configuration file

majorVersion attribute

The /vma flag is deprecated for Windows 8.1 and later. Instead, provide the major version number through configuration of the PRI file. If you provide a version value in both the /vma flag and the config file, MakePRI.exe gives preference to the value read from the config file. The major version defaults to 1 if none is provided.

Schema for majorVersion

This is the schema for majorVersion:

<xs:element name="resources">
  <xs:complexType>
    <xs:sequence>
      ...
      ...
      ...
    </xs:sequence>
    <xs:attribute name="majorVersion" type="xs:positiveInteger" use="optional" />
  </xs:complexType>
</xs:element>

Example for majorVersion

This example shows how to use majorVersion:

<resources majorVersion="2">
    <index root="\" startIndexAt="\">
    ...
    ...
       </index>
</resources>

Deprecating /vma message

MakePRI.exe shows this message if the /vma flag is used:

'/VersionMajor(vma) flag has been deprecated. Please specify major version in 
the configuration file using 'majorVersion' attribute on 'resources' node. 
For more information, refer to <msdn link>

The help text for the /vma flag is tagged with this "deprecated" string:

/VersionMajor(vma): <INTEGER> [Deprecated] Major version number for index, default is 1

targetOsVersion attribute

The format of the PRI XML configuration file is changed in Windows 8.1 and later to support various optimizations. To support building PRI files that are compatible with Windows 8, the targetOsVersion optional attribute is added to the 'resources' node to indicate the target operating system version. By default, MakePRI.exe will generate the latest file format.

Schema for targetOsVersion

This is the schema for targetOsVersion:

<xs:element name="resources">
  <xs:complexType>
    <xs:sequence>
      ...
      ...
      ...
    </xs:sequence>
    <xs:attribute name="targetOsVersion" type="xs:string" use="optional" />
  </xs:complexType>
</xs:element>

These values are supported:

Target Description

Windows 8

6.2.1

Windows 8.1

6.3.0

 

Here are error strings for particular scenarios:

Scenario Error string
A targetOsVersion other than "6.2.1" or "6.3.0" is specified Invalid Configuration: Invalid targetOsVersion specified.
'packaging' node is specified with "6.2.1" Invalid Configuration: 'Packaging' node is not supported with this targetOsVersion.

 

Example for targetOsVersion

This example shows how to use targetOsVersion:

<resources targetOsVersion="6.2.1">
    <index root="\" startIndexAt="\">
    ...
    ...
       </index>
</resources>

Internal PRI version

The targetOsVersion value internally maps to an MRM number that is referenced in file MrmFiles.h:

targetOsVersion value Target MRM number
6.2.1 Windows 8 mrmfile0
6.3.0 Windows 8.1 mrmfile1

 

targetOsVersion in dump file

MakePRI.exe adds the targetOsVersion value to the detailed dump file:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PriInfo>
    <PriHeader>
            <TargetOS version="6.2.1"/>
        <WindowsEnvironment version="1.3" checksum="701192710"/>
        <AutoMerge>false</AutoMerge>
    </PriHeader>
      ...
      ...
</PriInfo>

File compatibility

Windows 8.1 supports Windows 8 PRI files. But, if you try to use a Windows 8.1 PRI file on a Windows 8 computer, you receive a failure because the file format is different.

isDeploymentMergeable attribute

The isDeploymentMergeable attribute will cause MakePRI.exe to set a flag in the PRI file that causes:

  • Deployment merge to identify that this PRI file can merge.
  • GetFullyQualifiedReference to return an error in case this flag is set and the resource manager has been initialized with a file.

The default value of this attribute is TRUE. MakePRI.exe only sets the flag in PRI if you target Windows 8.1. If you supply this attribute with a config that targets Windows 8, MakePRI.exe ignores it with no error or warning.

We recommend that you set isDeploymentMergeable for ResourcePack creation in Windows 8.1 and later.

Schema for isDeploymentMergeable

This is the schema for isDeploymentMergeable:

<xs:element name="resources">
  <xs:complexType>
    <xs:sequence>
      ...
      ...
      ...
    </xs:sequence>
    <xs:attribute name="isDeploymentMergeable" type="xs:boolean " use="optional" />
  </xs:complexType>
</xs:element>

Example for isDeploymentMergeable

This example shows how to use isDeploymentMergeable:

<resources targetOsVersion="6.2.1", isDeploymentMergeable="true">
    <index root="\" startIndexAt="\">
    ...
    ...
       </index>
</resources>

isDeploymentMergeable in dump file

MakePRI.exe adds the isDeploymentMergeable value to the detailed dump file:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PriInfo>
    <PriHeader>
            <TargetOS version="6.2.1"/>
        <WindowsEnvironment version="1.2" checksum="701192710"/>
        <AutoMerge>false</AutoMerge>
        <IsDeploymentMergeable>false</IsDeploymentMergeable>

    </PriHeader>
      ...
      ...
</PriInfo>

Packaging node

The PRI XML configuration file supports a new 'packaging' node that defines PRI split information. The schema for the 'packaging' node is defined for both automatic (support for AutoResourcePackage along a specific dimension) and manual configuration:

<xs:element name="packaging" maxOccurs="1" minOccurs="0">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="autoResourcePackage" maxOccurs="unbounded" minOccurs="0">
        <xs:complexType>
          <xs:attribute name="qualifier" type="xs:string" use="required" />
        </xs:complexType>
      </xs:element>
      <xs:element name="resourcePackage" maxOccurs="unbounded" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="qualifierSet" maxOccurs="unbounded" minOccurs="0">
              <xs:complexType>
                <xs:attribute name="definition" type="xs:string" use="required" />
              </xs:complexType>
            </xs:element>
          </xs:sequence>
          <xs:attribute name="name" type="xs:string" use="required" />
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:element>

Example of AutoResourcePackage along a specific dimension

This example shows how to use "AutoResourcePackage along a specific dimension":

  <packaging>
    <autoResourcePackage qualifier="Language"/>
    <autoResourcePackage qualifier="Scale"/>
    <autoResourcePackage qualifier="DXFeatureLevel"/>
  </packaging>

Example of manual ResourcePackage

This example shows how to use "manual ResourcePackage":

  <packaging>
    <resourcePackage name="Germany">
      <qualifierSet definition="lang-de-de"/>
      <qualifierSet definition="lang-es-es"/>
    </resourcePackage>  
    <resourcePackage name="France">
      <qualifierSet definition="lang-fr-fr"/>
    </resourcePackage>  
    <resourcePackage name="HighRes1">
      <qualifierSet definition="scale-140"/>
    </resourcePackage>
    <resourcePackage name="HighRes2">
      <qualifierSet definition="scale-180"/>
    </resourcePackage>
  </packaging>

Nongoals of packaging node

MakePRI.exe doesn't explicitly block generation of resource PRI files along any specific dimension. Restrictions along a certain set of dimensions are defined and implemented externally by either MakeAppx.exe or other tools in the pipeline.

Parsing the packaging node

MakePRI.exe parses the 'packaging' node after all the 'index' nodes to populate all the default qualifiers. MakePRI.exe collects parsed info in these data structures.

enum ResourcePackageMode {
    None,
    AutoPackQualifier,
    ManualPack
}

ResourcePackageMode         eResourcePackageMode;
list<string>              RPQualifierList; // To store AutoResourcePackage Qualifiers
map<string, list<string>>   RPNameToQSIMap; // To store ResourcePackage name to QualifierSet list mapping.

Here are some error and warning strings for particular scenarios:

Scenario Type of issue String
More than one mode found in the configuration. For example, Manual and AutoResourcePackage specified. Error Invalid Configuration: 'packaging' node cannot have more than one mode of operation.
No candidates are found for the QualifierSet listed for 'ResourcePackage' node. Warning Invalid Configuration: No candidates found for <Resource Package Name>.
No candidates found for qualifier listed under ‘AutoResourcePackage’ node. Warning Invalid Configuration: No candidates found for qualifier <qualifier name>. Resource Package not generated.
A default qualifier is listed under resource package. Error Invalid Configuration: <Qualifiername>=<QualifierValue> is a default qualifier and its candidates cannot be added to a resource package.
None of the modes are found. That is, empty 'packaging' node found. Warning Invalid Configuration: No packaging mode specified.
AutoResourcePackage qualifier contains multiple qualifiers. For example, language_scale. Error Invalid Configuration : AutoResourcePackage with multiple qualifiers is not supported.
ResourcePackage QualifierSet contains multiple qualifiers. For example, language-en-us_scale-100 Error Invalid Configuration : QualifierSet with multiple qualifiers is not supported.
Duplicate resourcepack name found. Error Invalid Configuration : Duplicate resource pack name <rpname>.
Same qualifier set defined in two resource packages. Error Invalid Configuration: Multiple instances of QualifierSet "<qualifier tags>" found.

 

Handling candidates (found in the index) with multi-qualifier-sets

MakePRI.exe explicitly blocks multi-qualifier set for packaging in the configuration file. However, candidates with multi-qualifier sets can still be found in the project. MakePRI.exe doesn't generate an error if these candidates are found in the project.

If 'AutoResourcePackage' is provided as a packaging option, any candidates (found in the index) that belong to multi-qualifier-sets are placed in a resource package based on the qualifier priority.

For example, suppose AutoResourcePackage is provided on Languages and Scale, and a multi-qual candidate is found (en-us\logo.scale-100.jpg). MakePRI.exe places the candidate in 'en-us' resource PRI instead of 'scale' resource PRI because 'Language' is higher priority than 'Scale.'

For example, suppose AutoResourcePackage is provided on Languages, and a multi-qual candidate is found (en-us\logo.scale-100.jpg). MakePRI.exe places the candidate in 'en-us' resource PRI because 'scale' doesn’t exist.

Default configuration file

MakePRI.exe generates this configuration when the createconfig option is specified:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resources targetOsVersion="6.3.0" majorVersion="1">
  <packaging>
    <autoResourcePackage qualifier="Language"/>
    <autoResourcePackage qualifier="Scale"/>
    <autoResourcePackage qualifier="DXFeatureLevel"/>
  </packaging>
    <index root="\" startIndexAt="\">
        <default>
            <qualifier name="Language" value="en-us"/>
            <qualifier name="Contrast" value="standard"/>
            <qualifier name="Scale" value="100"/>
            <qualifier name="HomeRegion" value="001"/>
            <qualifier name="TargetSize" value="256"/>
            <qualifier name="LayoutDirection" value="LTR"/>
            <qualifier name="Configuration" value=""/>
            <qualifier name="AlternateForm" value=""/>
            <qualifier name="DXFeatureLevel" value="DX9"/>
    </default>
        <indexer-config type="folder" foldernameAsQualifier="true" filenameAsQualifier="true" qualifierDelimiter="."/>
        <indexer-config type="resw" convertDotsToSlashes="true" initialPath=""/>
        <indexer-config type="resjson" initialPath=""/>
        <indexer-config type="PRI"/>
    </index>
    <!--<index startIndexAt="Start Index Here" root="Root Here">-->
    <!--        <indexer-config type="resfiles" qualifierDelimiter="."/>-->
    <!--        <indexer-config type="priinfo" emitStrings="true" emitPaths="true"/>-->
    <!--</index>-->
</resources>