MakePri.exe 配置文件MakePri.exe configuration file

本主题介绍 MakePri.exe XML 配置文件的架构;也称为 PRI 配置文件。This topic describes the schema of the MakePri.exe XML configuration file; also known as a PRI config file. MakePri.exe 工具具有 createconfig 命令,可用于创建一个新的初始化 PRI 配置文件。The MakePri.exe tool has a createconfig command that you can use to create a new, initialized PRI config file.

备注

当你在安装 Windows 软件开发工具包时检查 UWP 托管应用的 Windows SDK 选项时,会安装 MakePri.exe。MakePri.exe is installed when you check the Windows SDK for UWP Managed Apps option while installing the Windows Software Development Kit. 它将安装到 (的路径 %WindowsSdkDir%bin\<WindowsTargetPlatformVersion>\x64\makepri.exe 和其他体系结构) 的文件夹中。It is installed to the path %WindowsSdkDir%bin\<WindowsTargetPlatformVersion>\x64\makepri.exe (as well as in folders named for the other architectures). 例如 C:\Program Files (x86)\Windows Kits\10\bin\10.0.17713.0\x64\makepri.exeFor example, C:\Program Files (x86)\Windows Kits\10\bin\10.0.17713.0\x64\makepri.exe.

PRI 配置文件控制索引哪些资源以及如何索引。The PRI config file controls what resources are indexed, and how. 配置 XML 必须符合以下架构。The configuration XML must conform to the following schema.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="resources">
    <xs:complexType>
      <xs:sequence>
        <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>
        <xs:element maxOccurs="unbounded" name="index">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="qualifiers" minOccurs="0" maxOccurs="unbounded">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element minOccurs="1" maxOccurs="unbounded" name="qualifier">
                      <xs:complexType>
                        <xs:attribute name="name" type="xs:string" use="required" />
                        <xs:attribute name="value" type="xs:string" use="required" />
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element name="default" minOccurs="0" maxOccurs="unbounded">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element minOccurs="1" maxOccurs="unbounded" name="qualifier">
                      <xs:complexType>
                        <xs:attribute name="name" type="xs:string" use="required" />
                        <xs:attribute name="value" type="xs:string" use="required" />
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element name="indexer-config" minOccurs="0" maxOccurs="unbounded">
                <xs:complexType>
                  <xs:sequence>
                    <xs:any minOccurs="0" maxOccurs="unbounded" processContents="skip"/>
                  </xs:sequence>
                  <xs:attribute name="type" type="xs:string" use="required" />
                  <xs:anyAttribute processContents="skip"/>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
            <xs:attribute name="root" type="xs:string" use="required" />
            <xs:attribute name="startIndexAt" type="xs:string" use="required" />
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute name="isDeploymentMergeable" type="xs:boolean" use="optional" />
      <xs:attribute name="majorVersion" type="xs:positiveInteger" use="optional" />
      <xs:attribute name="targetOsVersion" type="xs:string" use="optional" />
    </xs:complexType>
  </xs:element>
</xs:schema>
  • default 元素指定当运行时上下文不匹配任何候选资源时用于解析资源的上下文(语言、比例、对比度等)。The default element specifies the context (language, scale, contrast, etc.) that should be used to resolve resources when the runtime context does not match any resource candidates. 此上下文在生成时间进行指定,并且不会更改,因此当创建上下文时将资源解析到此上下文。Because this context is specified at build time and does not change, resources are resolved to this context as qualifiers are created. 匹配分数在生成时间进行存储。The matched score is stored at build time. 必须为每个限定符都指定一个值。Every qualifier must have some value specified. 请参阅 ResourceContext 获取有关如何选择资源的详细信息。See ResourceContext for details on how resources are chosen.
  • index 元素定义对资产完成的离散索引传递。The index element defines discrete indexing passes that are done over the assets. 每个索引传递确定要使用的特定格式索引器以及要索引的资源。Each indexing pass determines the format-specific indexers to use, and which resources to index.
  • qualifiers 元素设置其他资源继承的第一个文件或文件夹的初始限定符。The qualifiers element sets the initial qualifiers for the first file or folder that other resources inherit. 每个限定符元素必须具有有效的名称和值(请参阅定制语言、比例、高对比度和其他限定符的资源)。Each qualifier element must have a valid name and value (see Tailor your resources for language, scale, high contrast, and other qualifiers).
  • root 属性是索引传递的物理文件的路径根。The root attribute is the path root of the physical file for the index pass. 它可以是相对的或绝对的。It can be relative or absolute. 如果是相对的,则它追加到你在命令行中提供的项目根。If relative, it is appended to the project root that you provide in the command line. 如果是绝对的,则它直接用作索引传递根。If absolute, it is directly used as the index pass root. 使用反斜杠或正斜杠都可以。Back or forward slashes are acceptable. 尾部斜杠会被删除。Trailing slashes are trimmed. 索引传递的根确定一个文件夹,所有资源对该文件夹而言都被视为相对的。The root of the index pass determines the folder to which all resources are considered relative.
  • startIndexAt 属性是编制索引过程中使用的初始种子文件或文件夹。The startIndexAt attribute is the initial seed file or folder used in indexing. 它相对于索引传递根。It is relative to the index pass root. 空值假设索引传递根文件夹。An empty value assumes the index pass root folder.

默认 PRI 配置文件Default PRI config file

当签发 createconfig 命令时,MakePri.exe 生成此新的初始化 PRI 配置文件。MakePri.exe generates this new, initialized PRI config file when the createconfig command is issued.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resources targetOsVersion="10.0.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="Theme" value="dark"/>
      <qualifier name="AlternateForm" value=""/>
      <qualifier name="DXFeatureLevel" value="DX9"/>
      <qualifier name="Configuration" value=""/>
      <qualifier name="DeviceFamily" value="Universal"/>
      <qualifier name="Custom" value=""/>
    </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" emitEmbeddedData="true"/>-->
  <!--</index>-->
</resources>

打包元素Packaging element

packaging 元素定义 PRI 拆分信息。The packaging element defines PRI split information. 针对自动(支持沿特定维度的 autoResourcePackage)和手动配置定义 packaging 元素的架构。The schema for the packaging element is defined for both automatic (support for autoResourcePackage along a specific dimension), and manual configuration.

此示例演示如何使用沿特定维度的 autoResourcePackageThis example shows how to use autoResourcePackage along a specific dimension.

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

此示例演示如何使用手动 resourcePackageThis 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-200"/>
    </resourcePackage>
    <resourcePackage name="HighRes2">
      <qualifierSet definition="scale-400"/>
    </resourcePackage>
  </packaging>

MakePri.exe 不明确阻止沿任何特定维度生成资源 PRI 文件。MakePri.exe doesn't explicitly block generation of resource PRI files along any specific dimension. 沿一组特定维度的限制在外部由 MakeAppx.exe 或管道中的其他工具进行定义和实现。Restrictions along a certain set of dimensions are defined and implemented externally by either MakeAppx.exe or other tools in the pipeline.

MakePri.exe 分析所有 index 节点后的 packaging 元素以填充所有默认限定符。MakePri.exe parses the packaging element after all the index nodes to populate all the default qualifiers. MakePri.exe 收集在这些数据结构中分析的信息。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.

resources@isDeploymentMergeable 特性resources@isDeploymentMergeable attribute

此属性在 PRI 文件中设置标记,导致This attribute sets a flag in the PRI file that causes

  • 部署合并以标识此 PRI 文件可以合并。Deployment merge to identify that this PRI file can merge.
  • GetFullyQualifiedReference 在设置了该标志但未使用文件来初始化资源管理器的情况下返回错误。GetFullyQualifiedReference to return an error in case this flag is set and the resource manager has been initialized with a file.

此特性的默认值为 trueThe default value of this attribute is true. MakePri.exe 仅在你的目标为 Windows 10 时设置 PRI 中的标记。MakePri.exe only sets the flag in PRI if you target Windows 10.

如果你的目标为 Windows 10,我们建议你在创建资源包时省略 isDeploymentMergeable(或将其显式设置为 true)。We recommend that you omit isDeploymentMergeable (or set it explicitly to true) for resource pack creation if you target Windows 10.

如果使用 /dt detailed 选项运行 makepri dump,MakePri.exe 会将 isDeploymentMergeable 的值添加到转储文件。MakePri.exe adds the value of isDeploymentMergeable to the dump file if makepri dump is run with the /dt detailed option.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PriInfo>
    <PriHeader>
        ...
        <IsDeploymentMergeable>true</IsDeploymentMergeable>
        ...
    </PriHeader>
  ...
</PriInfo>

resources@majorVersion 特性resources@majorVersion attribute

此属性的默认值为 1。The default value for this attribute is 1. 如果你提供一个显式值,并且还对 MakePri.exe 工具使用弃用的 /VersionMajor(vma) 命令行选项,则以配置文件中的值优先。If you provide an explicit value, and you also use the deprecated /VersionMajor(vma) command-line option for the MakePri.exe tool, then the value in the config file takes precedence.

下面是一个示例。Here's an example.

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

resources@targetOsVersion 特性resources@targetOsVersion attribute

指示目标操作系统版本。Indicates the target operating system version. 下表显示了受支持的值;默认值为 6.3.0。The table below shows the values that are supported; the default value is 6.3.0.

Value 含义Meaning
10.0.010.0.0 Windows 10Windows 10
6.3.0(默认值)6.3.0 (default) Windows 8.1Windows 8.1
6.2.16.2.1 Windows 8Windows 8

下面是一个示例。Here's an example.

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

注意 Windows 相对于 PRI 文件后向兼容;但并不总是向前兼容。Note Windows is backward compatible with respect to PRI files; but not always forward compatible.

如果使用 /dt detailed 选项运行 makepri dump,MakePri.exe 会将 targetOsVersion 的值添加到转储文件。MakePri.exe adds the value of targetOsVersion to the dump file if makepri dump is run with the /dt detailed option.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PriInfo>
    <PriHeader>
        ...
        <TargetOS version="10.0.0"/>
        ...
    </PriHeader>
  ...
</PriInfo>

验证错误消息Validation error messages

下面提供了一些错误条件及相应的错误消息示例。Here are some example error conditions, and the corresponding error message.

条件Condition 严重性Severity 消息Message
指定除其中一个受支持的值以外的 targetOsVersion。A targetOsVersion other than one of the supported values is specified. 错误Error 无效的配置:指定的 targetOsVersion 无效。Invalid Configuration: Invalid targetOsVersion specified.
指定的 targetOsVersion 为“6.2.1”,且存在 packaging 元素。A targetOsVersion of "6.2.1" is specified and a packaging element is present. 错误Error 无效的配置:此 targetOsVersion 不支持“打包”节点。Invalid Configuration: 'Packaging' node is not supported with this targetOsVersion.
在配置中找到多个模式。More than one mode found in the configuration. 例如,指定了 Manual 和 AutoResourcePackage。For example, Manual and AutoResourcePackage specified. 错误Error 无效的配置:“打包”节点不能具有多个操作模式。Invalid Configuration: 'packaging' node cannot have more than one mode of operation.
默认限定符在资源包下列出。A default qualifier is listed under resource package. 错误Error 无效的配置:= 是默认限定符,不能将其候选项添加到资源包。Invalid Configuration: = is a default qualifier and its candidates cannot be added to a resource package.
AutoResourcePackage 限定符包含多个限定符。AutoResourcePackage qualifier contains multiple qualifiers. 例如 language_scale。For example, language_scale. 错误Error 无效配置: 不支持具有多个限定符的 AutoResourcePackage。Invalid Configuration : AutoResourcePackage with multiple qualifiers is not supported.
ResourcePackage QualifierSet 包含多个限定符。ResourcePackage QualifierSet contains multiple qualifiers. 例如 language-en-us_scale-100For example, language-en-us_scale-100 错误Error 无效配置: 不支持具有多个限定符的 QualifierSet。Invalid Configuration : QualifierSet with multiple qualifiers is not supported.
发现了重复的资源包名称。Duplicate resourcepack name found. 错误Error 无效的配置:重复的资源包名称 Invalid Configuration : Duplicate resource pack name .
在两个资源包中定义了相同的限定符集。Same qualifier set defined in two resource packages. 错误Error 无效的配置:找到 QualifierSet“”的多个实例。Invalid Configuration: Multiple instances of QualifierSet "" found.
找不到为“ResourcePackage”节点列出的 QualifierSet 的候选项。No candidates are found for the QualifierSet listed for 'ResourcePackage' node. 警告Warning 无效的配置:找不到 的候选项。Invalid Configuration: No candidates found for .
找不到在“AutoResourcePackage”节点下列出的限定符的候选项。No candidates found for qualifier listed under ‘AutoResourcePackage’ node. 警告Warning 无效的配置:找不到限定符 的候选项。Invalid Configuration: No candidates found for qualifier . 未生成资源包。Resource Package not generated.
找不到模式。None of the modes are found. 也就是说,发现了空的 'packaging' 节点。That is, empty 'packaging' node found. 警告Warning 无效的配置:未指定打包模式。Invalid Configuration: No packaging mode specified.