guide de déploiement SDK d'application Windows pour les applications empaquetées dépendantes de l’infrastructure

Cet article fournit des conseils sur le déploiement d’applications empaquetées dépendantes de l’infrastructure (voir Qu’est-ce que MSIX ?) qui utilisent le SDK d'application Windows. La rubrique équivalente pour les autres options d’empaquetage dépendant du framework est Guide de déploiement du SDK d'application Windows pour les applications dépendantes du framework empaquetées avec un emplacement externe ou non empaquetées.

Overview

Par défaut, lorsque vous créez un projet à l’aide de l’un des modèles WinUI 3 dans Visual Studio, votre projet est configuré pour générer l’application dans un package MSIX à l’aide de MSIX à projet unique (voir Packager votre application à l’aide de MSIX à projet unique) ou d’un projet Windows Application Packaging (voir Configurer votre application de bureau pour l’empaquetage MSIX dans Visual Studio). Vous pouvez ensuite créer un package MSIX pour votre application à l’aide des instructions de Packager une application de bureau ou UWP dans Visual Studio. Après avoir créé un package MSIX pour votre application, vous avez plusieurs options pour gérer le déploiement MSIX.

Pour en savoir plus sur les packages dont votre application empaquetée peut avoir besoin lorsqu’elle utilise le SDK d'application Windows, consultez l’architecture Deployment pour le SDK d'application Windows. Ceux-ci incluent les packages Framework, Main et Singleton  ; qui sont tous signés et publiés par Microsoft. Il existe deux exigences principales pour le déploiement d’une application empaquetée :

  1. Déployer le package d’infrastructure du Kit de développement logiciel (SDK) d’application Windows.
  2. Appelez l’API de déploiement.

Prerequisites

Déployer le package d’infrastructure SDK d'application Windows

Le package d’infrastructure SDK d'application Windows contient les fichiers binaires SDK d'application Windows utilisés au moment de l’exécution, et il est installé avec votre application. Le framework a des exigences de déploiement différentes pour différents canaux de la SDK d'application Windows.

Version stable

Lorsque vous installez une version stable du package NuGet SDK d'application Windows sur votre ordinateur de développement et que vous créez un projet à l’aide de l’un des modèles de projet WinUI fournis, le manifeste de package généré contient un élément PackageDependency qui spécifie une dépendance sur le package d’infrastructure.

Toutefois, si vous générez manuellement votre package d’application à l’aide d’un projet d’empaquetage d’applications Windows distinct, vous devez déclarer une PackageReference dans votre fichier Application (package).wapproj, comme suit :

<ItemGroup>
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.260209005">
       <IncludeAssets>build</IncludeAssets>
   </PackageReference>
</ItemGroup>

Cette dépendance de package garantit que le package Framework est installé lorsque votre application est déployée sur un autre ordinateur.

Préversion

Lorsque vous installez une préversion de la version préliminaire du package NuGet SDK d'application Windows sur votre ordinateur de développement, une préversion du package d’infrastructure SDK d'application Windows est déployée pendant la génération en tant que dépendance de package NuGet.

Appeler l’API de déploiement

Consultez également Initialiser le SDK d'application Windows.

L’API de déploiement est fournie par le package du framework SDK d'application Windows et est disponible dans le namespace Microsoft.Windows.ApplicationModel.WindowsAppRuntime. Le modèle d'application Windows ne prend pas en charge la déclaration d'une dépendance sur les packages Main et Singleton. L’API de déploiement est donc requise pour ces raisons :

  1. Pour déployer le package Singleton pour les fonctionnalités non dans le package Framework (par exemple, les notifications Push).
  2. Pour déployer le package principal, qui permet des mises à jour automatiques vers le package Framework à partir du Microsoft Store.

Pour les applications empaquetées qui ne sont pas distribuées via le Windows Store, vous êtes responsable de la distribution du package Framework. Nous vous recommandons d’appeler l’API de déploiement afin que toutes les mises à jour de maintenance critiques soient remises. Notez que pour utiliser des fonctionnalités en dehors du package Framework (par exemple, des notifications Push), le package Singleton doit être déployé (cela peut être effectué avec l’API de déploiement ou en redistribuant les packages MSIX à l’aide de votre propre méthode d’installation).

Important

Seules les applications empaquetées qui ont une confiance totale ou qui ont la fonctionnalité restreinte packageManagement ont l’autorisation d’utiliser l’API de déploiement pour installer les dépendances du package Main et Singleton.

Vous devez appeler l'API de déploiement après l'initialisation du processus de votre application, mais avant d'utiliser SDK d'application Windows fonctionnalités d'exécution qui utilisent le package Singleton (par exemple, les notifications Push). Les principales méthodes de l’API Deployment sont les méthodes Statiques GetStatus et Initialize de la classe DeploymentManager .

  • La méthode GetStatus retourne l'état de déploiement actuel du runtime SDK d'application Windows actuellement chargé. Utilisez cette méthode pour déterminer s'il est nécessaire d'installer SDK d'application Windows packages d'exécution avant que l'application actuelle puisse utiliser des fonctionnalités SDK d'application Windows.
  • La méthode Initialize vérifie si tous les packages requis sont présents à une version minimale nécessaire par le runtime SDK d'application Windows actuellement chargé. Si des dépendances de package sont manquantes, la méthode tente d’inscrire ces packages manquants. À compter de SDK d'application Windows 1.1, la méthode Initialize prend également en charge l’option de forcer le déploiement forcé des packages d’exécution SDK d'application Windows. Cela arrête tous les processus pour les packages d’exécution Main et Singleton , et interrompt donc leurs services (par exemple, les notifications Push ne fournissent pas de notifications pendant cette période). Vous devez appeler Initialiser une seule fois. Vous n'avez pas besoin d'appeler Initialize pour les applications déployées via les commandes Démarrer sans débogage et Démarrer le débogage dans Visual Studio.

Important

La valeur par défaut de la propriété Visual Studio <WindowsAppSdkDeploymentManagerInitialize> est true. Par conséquent, si vous souhaitez appeler DeploymentManager.Initialize explicitement, définissez <WindowsAppSdkDeploymentManagerInitialize>false</WindowsAppSdkDeploymentManagerInitialize> dans votre fichier projet Visual Studio.

Exemple d’application d’API de déploiement

Pour obtenir des conseils supplémentaires sur l’utilisation des méthodes GetStatus et Initialize de la classe DeploymentManager , explorez l’exemple d’application disponible.

Explorer l’exemple d’application api de déploiement

Résoudre les erreurs d’installation

Si l’API de déploiement rencontre une erreur lors de l’installation des packages d’exécution SDK d'application Windows, elle retourne un code d’erreur qui décrit le problème.

Le tableau suivant répertorie les codes d’erreur courants de l’API de déploiement et leurs causes classiques :

Code d'erreur Nom Cause courante
0x80070005 ACCESS_DENIED L’application n’est pas approuvée en tant qu’application de confiance totale, ou ne dispose pas de la capacité restreinte packageManagement. Exécutez avec des privilèges élevés ou ajoutez la capacité requise.
0x80073CF0 ERROR_INSTALL_OPEN_PACKAGE_FAILED Le package MSIX est endommagé ou inaccessible. Vérifiez que le fichier de package est intact et que le chemin d’accès est correct.
0x80073CF3 ERROR_INSTALL_PREREQUISITE_FAILED Un package de dépendances requis est manquant ou incompatible. Vérifiez que le package d’infrastructure VCLibs et tous les autres prérequis sont installés.
0x80073D06 ERROR_PACKAGES_IN_USE Un ou plusieurs packages sont en cours d’utilisation et ne peuvent pas être mis à jour. Fermez toutes les applications à l’aide du runtime SDK d'application Windows, puis réessayez.
0x80073CFB ERROR_PACKAGE_ALREADY_EXISTS La version du package est déjà enregistrée. Il s’agit d’informations : votre application peut continuer.
0x80073CF9 ERROR_INSTALL_FAILED Échec général de l’installation. Consultez les journaux des événements pour plus d’informations (voir ci-dessous).

Tip

Pour obtenir la liste complète des codes d’erreur d’installation du package MSIX, consultez Résolution des problèmes liés à l’empaquetage, au déploiement et à la requête des applications Windows.

Si le code d’erreur ne fournit pas suffisamment d’informations, vous trouverez plus d’informations de diagnostic dans les journaux d’événements détaillés (consultez Obtenir des informations de diagnostic). Les journaux des événements se trouvent dans observateur d'événements sous Journaux> des applications et des services Microsoft>Windows>AppxDeployment-Server.

Si vous rencontrez des erreurs que vous ne pouvez pas diagnostiquer, déposez un problème dans le WindowsAppSDK GitHub référentiel avec le code d'erreur et les journaux des événements afin que nous puissions examiner le problème.

  • Last updated on