Création de packages facultatifs et d’ensembles associés

  • Article

Les packages facultatifs ont un contenu qui peut être inclus dans un package principal. Ces éléments sont utiles pour le contenu téléchargeable (DLC), en divisant une grande application pour les restrictions de taille ou pour l’expédition de tout contenu supplémentaire distinct de votre application d’origine. Pour plus d’informations sur les packages facultatifs, consultez le billet de blog : Étendre votre application à l’aide de packages facultatifs.

Les jeux associés sont une extension de packages facultatifs. Les ensembles associés vous permettent d’appliquer un ensemble strict de versions sur les packages principaux et facultatifs. Les jeux associés peuvent avoir différents éditeurs de l’application principale s’il est déployé en dehors du Windows Store. Pour plus d’informations sur les ensembles associés, consultez billet de blog : Outils pour créer un ensemble associé.

Packages facultatifs et ensembles associés s’exécutent tous à l’intérieur du conteneur MSIX de l’application principale.

Prérequis

  • Visual Studio 2019 ou Visual Studio 2017 (version 15.1 ou ultérieure)
  • Windows 10, version 1703 ou ultérieure
  • Kit de développement logiciel (SDK) Windows 10, version 1703 ou ultérieure

Pour obtenir tous les derniers outils de développement, consultez Téléchargements et outils pour Windows 10.

Remarque

Pour soumettre une application qui utilise des packages facultatifs et/ou des ensembles associés au Microsoft Store, vous aurez besoin d’autorisation. Les packages facultatifs et les ensembles associés peuvent être utilisés pour les applications métier ou d’entreprise sans autorisation de l’Espace partenaires s’ils ne sont pas soumis à Windows Store. Pour obtenir l’autorisation de soumettre une application utilisant des packages facultatifs et des jeux connexes, consultez le Support technique pour les développeurs Windows.

Exemple de code

Pendant que vous lisez cet article, nous vous recommandons de suivre l’exemple de code de package facultatif sur GitHub pour comprendre comment les packages facultatifs et les ensembles associés fonctionnent dans Visual Studio.

Packages facultatifs

Pour créer un package facultatif dans Visual Studio, vous devez :

  1. Vérifiez que la version minimale de la plateforme cible de votre application est définie sur : 10.0.15063.0 ou version ultérieure.
  2. À partir de votre projet de package principal, ouvrez le Package.appxmanifest fichier. Accédez à l’onglet « Empaquetage » et notez le nom de votre famille de packages, qui est tout avant le caractère « _ ».
  3. Dans votre projet de package facultatif, cliquez avec le bouton droit sur l’éditeurPackage.appxmanifestOpen with > XML (Text).
  4. Recherchez l’élément <Dependencies> dans le fichier. Ajoutez ce qui suit et remplacez [MainPackageDependency] le nom de votre famille de packages à l’étape 2. Cela spécifie que votre package facultatif dépend de votre package principal. 
    <uap3:MainPackageDependency Name="[MainPackageDependency]"/>

Remarque

Si vous souhaitez créer un package facultatif à partir d’un autre éditeur, vous devez spécifier l’éditeur de l’application principale s’ils sont différents. Comme si <uap4 :MainPackageDependency Name="Main_app » Publisher="CN=Contoso... » />. Cela ne fonctionnera pas si vous publiez sur le Windows Store.

Une fois que vos dépendances de package sont configurées entre les étapes 1 et 4, vous pouvez continuer à développer comme vous le feriez normalement. Pour plus d’informations, consultez le billet de blog : Créer votre premier package facultatif.

Visual Studio peut être configuré pour redéployer votre package principal chaque fois que vous déployez un package facultatif. Pour définir la dépendance de build dans Visual Studio, vous devez :

  1. Cliquez avec le bouton droit sur le projet de package facultatif, puis sélectionnez Dépendances du projet De dépendances > ...
  2. Vérifiez le projet de package principal et sélectionnez « OK ».

À présent, chaque fois que vous entrez F5 ou générez un projet de package facultatif, Visual Studio génère d’abord le projet de package principal. Cela garantit que votre projet principal et vos projets facultatifs sont synchronisés.

Un ensemble associé se compose d’un package principal et d’un package facultatif étroitement couplé via des métadonnées spécifiées dans le fichier .appxbundle ou .msixbundle du package principal. Ces métadonnées relient le package principal au package facultatif (en utilisant le nom du fichier .appxbundle + version) et le package facultatif au package principal (à l’aide du nom indépendant de la version). Visual Studio vous aide à obtenir les métadonnées correctes dans vos fichiers.

Le contrôle de version des packages d’un ensemble associé est synchronisé d’une manière qui n’autorise pas l’utilisation de la dernière version d’un package tant que tous les packages de jeu associés (spécifiés par version dans le package principal) ne sont pas installés. Les packages sont gérés indépendamment, mais les packages spécifiés dans l’ensemble peuvent ne pas être utilisés tant que tous les packages n’ont pas été mis à jour. Pour plus d’informations sur les ensembles associés, consultez billet de blog : Outils pour créer un ensemble associé.

Pour configurer la solution de votre application pour les jeux associés, procédez comme suit :

  1. Cliquez avec le bouton droit sur le projet de package principal, sélectionnez Ajouter > un nouvel élément...
  2. Dans la fenêtre, recherchez les modèles installés pour .txt » et ajoutez un nouveau fichier texte.

    Important

    Le nouveau fichier texte doit être nommé : Bundle.Mapping.txt.

  3. Dans le Bundle.Mapping.txt fichier, entrez la chaîne « [OptionalProjects] » suivie des chemins relatifs de vos projets de package facultatifs. Voici un exemple Bundle.Mapping.txt de fichier : 
    [OptionalProjects]
"..\ActivatableOptionalPackage1\ActivatableOptionalPackage1.vcxproj"
"..\ActivatableOptionalPackage2\ActivatableOptionalPackage2.vcxproj"

Lorsque votre solution est configurée de cette façon, Visual Studio crée un manifeste de bundle nommé AppxBundleManifest.xml pour le package principal avec toutes les métadonnées requises pour les jeux associés.

Notez que, comme les packages facultatifs, un Bundle.Mapping.txt fichier pour les ensembles associés fonctionne uniquement sur Windows 10, version 1703 ou ultérieure. En outre, la version minimale de la plateforme cible de votre application doit être définie sur 10.0.15063.0 ou version ultérieure.

Suppression de packages facultatifs

Les utilisateurs peuvent accéder à leur application Paramètres et supprimer les packages facultatifs. De même, les développeurs peuvent utiliser RemoveOptionalPackageAsync pour supprimer une liste de packages facultatifs.

PackageCatalog catalog = PackageCatalog.OpenForCurrentPackage();
List<string> optionalList = new List<string>();
optionalList.Add("FabrikamAgeAnalysis_kwpnjs8c36mz0");
    
// Warn user that application will be restarted. 
var result = await catalog.RemoveOptionalPackagesAsync(optionalList);
if (result.ExtendedError != null)
{
    throw removalResult.ExtendedError;
}

Remarque

Dans le cas d’un ensemble associé, la plateforme doit redémarrer l’application principale pour finaliser la suppression afin d’éviter les situations où l’application a du contenu chargé du package en cours de suppression. Les applications doivent informer les utilisateurs que l’application doit être redémarrée avant que l’application appelle l’API.

Si le package facultatif est le contenu uniquement, le développeur doit indiquer explicitement à la plateforme que le package sur le point de supprimer n’est pas utilisé par l’application avant que le développeur ne supprime le package facultatif. Cela permet également au développeur de supprimer le package sans redémarrage.

Problèmes connus

Le débogage d’un projet facultatif d’ensemble associé n’est actuellement pas pris en charge dans Visual Studio. Pour contourner ce problème, vous pouvez déployer et lancer l’activation (Ctrl + F5) et attacher manuellement le débogueur à un processus. Pour attacher le débogueur, accédez au menu « Déboguer » dans Visual Studio, sélectionnez « Attacher au processus... », puis attachez le débogueur au processus d’application principal.