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

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 à utiliser pour pouvoir appeler des fonctionnalités SDK d'application Windows 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é de la SDK d'application Windows.

• À compter de SDK d'application Windows 1.0, cette opération peut être effectuée automatiquement lorsque votre application démarre via l’initialisation automatique (définissez la propriété project <WindowsPackageType>None</WindowsPackageType>). Pour une démonstration, consultez Create your first WinUI project.
• Toutefois, si vous avez des besoins avancés (tels que la gestion des erreurs en affichant votre propre interface utilisateur personnalisée ou journalisation, ou si vous devez charger une version du SDK d'application Windows différent 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 explicitement l’API de programme d’amorçage.

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 plus d’informations sur les dépendances dynamiques, consultez les packages d’infrastructure MSIX et les dépendances dynamiques.

En arrière-plan, et en désactivant les initialiseurs automatiques

Le code généré par la propriété WindowsPackageType, mentionnée ci-dessus, tire parti des auto-initialiseurs pour appeler l’API de bootstrap. 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 project 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>
  • Appelez DebugBreak() si une erreur se produit.
• <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 arrêt immédiat si une erreur se produit.
• <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
  • Invitez l’utilisateur à acquérir le runtime SDK d'application Windows si un runtime correspondant est introuvable.
• <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
  • Réussit s’il est appelé dans un processus possédant une 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émarrage de votre application. Dans ce cas, vous n'avez pas besoin de WindowsPackageType dans votre fichier project.

Désactivation ou activation des initialiseurs automatiques

La propriété project <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> désactive l'initialiseur automatique décrit ci-dessus (l'API de démarrage n'est pas appelée). Cela permet à votre application de prendre la responsabilité 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), les initialiseurs automatiques s’appliquent uniquement aux projets qui produisent un exécutable (autrement dit, la propriété OutputType project est définie sur Exe ou WinExe). Cela permet d’empêcher l’ajout d’initialiseurs automatiques dans des DLL de bibliothèque de classes et d’autres fichiers non exécutables par défaut. Si vous do 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 project avec <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>.

Utilisation de l’API de démarrage

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

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 du package de framework qui correspond au package NuGet du 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 vous assurer que le composant du programme d'amorçage peut initialiser correctement l'SDK d'application Windows et ajouter la référence d'exécution au package d'infrastructure.

L'API de démarrage utilise l'API Dynamic Dependencies pour ajouter le package d'infrastructure du runtime SDK d'application Windows au graph 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 maintenance du 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 qui ont été effectuées 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.

.NET wrapper pour l’API de bootstrapper

Bien que vous puissiez appeler l’API de démarrage C/C++ directement à partir d’applications .NET, cela nécessite l’utilisation d’un appel de platforme pour appeler les fonctions. Dans SDK d'application Windows versions 1.0 et ultérieures, un wrapper .NET pour l’API de démarrage est disponible dans l’assembly Microsoft.WindowsAppRuntime.Bootstrap.Net.dll. Cet assembly offre une API plus simple et plus naturelle pour les développeurs .NET afin d'accéder aux fonctionnalités du programme d'amorçage. La classe Bootstrap fournit des fonctions Initialize, TryInitialize et Shutdown statiques qui encapsulent les appels aux fonctions MddBootstrapInitialize et MddBootstrapShutdown pour les scénarios les plus courants. Pour obtenir un exemple montrant comment utiliser le wrapper .NET pour l’API de démarrage, consultez les instructions C# de Tutorial : utilisez l’API de démarrage 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 de démarrage, consultez les ressources suivantes :

• API C# du chargeur de démarrage.
• Section 6.1.4 de la spécification des dépendances dynamiques.
• Bootstrap.cs : implémentation open source du wrapper .NET pour l’API de démarrage.

Wrapper C++ pour l’API de démarrage

Un wrapper C++ pour l’API de démarrage est disponible à partir de SDK d'application Windows 1.1.

Consultez l’API C++ Bootstrapper.

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

Pour déclarer la compatibilité avec le système d’exploitation (OS) et éviter que le SDK d'application Windows n'adopte par défaut le comportement de Windows 8 (et les incidents potentiels), vous pouvez inclure un manifeste d'application en parallèle avec votre application empaquetée avec un emplacement externe ou votre 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). Il peut s'agir d'un problème si vous ajoutez la prise en charge de SDK d'application Windows à une application existante, plutôt que de créer une nouvelle application via un modèle de projet Visual Studio.

Si vous n'avez pas encore de manifeste d'application côte à côte dans votre project, ajoutez un nouveau fichier XML à votre project et nommez-le comme recommandé dans les manifestes Application. Ajoutez au fichier l’élément de compatibilité et les éléments enfants présentés dans l’exemple suivant. Ces valeurs contrôlent le niveau des particularités pour les composants qui s'exécutent 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 une version ultérieure). Notez que la définition d’une valeur supérieure signifie que les versions antérieures 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>

Voir aussi

• SDK d'application Windows et versions Windows prises en charge
• Guide de déploiement du SDK d'application Windows pour les applications dépendantes du cadre empaquetées avec un emplacement externe ou non empaquetées
• Spécification des dépendances dynamiques
• Packages d’infrastructure MSIX et dépendances dynamiques
• Architecture de runtime du kit SDK d’application Windows
• Tutoriel : utilisez l’API de Bootstrapper dans une application empaquetée avec emplacement externe ou non empaquetée qui utilise le SDK d'application Windows