Initialiser dynamiquement le package SDK d'application Windows Framework

Remarque

Les applications empaquetées, y compris les applications empaquetées avec un emplacement externe (packages partiels), peuvent déclarer statiquement la dépendance au framework SDK d'application Windows avec <PackageDependency> dans AppxManifest.xml. Ils n’ont pas besoin d’initialisation du programme d’amorçage pour cette dépendance. Consultez le guide de déploiement de SDK d'application Windows pour les applications empaquetées dépendantes de l’infrastructure.

Une application dépendante de l’infrastructure doit avoir le package SDK d'application Windows Framework dans son graphe de package de processus avant de pouvoir utiliser des API de ce package, telles que WinUI 3, App Lifecycle, MRT Core et DWriteCore. Pour les applications non empaquetées sans dépendance static Framework, l’API bootstrapper établit cette dépendance dynamiquement.

Les applications autonomes embarquent les binaires du Framework localement dans l’application et n’ont pas besoin d’une dépendance MSIX Framework ni d’une initialisation du Bootstrapper pour ces binaires. Consultez SDK d'application Windows guide de déploiement pour les applications autonomes.

  • À 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 Créer et exécuter un projet WinUI 3.
  • 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 ou l’autre technique permet à une application non empaquetée dépendant de l’infrastructure de prendre une dépendance dynamique sur le package SDK d'application Windows Framework au moment de l’exécution. L’empaquetage avec un emplacement externe n’est pas, par lui-même, une raison d’utiliser l’une ou l’autre technique.

Pour les applications console C# et C++ qui utilisent l’initialisation automatique, consultez les exemples SDK d'application Windows non empaquetés.

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>
  • <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 sans effectuer de travail s’il est appelé dans un processus avec l’identité du package. Cette option n’ajoute pas de dépendance Framework pour ce processus ; déclarez la dépendance dans son manifeste de package.

Pour plus d’informations sur les options d’initialisation, consultez MddBootstrapInitializeOptions.

Si vous souhaitez que votre application dispose d’un contrôle explicite, désactivez l’initialiseur automatique du programme d’amorçage, comme décrit ci-dessous, puis appelez l’API bootstrapper tôt au démarrage de votre application.

Important

L’initialisation du Bootstrapper n’ajoute pas de dépendance dans un processus avec une identité de package, y compris une application empaquetée avec un emplacement externe. Elle retourne une erreur, sauf si l’option no-op package-identity est activée. Pour ces applications, déclarez plutôt la dépendance Framework dans AppxManifest.xml. Consultez l’implémentation du programme d’amorçage.

Remarque

Outre l’initialisation automatique et l’API de 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 any package d’infrastructure (pas seulement le package d’infrastructure SDK d'application Windows), et il est utilisé en interne par l’API de démarrage. 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.

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

Important

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

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.

Si nécessaire par le système d’exploitation, cette fonction initialise également le Gestionnaire de durée de vie des dépendances dynamiques (DDLM) pour conserver le package Framework référencé dynamiquement en cours d’utilisation. Sur les versions prises en charge de Windows 11, le programme d’amorçage peut utiliser la gestion de la durée de vie des dépendances dynamiques natives du système d’exploitation à la place.

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 qui montre comment utiliser le wrapper .NET pour l’API de programme d’amorçage, consultez les instructions C# du tutoriel : Utiliser l’API de démarrage dans une application non empaquetée.

Pour plus d’informations sur le wrapper .NET pour l’API de démarrage, consultez les ressources suivantes :

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