Utiliser le runtime du SDK d’application Windows pour les applications empaquetées avec un emplacement externe ou non empaquetées

  • Article

Notes

Si votre application est installée à l’aide de la technologie MSIX, consultez SDK d'application Windows guide de déploiement pour les applications empaquetées dépendantes de l’infrastructure.

Si votre application n’est pas installée à l’aide de MSIX (c’est-à-dire qu’elle est empaquetée avec un emplacement externe ou non empaquetée), vous devez initialiser le SDK d'application Windows pour l’utiliser avant de pouvoir appeler SDK d'application Windows fonctionnalités telles que WinUI 3, App Lifecycle, MRT Core et DWriteCore. Votre application doit initialiser le runtime SDK d'application Windows avant d’utiliser toute autre fonctionnalité du SDK d'application Windows.

  • À compter de SDK d'application Windows 1.0, cela peut être effectué automatiquement lorsque votre application démarre via l’initialisation automatique (définissez la propriété <WindowsPackageType>None</WindowsPackageType>du projet ). Pour une démonstration, consultez Créer votre premier projet WinUI 3.
  • Toutefois, si vous avez des besoins avancés (par exemple, la gestion des erreurs en affichant votre propre interface utilisateur personnalisée ou journalisation, ou si vous devez charger une version de l’SDK d'application Windows différente de la version que vous avez créée), poursuivez la lecture de cette rubrique. Dans ces scénarios, au lieu de l’initialisation automatique, vous pouvez appeler l’API du programme d’amorçage explicitement.

L’une des deux techniques ci-dessus permet à une application qui n’utilise pas MSIX de prendre une dépendance dynamique sur le SDK d'application Windows au moment de l’exécution.

Pour obtenir des informations générales sur les dépendances dynamiques, consultez Packages d’infrastructure MSIX et dépendances dynamiques.

En arrière-plan et refus de l’initialisation automatique des modules

Le code généré par la WindowsPackageType propriété mentionnée ci-dessus tire parti des initialiseurs de module pour appeler l’API du programme d’amorçage. Le programme d’amorçage effectue le gros travail pour trouver le SDK d'application Windows et permettre au processus actuel de l’utiliser. Le code généré gère à la fois l’initialisation et l’arrêt. Vous pouvez contrôler le comportement de l’initialisation avec les propriétés de projet suivantes :

  • <WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
    • Utilisez les options par défaut.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
    • N’utilisez aucune option.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
    • Appelez DebugBreak() si une erreur se produit uniquement si un débogueur est attaché au processus.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
    • Effectuez un échec rapide en cas d’erreur.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
    • Invitez l’utilisateur à acquérir le runtime SDK d'application Windows s’il est introuvable.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Succcéé si appelé dans un processus avec l’identité de package (sinon, il échoue et une erreur est retournée).

Si vous souhaitez que votre application dispose d’un contrôle explicite, vous pouvez appeler directement l’API boostrapper au début du démarrage de votre application. Dans ce cas, vous n’avez pas besoin WindowsPackageType de votre fichier projet.

Notes

En plus de l’initialisation automatique et de l’API du programme d’amorçage, le SDK d'application Windows fournit également une implémentation de l’API de dépendance dynamique. Cette API permet à vos applications non empaquetées de dépendre de n’importe quel package d’infrastructure (pas seulement le package d’infrastructure SDK d'application Windows), et elle est utilisée en interne par l’API du programme d’amorçage. Pour plus d’informations sur l’API de dépendance dynamique, consultez Utiliser l’API de dépendance dynamique pour référencer des packages MSIX au moment de l’exécution.

Refus de l’initialisation automatique de module (ou de l’initialisation automatique)

La propriété <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> de projet désactive l’initialisation automatique du module décrite ci-dessus (l’API du programme d’amorçage n’est pas appelée). Cela permet à votre application de prendre des responsabilités et d’appeler directement l’API du programme d’amorçage.

À compter de la version 1.2 du SDK d'application Windows (à partir du canal stable), l’initialisation automatique du module s’applique uniquement aux projets qui produisent un exécutable (autrement dit, la propriété de projet OutputType est définie sur Exe ou WinExe). Cela permet d’empêcher l’ajout d’initialiseurs automatiques dans les DLL de bibliothèques de classes et d’autres fichiers non exécutables par défaut. Si vous avez besoin d’un initialiseur automatique dans un fichier non exécutable (par exemple, une DLL de test chargée par un exécutable de processus hôte qui n’initialise pas le programme d’amorçage), vous pouvez activer explicitement un initialiseur automatique dans votre projet avec <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>.

Utilisation de l’API du programme d’amorçage

Important

La fonction MddBootstrapInitialize2 mentionnée ci-dessous est disponible à partir de la version 1.1.

L’API du programme d’amorçage se compose de trois fonctions C/C++ déclarées dans le fichier d’en-tête mddbootstrap.h dans le SDK d'application Windows : MddBootstrapInitialize, MddBootstrapInitialize2 et MddBootstrapShutdown. Ces fonctions sont fournies par la bibliothèque de programme d’amorçage dans le SDK d'application Windows. Cette bibliothèque est une petite DLL que vous devez distribuer avec votre application ; il ne fait pas partie du package d’infrastructure lui-même.

MddBootstrapInitialize2

Cette fonction initialise le processus appelant pour utiliser la version du package d’infrastructure SDK d'application Windows qui correspond le mieux aux critères que vous passez aux paramètres de fonction. En règle générale, cela entraîne le référencement de la version du package d’infrastructure qui correspond au package NuGet SDK d'application Windows installé. Si plusieurs packages répondent aux critères, le meilleur candidat est sélectionné. Cette fonction doit être l’un des premiers appels au démarrage de l’application pour s’assurer que le composant de programme d’amorçage peut correctement initialiser le SDK d'application Windows et ajouter la référence d’exécution au package d’infrastructure.

L’API du programme d’amorçage utilise l’API Dépendances dynamiques pour ajouter le package d’infrastructure du runtime SDK d'application Windows au graphe de package du processus actuel et activer l’accès au package.

Cette fonction initialise également le Gestionnaire de durée de vie des dépendances dynamiques (DDLM). Ce composant fournit une infrastructure pour empêcher le système d’exploitation de gérer le package d’infrastructure SDK d'application Windows pendant qu’il est utilisé par une application non empaquetée.

MddBootstrapShutdown

Cette fonction supprime les modifications apportées au processus actuel par un appel à MddBootstrapInitialize. Une fois cette fonction appelée, votre application ne peut plus appeler SDK d'application Windows API, y compris l’API de dépendances dynamiques.

Cette fonction arrête également le Gestionnaire de durée de vie des dépendances dynamiques (DDLM) afin que Windows puisse traiter le package d’infrastructure si nécessaire.

Wrapper .NET pour l’API du programme d’amorçage

Bien que vous puissiez appeler l’API du programme d’amorçage C/C++ directement à partir d’applications .NET, cela nécessite l’utilisation d’un appel de plateforme pour appeler les fonctions. Dans SDK d'application Windows versions 1.0 et ultérieures, un wrapper .NET pour l’API du programme d’amorçage est disponible dans l’assemblyMicrosoft.WindowsAppRuntime.Bootstrap.Net.dll. Cet assembly fournit une API plus facile et plus naturelle pour les développeurs .NET pour accéder aux fonctionnalités du programme d’amorçage. La classe Bootstrap fournit des fonctions statiques Initialize, TryInitialize et Shutdown qui encapsulent les appels aux fonctions MddBootstrapInitialize et MddBootstrapShutdown pour les scénarios les plus courants. Pour obtenir un exemple qui montre comment utiliser le wrapper .NET pour l’API du programme d’amorçage, consultez les instructions C# dans Tutoriel : Utiliser l’API de programme d’amorçage dans une application empaquetée avec un emplacement externe ou non empaquetée qui utilise le SDK d'application Windows.

Pour plus d’informations sur le wrapper .NET pour l’API du programme d’amorçage, consultez les ressources suivantes :

Wrapper C++ pour l’API du programme d’amorçage

Un wrapper C++ pour l’API du programme d’amorçage est disponible à partir de SDK d'application Windows 1.1.

Consultez API C++ du programme d’amorçage.

Déclarer la compatibilité du système d’exploitation dans votre manifeste d’application

Pour déclarer la compatibilité du système d’exploitation et éviter que l’SDK d'application Windows par défaut Windows 8 comportement (et les incidents potentiels), vous pouvez inclure un manifeste d’application côte à côte avec votre package avec un emplacement externe ou une application non empaquetée. Consultez les manifestes d’application (il s’agit du fichier qui déclare des éléments tels que la prise en charge du DPI et qui est incorporé dans le .exe de votre application pendant la compilation). Cela peut être un problème si vous ajoutez SDK d'application Windows prise en charge à une application existante, plutôt que d’en créer une via un modèle de projet Visual Studio.

Si vous n’avez pas encore de manifeste d’application côte à côte dans votre projet, ajoutez un nouveau fichier XML à votre projet et nommez-le comme recommandé dans Manifestes d’application. Ajoutez au fichier l’élément de compatibilité et les éléments enfants indiqués dans l’exemple suivant. Ces valeurs contrôlent le niveau de bizarreries pour les composants en cours d’exécution dans le processus de votre application.

Remplacez l’attribut Id de l’élément maxversiontested par le numéro de version de Windows que vous ciblez (doit être 10.0.17763.0 ou version ultérieure). Notez que la définition d’une valeur plus élevée signifie que les anciennes versions de Windows n’exécutent pas correctement votre application, car chaque version de Windows ne connaît que les versions antérieures. Par conséquent, si vous souhaitez que votre application s’exécute sur Windows 10, version 1809 (10.0 ; Build 17763), vous devez laisser la valeur 10.0.17763.0 telle qu’elle est, ou ajouter plusieurs éléments maxversiontested pour les différentes valeurs que votre application prend en charge.

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
    <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
        <application>
            <!-- Windows 10, version 1809 (10.0; Build 17763) -->
            <maxversiontested Id="10.0.17763.0"/>
            <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
        </application>
    </compatibility>
</assembly>