Skip to content

Commit a2a66fa

Browse files
authored
Update build-resources-into-app-package.md
1 parent a82c0e9 commit a2a66fa

File tree

1 file changed

+10
-10
lines changed

1 file changed

+10
-10
lines changed

uwp/app-resources/build-resources-into-app-package.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,17 @@ keywords: windows 10, uwp, resource, image, asset, MRT, qualifier
99
ms.localizationpriority: medium
1010
---
1111

12-
# Build resources into your app package, instead of into a resource pack
12+
# Build resources into your app package instead of into a resource pack
1313

14-
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 (or resource packs). This topic explains how to do that.
14+
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 (or resource packs). This topic explains how to do that.
1515

16-
By default when you build an [app bundle (.appxbundle)](/windows/msix/package/packaging-uwp-apps), only your default resources for language, scale, and DirectX feature level are built into the app package. Your translated resources—and your resources tailored for non-default scales and/or DirectX feature levels—are built into resource packages and they are only downloaded onto devices that need them. If a customer is buying your app from the Microsoft Store using a device with a language preference set to Spanish, then only your app plus the Spanish resource package are downloaded and installed. If that same user later changes their language preference to French in **Settings**, then your app's French resource package is downloaded and installed. Similar things happen with your resources qualified for scale and for DirectX feature level. For the majority of apps, this behavior constitutes a valuable efficiency, and it's exactly what you and the customer *want* to happen.
16+
By default, when you build an [app bundle (.appxbundle)](/windows/msix/package/packaging-uwp-apps), only your default resources for language, scale, and DirectX feature level are built into the app package. Your translated resources—and your resources tailored for non-default scales and/or DirectX feature levels—are built into resource packages, and they are only downloaded onto devices that need them. If a customer is buying your app from the Microsoft Store using a device with a language preference set to Spanish, then only your app plus the Spanish resource package are downloaded and installed. If that same user later changes their language preference to French in **Settings**, then your app's French resource package is downloaded and installed. Similar things happen with your resources qualified for scale and for DirectX feature level. For the majority of apps, this behavior constitutes a valuable efficiency, and it's what you and the customer *want* to happen.
1717

1818
But if your app allows the user to change the language on the fly from within the app (instead of via **Settings**), then that default behavior is not appropriate. You actually want all of your language resources to be unconditionally downloaded and installed along with the app one time, and then remain on the device. You want to build all of those resources into your app package instead of into separate resource packages.
1919

2020
**Note** Including resources in an app package essentially increases the size of the app. That's why it's only worth doing if the nature of the app demands it. If not, then you don't need to do anything except build a regular app bundle as usual.
2121

22-
You can configure Visual Studio to build resources into your app package in one of two ways. You can either add a configuration file to your project, or you can edit your project file directly. Use whichever of these options you're most comfortable with, or whichever works best with your build system.
22+
You can configure Visual Studio to build resources into your app package in one of two ways. You can either add a configuration file to your project or you can edit your project file directly. Use whichever of these options you're most comfortable with or whichever works best with your build system.
2323

2424
## Option 1. Use priconfig.packaging.xml to build resources into your app package
2525

@@ -33,7 +33,7 @@ You can configure Visual Studio to build resources into your app package in one
3333
<autoResourcePackage qualifier="DXFeatureLevel" />
3434
</packaging>
3535
```
36-
4. Each `<autoResourcePackage>` element tells Visual Studio to automatically split the resources for the given qualifier name out into separate resource packages. This is called *auto-splitting*. With the file contents you have so far, you haven't actually changed Visual Studio's behavior. In other words, Visual Studio *already behaved as if* this file were present with these contents, because these are the defaults. If you don't want Visual Studio to auto-split on a qualifier name then delete that `<autoResourcePackage>` element from the file. Here's how the file would look if you wanted all of your language resources to be built into the app package instead of being auto-split out into separate resource packages.
36+
4. Each `<autoResourcePackage>` element tells Visual Studio to automatically split the resources for the given qualifier name out into separate resource packages. This is called *auto-splitting*. With the file contents you have so far, you haven't actually changed Visual Studio's behavior. In other words, Visual Studio *already behaved as if* this file were present with these contents because these are the defaults. If you don't want Visual Studio to auto-split on a qualifier name, then delete that `<autoResourcePackage>` element from the file. Here's how the file would look if you wanted all of your language resources to be built into the app package instead of being auto-split out into separate resource packages.
3737
```xml
3838
<packaging>
3939
<autoResourcePackage qualifier="Scale" />
@@ -44,7 +44,7 @@ You can configure Visual Studio to build resources into your app package in one
4444

4545
To confirm that your auto-split choices are being taken into account, look for the file `<ProjectFolder>\obj\<ReleaseConfiguration folder>\split.priconfig.xml` and confirm that its contents match your choices. If they do, then you have successfully configured Visual Studio to build the resources of your choice into the app package.
4646

47-
There is one final step that you need to do. **But only if you deleted the `Language` qualifier name**. You need to specify the union of all of your app's supported language as your app's default for language. For details, see [Specify the default resources that your app uses](specify-default-resources-installed.md). This is what your `priconfig.default.xml` would contain if you were including resources for English, Spanish, and French in your app package.
47+
There is one final step that you need to do. **But only if you deleted the `Language` qualifier name**. You need to specify the union of all of your app's supported languages as your app's default language. For details, see [Specify the default resources that your app uses](specify-default-resources-installed.md). This is what your `priconfig.default.xml` would contain if you were including resources for English, Spanish, and French in your app package.
4848

4949
```xml
5050
<default>
@@ -65,27 +65,27 @@ If you name your file `priconfig.packaging.xml`, then Visual Studio will recogni
6565
<AppxPriConfigXmlPackagingSnippetPath>FILE-PATH-AND-NAME</AppxPriConfigXmlPackagingSnippetPath>
6666
```
6767

68-
Replace `FILE-PATH-AND-NAME` with the path to, and name of, your file.
68+
Replace `FILE-PATH-AND-NAME` with the path to and name of your file.
6969

7070
## Option 2. Use your project file to build resources into your app package
7171

72-
This is an alternative to Option 1. Once you understand how Option 1 works, you can choose to do Option 2 instead, if that suits your development and/or build workflow better.
72+
This is an alternative to Option 1. Once you understand how Option 1 works, you can choose to do Option 2 instead if that suits your development and/or build workflow better.
7373

7474
In your project file, between the opening and closing tags of the first `<PropertyGroup>` element, add this XML.
7575

7676
```xml
7777
<AppxBundleAutoResourcePackageQualifiers>Language|Scale|DXFeatureLevel</AppxBundleAutoResourcePackageQualifiers>
7878
```
7979

80-
Here's how that looks after you've delete the first qualifier name.
80+
Here's how that looks after you've deleted the first qualifier name.
8181

8282
```xml
8383
<AppxBundleAutoResourcePackageQualifiers>Scale|DXFeatureLevel</AppxBundleAutoResourcePackageQualifiers>
8484
```
8585

8686
Save and close, and rebuild your project.
8787

88-
There is one final step that you need to do. **But only if you deleted the `Language` qualifier name**. You need to specify the union of all of your app's supported language as your app's default for language. For details, see [Specify the default resources that your app uses](specify-default-resources-installed.md). This is what your project file would contain if you were including resources for English, Spanish, and French in your app package.
88+
There is one final step that you need to do. **But only if you deleted the `Language` qualifier name**. You need to specify the union of all of your app's supported languages as your app's default language. For details, see [Specify the default resources that your app uses](specify-default-resources-installed.md). This is what your project file would contain if you included resources for English, Spanish, and French in your app package.
8989

9090
```xml
9191
<AppxDefaultResourceQualifiers>Language=en;es;fr</AppxDefaultResourceQualifiers>

0 commit comments

Comments
 (0)