Création de package à l’aide de la disposition de mise en packagePackage creation with the packaging layout

Grâce à l'introduction aux packages d'actifs, les développeurs disposent désormais des outils nécessaires à la génération de davantage de packages ainsi que d'autres types de packages.With the introduction of asset packages, developers now have the tools to build more packages in addition to more package types. À mesure qu'une application devient plus vaste et plus complexe, elle sera souvent composée de davantage de packages. La gestion de ces packages devient alors plus difficile (en particulier si vous générez en dehors de Visual Studio en utilisant des fichiers de mappage).As an app gets larger and more complex, it will often be comprised of more packages, and the difficulty of managing these packages will increase (especially if you are building outside of Visual Studio and using mapping files). Pour simplifier la gestion de la structure de package d'une application, vous pouvez utiliser la disposition de mise en package prise en charge par MakeAppx.exe.To simplify the management of an app’s packaging structure, you can use the packaging layout supported by MakeAppx.exe.

La disposition de mise en package constitue un unique document XML décrivant la structure de mise en package de l'application.The packaging layout is a single XML document that describes packaging structure of the app. Il spécifie les ensembles d'une application (principaux et facultatifs), les packages contenus dans les ensembles ainsi que les fichiers contenus dans les packages.It specifies the bundles of an app (primary and optional), the packages in the bundles, and the files in the packages. Les fichiers peuvent être sélectionnés depuis différents emplacements de dossiers, de disques ou de réseau.Files can be selected from different folders, drives, and network locations. Les caractères génériques peuvent être utilisés pour sélectionner ou exclure des fichiers.Wildcards can be used to select or exclude files.

Une fois la disposition de mise en package d'une application configurée, MakeAppx.exe est utilisé pour créer tous les packages pour une application dans un appel de ligne de commande unique.After the packaging layout for an app has been set up, it's used with MakeAppx.exe to create all of the packages for an app in a single command line call. La disposition de mise en package peut être modifiée pour altérer la structure de package afin qu'elle corresponde à vos besoins de déploiement.The packaging layout can be edited to alter the package structure to fit your deployment needs.

Exemple de disposition de mise en package simpleSimple packaging layout example

Voici un exemple de disposition de mise en package simple :Here's an example of what a simple packaging layout looks like:

<PackagingLayout xmlns="http://schemas.microsoft.com/appx/makeappx/2017">
  <PackageFamily ID="MyGame" FlatBundle="true" ManifestPath="C:\mygame\appxmanifest.xml" ResourceManager="false">
    
    <!-- x64 code package-->
    <Package ID="x64" ProcessorArchitecture="x64">
      <Files>
        <File DestinationPath="*" SourcePath="C:\mygame\*"/>
        <File ExcludePath="*C:\mygame\*.txt"/>
      </Files>
    </Package>
    
    <!-- Media asset package -->
    <AssetPackage ID="Media" AllowExecution="false">
      <Files>
        <File DestinationPath="Media\**" SourcePath="C:\mygame\media\**"/>
      </Files>
    </AssetPackage>

  </PackageFamily>
</PackagingLayout>

Décomposons cet exemple pour comprendre son fonctionnementLet's break this example down to understand how it works.

PackageFamilyPackageFamily

Cette disposition de Packaging crée un fichier de bundle d’applications plat unique avec un package d’architecture x64 et un package de ressources « média ».This packaging layout will create a single flat app bundle file with an x64 architecture package and a “Media” asset package.

L'élément PackageFamily est utilisé pour définir un ensemble d'applications.The PackageFamily element is used to define an app bundle. Vous devez utiliser l'attribut ManifestPath pour fournir un élément AppxManifest à l'ensemble. L'élément AppxManifest doit correspondre à l'élément AppxManifest pour le package d'architecture de l'ensemble.You must use the ManifestPath attribute to provide an AppxManifest for the bundle, the AppxManifest should correspond to the AppxManifest for the architecture package of the bundle. L'attribut ID doit également être fourni.The ID attribute must also be provided. Cet élément est utilisé avec MakeAppx.exe lors de la création de package. Ainsi, vous pouvez créer uniquement ce package si vous le souhaitez, il s'agira alors du nom de fichier pour le package obtenu.This is used with MakeAppx.exe during package creation so that you can create just this package if you want to, and this will be the file name of the resulting package. L'attribut FlatBundle est utilisé pour décrire le type d'ensemble que vous souhaitez créer, l'attribut true pour un ensemble plat (vous trouverez plus d'informations ici) et l'attribut false pour un ensemble classique.The FlatBundle attribute is used to describe what type of bundle you want to create, true for a flat bundle (which you can read more about here), and false for a classic bundle. L'attribut ResourceManager est utilisé pour spécifier si les packages de ressources dans cet ensemble utiliseront MRT afin d'accéder aux fichiers.The ResourceManager attribute is used to specify if the resource packages within this bundle will use MRT in order to access the files. La valeur par défaut est true, mais à compter de la version 1803 de Windows 10, il n'est pas encore prêt. L'attribut doit donc être défini sur false.This is by default true, but as of Windows 10, version 1803, this is not yet ready, so this attribute must be set to false.

Package et AssetPackagePackage and AssetPackage

Dans l'élément PackageFamily, les packages contenus ou référencés par l'ensemble d'applications sont définis.Within the PackageFamily, the packages that the app bundle contains or references are defined. Ici, le package d'architecture (également appelé package principal) est défini avec l'élément Package et le package d'actifs est défini avec l'élément AssetPackage.Here, the architecture package (also called the main package) is defined with the Package element, and the asset package is defined with the AssetPackage element. Le package d'architecture doit spécifier l'architecture pour laquelle le package est destiné : « x64 », « x86 » « arm » « neutral ».The architecture package must specify which architecture the package is for, either “x64”, “x86”, “arm”, or “neutral”. Vous pouvez également fournir directement (facultatif) un élément AppxManifest spécifiquement pour ce package à l'aide de l'attribut ManifestPath à nouveau.You can also (optionally) directly provide an AppxManifest specifically for this package by using the ManifestPath attribute again. Si aucun élément AppxManifest n’est fourni, il sera automatiquement généré à partir de l'élément AppxManifest fourni pour l'élément PackageFamily.If an AppxManifest is not provided, one will be automatically generated from the AppxManifest provided for the PackageFamily.

Les éléments par défaut et AppxManifest seront générés pour chaque package à l'intérieur de l'ensemble.By default and AppxManifest will be generated for every package within the bundle. Pour le package d'actifs, vous pouvez également définir l'attribut AllowExecution.For the asset package, you can also set the AllowExecution attribute. La définition de la valeur false (par défaut) permet de réduire le délai de publication de votre application. En effet, pour les packages n'ayant pas besoin d'être exécutés l'analyse des virus ne bloquera pas le processus de publication (vous trouverez pus d'informations à ce sujet en consultant Introduction aux packages d'actifs).Setting this to false (the default), will help decrease the publishing time for your app since packages that don’t need to execute won’t have their virus scan block the publishing process (you can learn more about this at Introduction to asset packages).

FichiersFiles

Dans chaque définition de package, vous pouvez utiliser l'élément Fichier afin de sélectionner les fichiers à inclure à ce package.Within each package definition, you can use the File element to select files to be included in this package. L'attribut SourcePath définit l'emplacement local des fichiers.The SourcePath attribute is where the files are locally. Vous pouvez sélectionner les fichiers à partir de différents dossiers (en fournissant les chemins relatifs), de différents disques (en fournissant les chemins absolus) et même à partir de réseaux partagés (en fournissant un chemin semblable à \\myshare\myapp\*).You can select files from different folders (by providing relative paths), different drives (by providing absolute paths), or even network shares (by providing something like \\myshare\myapp\*). Le DestinationPath est la destination vers laquelle les fichiers sont transférés dans le package, en fonction de la racine du package.The DestinationPath is where the files will end up within the package, relative to the package root. ExcludePath peut être utilisé (au lieu des deux autres attributs) pour sélectionner les fichiers à exclure des fichiers sélectionnés par les autres éléments Fichier dans les attributs SourcePath au sein du même package.ExcludePath can be used (instead of the other two attributes) to select files to be excluded from the ones selected by other File elements’ SourcePath attributes within the same package.

Chaque élément Fichier peut être utilisé pour sélectionner plusieurs fichiers à l’aide de caractères génériques.Each File element can be used to select multiple files by using wildcards. En règle générale, un seul caractère générique (*) peut être utilisé indéfiniment dans le chemin.In general, single wildcard (*) can be used anywhere within the path any number of times. Toutefois, un même caractère générique correspondra uniquement aux fichiers dans un dossier et non dans les sous-dossiers.However, a single wildcard will only match the files within a folder and not any subfolders. Par exemple, C:\MyGame\*\* peut être utilisé dans le SourcePath pour sélectionner les fichiers C:\MyGame\Audios\UI.mp3 et C:\MyGame\Videos\intro.mp4, mais il le peut pas sélectionner C:\MyGame\Audios\Level1\warp.mp3.For example, C:\MyGame\*\* can be used in the SourcePath to select the files C:\MyGame\Audios\UI.mp3 and C:\MyGame\Videos\intro.mp4, but it cannot select C:\MyGame\Audios\Level1\warp.mp3. Le caractère générique double (**) peut également être utilisé dans les noms de dossier et de fichier pour correspondre à tout élément de manière récursive (mais il ne peut pas se trouver à côté des noms partiels).The double wildcard (**) can also be used in place of folder or file names to match anything recursively (but it cannot be next to partial names). Par exemple, C:\MyGame\**\Level1\** peut sélectionner C:\MyGame\Audios\Level1\warp.mp3 et C:\MyGame\Videos\Bonus\Level1\DLC1\intro.mp4.For example, C:\MyGame\**\Level1\** can select C:\MyGame\Audios\Level1\warp.mp3 and C:\MyGame\Videos\Bonus\Level1\DLC1\intro.mp4. Les caractères génériques peuvent également être utilisés pour modifier directement les noms de fichier dans le cadre du processus de mise en package si les caractères génériques sont utilisés à différents endroits entre la source et la destination.Wildcards can also be used to directly change file names as part of the packaging process if the wildcards are used in different places between the source and destination. Par exemple, le chemin C:\MyGame\Audios\* pour SourcePath et le chemin Sound\copy_* pour DestinationPath peuvent sélectionner C:\MyGame\Audios\UI.mp3 et le faire apparaître dans le package sous Sound\copy_UI.mp3.For example, having C:\MyGame\Audios\* for SourcePath and Sound\copy_* for DestinationPath can select C:\MyGame\Audios\UI.mp3 and have it appear in the package as Sound\copy_UI.mp3. En général, le nombre de caractères génériques uniques et doubles doivent être les mêmes pour SourcePath et DestinationPath d'un même élément Fichier.In general, the number of single wildcards and double wildcards must be the same for the SourcePath and DestinationPath of a single File element.

Exemple de disposition de mise en package avancéeAdvanced packaging layout example

Voici un exemple de disposition de mise en package plus compliquée :Here's an example of a more complicated packaging layout:

<PackagingLayout xmlns="http://schemas.microsoft.com/appx/makeappx/2017">
  <!-- Main game -->
  <PackageFamily ID="MyGame" FlatBundle="true" ManifestPath="C:\mygame\appxmanifest.xml" ResourceManager="false">
    
    <!-- x64 code package-->
    <Package ID="x64" ProcessorArchitecture="x64">
      <Files>
        <File DestinationPath="*" SourcePath="C:\mygame\*"/>
        <File ExcludePath="*C:\mygame\*.txt"/>
      </Files>
    </Package>

    <!-- Media asset package -->
    <AssetPackage ID="Media" AllowExecution="false">
      <Files>
        <File DestinationPath="Media\**" SourcePath="C:\mygame\media\**"/>
      </Files>
    </AssetPackage>
    
    <!-- English resource package -->
    <ResourcePackage ID="en">
      <Files>
        <File DestinationPath="english\**" SourcePath="C:\mygame\english\**"/>
      </Files>
      <Resources Default="true">
        <Resource Language="en"/>
      </Resources>
    </ResourcePackage>

    <!-- French resource package -->
    <ResourcePackage ID="fr">
      <Files>
        <File DestinationPath="french\**" SourcePath="C:\mygame\french\**"/>
      </Files>
      <Resources>
        <Resource Language="fr"/>
      </Resources>
    </ResourcePackage>
  </PackageFamily>

  <!-- DLC in the related set -->
  <PackageFamily ID="DLC" Optional="true" ManifestPath="C:\DLC\appxmanifest.xml">
    <Package ID="DLC.x86" Architecture="x86">
      <Files>
        <File DestinationPath="**" SourcePath="C:\DLC\**"/>
      </Files>
    </Package>
  </PackageFamily>

  <!-- DLC not part of the related set -->
  <PackageFamily ID="Themes" Optional="true" RelatedSet="false" ManifestPath="C:\themes\appxmanifest.xml">
    <Package ID="Themes.main" Architecture="neutral">
      <Files>
        <File DestinationPath="**" SourcePath="C:\themes\**"/>
      </Files>
    </Package>
  </PackageFamily>

  <!-- Existing packages that need to be included/referenced in the bundle -->
  <PrebuiltPackage Path="C:\prebuilt\DLC2.appxbundle" />

</PackagingLayout>

Cet exemple diffère de l'exemple simple avec l'ajout des éléments ResourcePackage et Facultatif.This example differs from the simple example with the addition of ResourcePackage and Optional elements.

Les packages de ressources peuvent être spécifiés dans l'élément ResourcePackage.Resource packages can be specified with the ResourcePackage element. Dans le ResourcePackage, l'élément Ressources doit être utilisé pour spécifier les qualificateurs de ressource du pack de ressources.Within the ResourcePackage, the Resources element must be used to specify the resource qualifiers of the resource pack. Les qualificateurs de ressource sont les ressources prises en charge par le pack de ressources. Ici, nous visualisons deux packs de ressources qui contiennent chacun les fichiers spécifiques en anglais et en français.The resource qualifiers are the resources that are supported by the resource pack, here, we can see that there are two resource packs defined and they each contain the English and French specific files. Un pack de ressources peut disposer de plus d'un qualificateur. Il suffit d'ajouter un autre élément Ressource dans Ressources.A resource pack can have more than one qualifier, this can be done by adding another Resource element within Resources. Une ressource par défaut pour la dimension de ressource doit également être spécifiée si la dimension existe (les dimensions sont la langue, l'échelle, l'élément dxfl).A default resource for the resource dimension must also be specified if the dimension exists (dimensions being language, scale, dxfl). Dans le cas présent, vous voyons que l'anglais est la langue par défaut. Donc, les utilisateurs n'ayant pas nécessairement de langue de système en français auront accès au téléchargement de secours du pack de ressources en anglais et de l'affichage en anglais.Here, we can see that English is the default language, meaning that for users that does not have a system language of French set, they will fallback to downloading the English resource pack and display in English.

Les packages facultatifs ont leurs propres noms de famille de package distincts et doivent être définis avec des éléments PackageFamily tout e spécifiant l'attribut Facultatif sur true.Optional packages each have their own distinct package family names and must be defined with PackageFamily elements, while specifying the Optional attribute to be true. L'attribut RelatedSet est utilisé pour spécifié si le package facultatif se trouve dans l'ensemble connexe (il doit l'être par défaut), peut importe si le package facultatif doit être mis à jour avec le package principal.The RelatedSet attribute is used to specify whether the optional package is within the related set (by default this is true) – whether the optional package should be updated with the primary package.

L’élément PrebuiltPackage est utilisé pour ajouter des packages qui ne sont pas définis dans la disposition d’empaquetage à inclure ou à référencer dans le ou les fichiers de l’ensemble d’applications à générer.The PrebuiltPackage element is used to add packages that are not defined in the packaging layout to be included or referenced in the app bundle file(s) to be built. Dans ce cas, un autre package DLC facultatif est inclus ici afin que le fichier de bundle d’applications principal puisse le référencer et faire partie de l’ensemble associé.In this case, another DLC optional package is being included here so that the primary app bundle file can reference it and have it be part of the related set.

Générer des packages d'application avec une disposition de mise en package et l'outil MakeAppx.exeBuild app packages with a packaging layout and MakeAppx.exe

Une fois la disposition de mise en package préparée pour votre application, vous pouvez démarrer la génération des packages pour votre application à l'aide de l'outil MakeAppx.exe.Once you have the packaging layout for your app, you can start using MakeAppx.exe to build the packages of your app. Pour générer tous les packages définis dans la disposition de mise en package, utilisez la commande :To build all of the packages defined in the packaging layout, use the command:

MakeAppx.exe build /f PackagingLayout.xml /op OutputPackages\

Néanmoins, si vous mettez à jour votre application et que certains packages ne contiennent aucun des fichiers modifiés, vous pouvez générer uniquement les package ayant été modifiés.But, if you are updating your app and some packages don't contain any changed files, you can build only the packages that have changed. Avec l'utilisation de l'exemple de disposition de mise en package simple sur cette page et la génération du package d'architecture x64, votre commande doit être semblable à ceci :Using the simple packaging layout example on this page and building the x64 architecture package, this is what our command would look like:

MakeAppx.exe build /f PackagingLayout.xml /id "x64" /ip PreviousVersion\ /op OutputPackages\ /iv

L'indicateur /id peut être utilisé pour sélectionner les packages à générer à partir de la disposition de mise en package. Il correspond à l'attribut ID de la disposition.The /id flag can be used to select the packages to be built from the packaging layout, corresponding to the ID attribute in the layout. L'attribut /ip est utilisé pour indiquer l'emplacement de la version précédente des packages dans ce cas.The /ip is used to indicate where the previous version of the packages are in this case. La version précédente doit être fournie, car le fichier de bundle d’applications doit toujours faire référence à la version précédente du package multimédia .The previous version must be provided because the app bundle file still needs to reference the previous version of the Media package. L'indicateur /iv est utilisé pour incrémenter automatiquement la version des packages en cours de génération (au lieu de modifier la version dans l'élément AppxManifest).The /iv flag is used to automatically increment the version of the packages being built (instead of changing the version in the AppxManifest). Sinon, les commutateurs /pv et /bv peuvent être utilisés pour fournir directement une version de package (pour tous les packages à créer) et une version d'ensemble (pour tous les ensembles à créer) respectivement.Alternatively, the switches /pv and /bv can be used to directly provide a package version (for all packages to be created) and a bundle version (for all bundles to be created), respectively. À l'aide de l'exemple de disposition de mise en package avancée de cette page, si vous souhaitez uniquement générer l'ensemble facultatif Themes et le package d'application Themes.main auquel il fait référence, vous pourriez utiliser cette commande :Using the advanced packaging layout example on this page, if you want to only build the Themes optional bundle and the Themes.main app package that it references, you would use this command:

MakeAppx.exe build /f PackagingLayout.xml /id "Themes" /op OutputPackages\ /bc /nbp

L'indicateur /bc est utilisé pour dénoter que les descendants de l'ensemble Themes doivent également être généré (dans ce cas, Themes.main sera généré).The /bc flag is used to denote that the children of the Themes bundle should also be built (in this case Themes.main will be built). L'indicateur /nbp est utilisé pour dénoter que les parents de l'ensemble Themes ne doivent pas être générés.The /nbp flag is used to denote that the parent of the Themes bundle should not be built. Les parents de l'ensemble Themes, ensemble d'applications facultatif, constituent l'ensemble d'applications principal : MyGame.The parent of Themes, which is an optional app bundle, is the primary app bundle: MyGame. De manière habituelle pour le package facultatif d'un ensemble connexe, l'ensemble d'applications principal doit également être généré pour que le package facultatif puisse être installé. En effet, le package facultatif est également référencé dans l'ensemble d'applications principal lorsqu'il se trouve dans un ensemble connexe (la garantie de version entre le package principal et le package facultatif).Usually for an optional package in a related set, the primary app bundle must also be built for the optional package to be installable, since the optional package is also referenced in the primary app bundle when it is in a related set (to guarantee versioning between the primary and the optional packages). La relation parent-descendant entre les packages est illustrée dans le diagramme suivant :The parent child relationship between packages is illustrated in the following diagram:

Diagramme de disposition de mise en package