From 0763d1a2eaa570efa3a4fc0374d3e67f6daaab35 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 31 Aug 2026 21:26:02 +0000 Subject: [PATCH 1/2] Initial plan From 3e61fec9b8169111624ac39e08935e76498b9eda Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 31 Aug 2026 21:29:28 +0000 Subject: [PATCH 2/2] Document the package resource index (PRI) file format Co-authored-by: GrantMeStrength <1928855+GrantMeStrength@users.noreply.github.com> --- ...compile-resources-manually-with-makepri.md | 1 + uwp/app-resources/index.md | 1 + uwp/app-resources/pri-file-format.md | 111 ++++++++++++++++++ .../resource-management-system.md | 2 + uwp/develop/toc.yml | 2 + 5 files changed, 117 insertions(+) create mode 100644 uwp/app-resources/pri-file-format.md diff --git a/uwp/app-resources/compile-resources-manually-with-makepri.md b/uwp/app-resources/compile-resources-manually-with-makepri.md index cabac2ba18..a6631d66a7 100644 --- a/uwp/app-resources/compile-resources-manually-with-makepri.md +++ b/uwp/app-resources/compile-resources-manually-with-makepri.md @@ -59,4 +59,5 @@ When PRI files are built for other components, class libraries, assemblies, DLLs * [MakePri.exe command-line options](makepri-exe-command-options.md) * [MakePri.exe configuration](makepri-exe-configuration.md) * [MakePri.exe format-specific indexers](makepri-exe-format-specific-indexers.md) +* [Package resource index (PRI) file format](pri-file-format.md) * [Tailor your resources for language, scale, and other qualifiers](tailor-resources-lang-scale-contrast.md) diff --git a/uwp/app-resources/index.md b/uwp/app-resources/index.md index f6eb4cb406..5dda3056b7 100644 --- a/uwp/app-resources/index.md +++ b/uwp/app-resources/index.md @@ -31,6 +31,7 @@ For more info about the value proposition of localizing your app, see [Globaliza | [Specify the default resources that your app uses](specify-default-resources-installed.md) | If your app doesn't have resources that match the particular settings of a customer device, then the app's default resources are used. This topic explains how to specify what those default resources are. | | [Build resources into your app package, instead of into a resource pack](build-resources-into-app-package.md) | Some kinds of apps (multilingual dictionaries, translation tools, etc.) need to override the default behavior of an app bundle, and build resources into the app package instead of having them in separate resource packages. This topic explains how to do that. | | [Package resource indexing (PRI) APIs and custom build systems](pri-apis-custom-build-systems.md) | With the [package resource indexing (PRI) APIs](/windows/desktop/menurc/pri-indexing-reference), you can develop a custom build system for your UWP app's resources. The build system will be able to create, version, and dump (as XML) package resource index (PRI) files to whatever level of complexity your UWP app needs. | +| [Package resource index (PRI) file format](pri-file-format.md) | A package resource index (PRI) file is the binary index of your app's resources. This topic describes what a PRI file contains, how it's structured logically, and how to inspect one. | | [Compile resources manually with MakePri.exe](compile-resources-manually-with-makepri.md) | MakePri.exe is a command line tool that you can use to create and dump PRI files. It is integrated as part of MSBuild within Microsoft Visual Studio, but it could be useful to you for creating packages manually or with a custom build system. | | [Use the Windows 10 Resource Management System in a legacy app or game](using-mrt-for-converted-desktop-apps-and-games.md) | By packaging your .NET or Win32 app or game as an .msix or .appx package, you can leverage the Resource Management System to load app resources tailored to the run-time context. This in-depth topic describes the techniques. | diff --git a/uwp/app-resources/pri-file-format.md b/uwp/app-resources/pri-file-format.md new file mode 100644 index 0000000000..a7f04eb7ab --- /dev/null +++ b/uwp/app-resources/pri-file-format.md @@ -0,0 +1,111 @@ +--- +description: A package resource index (PRI) file is the binary index of an app's resources. This topic describes what a PRI file contains, how it's structured logically, and how to inspect one. +title: Package resource index (PRI) file format +template: detail.hbs +ms.date: 08/31/2026 +ms.topic: article +keywords: windows 10, uwp, resource, image, asset, MRT, qualifier, PRI, resources.pri +ms.localizationpriority: medium +--- +# Package resource index (PRI) file format + +A package resource index (PRI) file is the binary index of an app's resources that the [Resource Management System](resource-management-system.md) reads at run-time in order to load the resource candidate that best matches the current context (language, scale, contrast, and so on). + +This topic describes what a PRI file contains and how you can inspect one. For the tooling that produces PRI files, see [Compile resources manually with MakePri.exe](compile-resources-manually-with-makepri.md) and [Package resource indexing (PRI) APIs and custom build systems](pri-apis-custom-build-systems.md). + +> [!IMPORTANT] +> The binary layout of a PRI file (its headers, sections, and byte-level encoding) isn't documented, and it isn't a stable contract; it can change between versions of Windows and of the Windows SDK. Don't write code that parses or produces the bytes of a PRI file directly. Use the [PRI APIs](/windows/desktop/menurc/pri-indexing-reference), [MakePri.exe](compile-resources-manually-with-makepri.md), or the run-time resource APIs described in this topic instead. Everything documented here is the *logical* structure that those supported tools and APIs expose. + +## Where PRI files come from, and where they live + +- A PRI file is generated at build time. Visual Studio and MSBuild generate one for you; you can also generate one yourself with [MakePri.exe](makepri-exe-command-options.md) or with the [PRI APIs](pri-apis-custom-build-systems.md). +- A package typically contains a single PRI file named `resources.pri` at the root of the package. That file is loaded automatically when the resource APIs are first used. +- If your app is split into resource packages (for example, one per language, or per scale), then each resource package contains its own PRI file, containing the additional candidates for that package. See [MakePri.exe configuration file](makepri-exe-configuration.md) for how that split is configured. +- A PRI file contains only data. It isn't a portable executable (PE) file, and it isn't loaded as a module. This is a deliberate difference from the Win32 app model, where resources are contained within DLLs. + +## What a PRI file contains + +Logically, a PRI file is a tree of named resources, where each named resource owns one or more candidate values. The MakePri.exe `dump` command projects that tree into XML, so a dump is a convenient way to read the structure. Here's a dump of a small PRI file. + +```xml + + + + + en-US,de-DE + + + + + sample-image.png + + + + + + + LocalizedString1-en-US + + + LocalizedString1-neutral + + + + + +``` + +The pieces of that structure are as follows. + +| Element | Description | +|-|-| +| Resource map | A named collection of resources; the root of the tree. When a PRI file is loaded from a package, the resource map name is verified to match the package identity name. A PRI file has one primary resource map, and it also records a version. At run-time, a resource map is projected as a [ResourceMap](/uwp/api/windows.applicationmodel.resources.core.resourcemap) object. | +| Qualifier set | The set of qualifier values (language, scale, contrast, and so on) that the candidates in the file are qualified by. See [Tailor your resources for language, scale, high contrast, and other qualifiers](tailor-resources-lang-scale-contrast.md). | +| Resource map subtree | A node in the tree, which contains further subtrees and named resources. Subtrees typically correspond to the resource file that the resources came from (for example, `resources` for `resources.resw`). Indexed file paths all live under a reserved `Files` subtree, so `\Images\logo.png` is indexed as `Files/images/logo.png`. | +| Named resource | A single logical resource, such as the string identifier `LocalizedString1` or the file `sample-image.png`, together with all of its variants. Each named resource has a `ms-resource` URI (see [URI schemes](uri-schemes.md)). At run-time, it's projected as a [NamedResource](/uwp/api/windows.applicationmodel.resources.core.namedresource) object. | +| Candidate | One concrete value of a named resource, together with the qualifiers that it matches. A candidate with no qualifiers is a neutral candidate, which matches any context; a candidate marked as default is the one that's used for the default qualifier values of the app. At run-time, a candidate is projected as a [ResourceCandidate](/uwp/api/windows.applicationmodel.resources.core.resourcecandidate) object. | + +A candidate value is one of three kinds: a string that's stored in the PRI file itself; a path that refers to a file elsewhere in the package (the file itself isn't stored in the PRI file); or embedded data, which is arbitrary bytes stored in the PRI file. Those three kinds correspond to the `emitStrings`, `emitPaths`, and `emitEmbeddedData` attributes of the `priinfo` indexer (see [MakePri.exe format-specific indexers](makepri-exe-format-specific-indexers.md)). + +A PRI file can also contain these optional parts. + +- **A schema.** The schema is the structure of the tree (subtrees and named resource names) without the candidate values. It's what makes it possible to version a PRI file, or to build a resource package for an existing PRI file, without rebuilding everything. You can write the schema to a separate file with the MakePri.exe `/SchemaFile(sf)` option, and you can pass a schema file, instead of a PRI file, as the input to the `versioned` and `resourcepack` commands. A resource pack that was built with the *omitSchemaFromResourcePacks* configuration switch doesn't carry its own copy of the schema, and reading it requires the main package's PRI file as an external schema. +- **A reverse map.** A debugging-only section that maps candidates back to the source files that they were indexed from. It's generated by the MakePri.exe `/ReverseMap(rm)` option, and it isn't present by default. + +For how the candidates in a PRI file are ranked and chosen at run-time, see [How the Resource Management System matches and chooses resources](how-rms-matches-and-chooses-resources.md). + +## Inspect a PRI file + +To read the contents of an existing PRI file, dump it to XML. + +```console +makepri dump /if C:\MyApp\resources.pri /of C:\resources.pri.xml /dt Detailed +``` + +The `/DumpType(dt)` option controls how much detail the XML contains. + +| Dump type | Description | +|-|-| +| `Basic` | The default. The resource maps, named resources, and their candidate values, as shown earlier in this topic. | +| `Detailed` | The same information, with additional detail about the file's internals. | +| `Schema` | The structure of the tree only, without candidate values. This is the same content that the `/SchemaFile(sf)` option writes. | +| `Summary` | A high-level overview of the file, such as its resource map name, version, and resource counts, rather than the individual resources. | + +Use `/OutputOptions(oo)` for finer control over what's emitted, and `/ExternalSchema(es)` when you're dumping a schema-free resource pack. For the full set of options, see [MakePri.exe command-line options](makepri-exe-command-options.md#dump-command). + +You can also dump a PRI file programmatically by calling the [MrmDumpPriFile](/windows/desktop/menurc/pri-indexing-reference) function; for a walkthrough, see [Scenario 1: Generate a PRI file from string resources and asset files](pri-apis-scenario-1.md). + +To read a PRI file's contents at run-time instead, use the resource APIs. + +- For a UWP app, use [ResourceManager](/uwp/api/windows.applicationmodel.resources.core.resourcemanager) and the other types in the [Windows.ApplicationModel.Resources.Core](/uwp/api/windows.applicationmodel.resources.core) namespace, which let you enumerate resource maps, named resources, and candidates. See [Resource Management System](resource-management-system.md). +- For an app that uses the Windows App SDK, use MRT Core. See [Manage resources with MRT Core](/windows/apps/windows-app-sdk/mrtcore/mrtcore-overview). + +## Related topics + +* [Resource Management System](resource-management-system.md) +* [How the Resource Management System matches and chooses resources](how-rms-matches-and-chooses-resources.md) +* [Compile resources manually with MakePri.exe](compile-resources-manually-with-makepri.md) +* [MakePri.exe command-line options](makepri-exe-command-options.md) +* [Package resource indexing (PRI) APIs and custom build systems](pri-apis-custom-build-systems.md) +* [Package resource indexing (PRI) reference](/windows/desktop/menurc/pri-indexing-reference) +* [URI schemes](uri-schemes.md) diff --git a/uwp/app-resources/resource-management-system.md b/uwp/app-resources/resource-management-system.md index ae1dc54e80..596d1156b0 100644 --- a/uwp/app-resources/resource-management-system.md +++ b/uwp/app-resources/resource-management-system.md @@ -19,6 +19,7 @@ Every app package should contain a binary index of the resources in the app. Thi - PRI files can be created and dumped with the tool [MakePRI.exe](compile-resources-manually-with-makepri.md). - For typical app development you won't need MakePRI.exe because it's already integrated into the Visual Studio compile workflow. And Visual Studio supports editing PRI files in a dedicated UI. However, your localizers and the tools they use might rely upon MakePRI.exe. - Each PRI file contains a named collection of resources, referred to as a resource map. When a PRI file from a package is loaded, the resource map name is verified to match the package identity name. +- For a description of what a PRI file contains, and how to inspect one, see [Package resource index (PRI) file format](pri-file-format.md). - PRI files contain only data, so they don't use the portable executable (PE) format. They are specifically designed to be data-only as the resource format for Windows. They replace resources contained within DLLs in the Win32 app model. ## UWP API access to app resources @@ -59,5 +60,6 @@ Resource candidates are chosen based on a particular [**ResourceContext**](/uwp/ * [ResourceContext](/uwp/api/windows.applicationmodel.resources.core.resourcecontext?branch=live) ## Related topics +* [Package resource index (PRI) file format](pri-file-format.md) * [Localize strings in your UI and app package manifest](localize-strings-ui-manifest.md) * [Load images and assets tailored for scale, theme, high contrast, and others](images-tailored-for-scale-theme-contrast.md) diff --git a/uwp/develop/toc.yml b/uwp/develop/toc.yml index b8c831d3f1..19c92e1004 100644 --- a/uwp/develop/toc.yml +++ b/uwp/develop/toc.yml @@ -119,6 +119,8 @@ items: items: - name: Scenario 1 (PRI APIs) href: ../app-resources/pri-apis-scenario-1.md + - name: Package resource index (PRI) file format + href: ../app-resources/pri-file-format.md - name: Compile resources manually with MakePri.exe href: ../app-resources/compile-resources-manually-with-makepri.md - name: MakePri.exe command-line options