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

Article
06/24/2024

Remarque

Si votre application est installée à l’aide de la technologie MSIX, consultez le guide de déploiement du Kit de développement logiciel (SDK) d’application Windows 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 à l’emplacement externe ou non empaquetée), vous devez initialiser le Kit de développement logiciel (SDK) d’application Windows pour une utilisation avant de pouvoir appeler des fonctionnalités du KIT DE DÉVELOPPEMENT logiciel (SDK) d’application Windows telles que WinUI 3, Cycle de vie des applications, MRT Core et DWriteCore. Votre application doit initialiser le runtime du Kit de développement logiciel (SDK) d’application Windows avant d’utiliser toute autre fonctionnalité du Kit de développement logiciel (SDK) d’application Windows.

À compter du Kit de développement logiciel (SDK) d’application Windows 1.0, qui 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 du 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 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 refus de l’initialisation automatique du module

Le code généré par la WindowsPackageType propriété mentionnée ci-dessus tire parti des initialiseurs de module pour appeler l’API de démarrage. Le programme d’amorçage effectue l’effort lourd pour trouver le Kit de développement logiciel (SDK) de l’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>
- 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 échec rapide si une erreur se produit.
<WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
- Invitez l’utilisateur à acquérir le runtime du Kit de développement logiciel (SDK) d’application Windows si un runtime correspondant est introuvable.
<WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
- Réussi s’il est appelé dans un processus avec l’identité du package (sinon elle é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 WindowsPackageType dans votre fichier projet.

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 prendre une dépendance sur n’importe quel package d’infrastructure (pas seulement le package d’infrastructure du SDK d’application Windows) et il est utilisé 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 ou acceptation de l’initialisation automatique du module

La propriété <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> du projet désactive l’initialisation automatique du module décrite 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 Kit de développement logiciel (SDK) de l’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 des DLL de bibliothèque 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 de démarrage

Important

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

L’API bootstrapper se compose de trois fonctions C/C++ déclarées dans le fichier d’en-tête mddbootstrap.h dans le Kit de développement logiciel (SDK) d’application Windows : MddBootstrapInitialize, MddBootstrapInitialize2 et MddBootstrapShutdown. Ces fonctions sont fournies par la bibliothèque de programme d’amorçage dans le Kit de développement logiciel (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 du Kit de développement logiciel (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 du Kit de développement logiciel (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 initialiser correctement le SDK d’application Windows et ajouter la référence au runtime au package d’infrastructure.

L’API de démarrage utilise l’API Dépendances dynamiques pour ajouter le package d’infrastructure du runtime du KIT de développement logiciel (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 l’infrastructure pour empêcher le système d’exploitation de maintenance du package d’infrastructure du Kit de développement logiciel (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 les API du Kit de développement logiciel (SDK) d’application Windows, 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 de démarrage

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 plateforme pour appeler les fonctions. Dans windows App SDK 1.0 et versions 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 facile et plus naturelle pour les développeurs .NET 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 : Utilisez l’API de démarrage dans une application empaquetée avec un emplacement externe ou non empaquetée qui utilise le Kit de développement logiciel (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 programme d’amorçage.
Section 6.1.4 de la spécification des dépendances dynamiques.
Bootstrap.cs : implémentation code source ouvert du wrapper .NET pour l’API de démarrage.

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

Un wrapper C++ pour l’API de programme d’amorçage est disponible à partir du Kit de développement logiciel (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é du système d’exploitation et éviter le comportement par défaut du SDK d’application Windows 8 (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 la prise en charge du Kit de développement logiciel (SDK) d’application Windows à une application existante, plutôt que de en créer un 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 les manifestes d’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 quirks 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 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>

Partager via