Tutoriel : Utiliser l’API du programme de démarrage dans une application empaquetée avec un emplacement externe ou non empaquetée qui utilise le SDK d’application Windows

Cet article explique comment configurer une application qui 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) pour utiliser l’API du programme d’amorçage afin qu’elle charge explicitement le runtime SDK d'application Windows et appelle SDK d'application Windows API. Les applications qui ne sont pas installées via MSIX incluent les applications empaquetées avec un emplacement externe et les applications non empaquetées.

Important

À compter du SDK d’application Windows 1.0, l’approche par défaut pour charger le SDK d’application Windows à partir d’une application packagée avec un emplacement externe ou non packagée consiste à utiliser l’initialisation automatique par le biais de la propriété <WindowsPackageType> du projet (ainsi qu’à apporter d’autres modifications de configuration). Pour connaître les étapes de l’initialisation automatique dans le contexte d’un projet WinUI 3, consultez Créer votre premier projet WinUI 3. Ou, si vous avez un projet existant qui n’est pas WinUI 3, consultez Utiliser le SDK d’application Windows dans un projet existant.

Si vous avez des besoins avancés (tels que la gestion des erreurs personnalisées ou le chargement d’une version spécifique du SDK d'application Windows), vous pouvez appeler explicitement l’API du programme d’amorçage. Et c’est l’approche que cette rubrique illustre. Pour plus d’informations, consultez Utiliser le runtime SDK d'application Windows pour les applications empaquetées avec un emplacement externe ou non empaquetées.

Cette rubrique montre explicitement l’appel de l’API du programme d’amorçage à partir d’un projet d’application console de base ; mais les étapes s’appliquent à toute application de bureau non empaquetée qui utilise le SDK d'application Windows.

Avant de suivre ce didacticiel, nous vous recommandons de consulter l’architecture d’exécution pour en savoir plus sur la dépendance de package Framework que votre application prend lorsqu’elle utilise le SDK d'application Windows, ainsi que les composants supplémentaires requis pour fonctionner dans un package avec un emplacement externe ou une application non empaquetée.

Prérequis

1. Installation d’outils pour le SDK pour application Windows.
2. Vérifiez que toutes les dépendances pour les applications empaquetées avec un emplacement externe et non empaquetées sont installées (consultez SDK d'application Windows guide de déploiement pour les applications dépendantes de l’infrastructure empaquetées avec un emplacement externe ou non empaquetées). Pour ce faire, il est facile d’exécuter le programme d’installation du runtime SDK d'application Windows.

Instructions

Vous pouvez suivre ce tutoriel à l’aide d’un projet C# ou C++.

Notes

Les dépendances dynamiques et les API de programme d’amorçage échouent lorsqu’elles sont appelées par un processus avec élévation de privilèges. Par conséquent, Visual Studio ne doit pas être lancé avec élévation de privilèges. Pour plus d’informations, consultez Dépendances dynamiques ne prend pas en charge l’élévation #567 .

C#

Suivez ces instructions pour configurer un projet WinUI 3 C# empaqueté avec un emplacement externe ou non empaqueté.

1. Dans Visual Studio, créez un projet d’application console C#. Nommez le projet DynamicDependenciesTest. Après avoir créé le projet, vous devez avoir un « Hello, World ! » Application console C#.

2. Ensuite, configurez votre projet.

   1. Dans Explorateur de solutions, cliquez avec le bouton droit sur votre projet et choisissez Modifier le fichier projet.
   2. Remplacez la valeur de l’élément TargetFramework par un moniker d’infrastructure cible. Par exemple, utilisez ce qui suit si votre application cible Windows 10, version 2004.

   <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
   

   1. Enregistrez et fermez le fichier projet.

3. Remplacez la plateforme de votre solution par x64. La valeur par défaut dans un projet .NET est AnyCPU, mais WinUI 3 ne prend pas en charge cette plateforme.

   1. Sélectionnez Build>Gestionnaire de configuration.
   2. Sélectionnez la liste déroulante sous Plateforme de solution active , puis cliquez sur Nouveau pour ouvrir la boîte de dialogue Nouvelle plateforme de solution .
   3. Dans la liste déroulante sous Type ou sélectionnez la nouvelle plateforme, sélectionnez x64.
   4. Cliquez sur OK pour fermer la boîte de dialogue Nouvelle plateforme de solution .
   5. Dans Configuration Manager, cliquez sur Fermer.

4. Installez le package NuGet SDK d'application Windows dans votre projet.

   1. Dans Explorateur de solutions, cliquez avec le bouton droit sur le nœud Dépendances et choisissez Gérer les packages Nuget.
   2. Dans la fenêtre Gestionnaire de package NuGet , sélectionnez l’onglet Parcourir , puis installez le package Microsoft.WindowsAppSDK .

5. Vous êtes maintenant prêt à utiliser l’API du programme d’amorçage (voir Utiliser le runtime SDK d'application Windows pour les applications empaquetées avec un emplacement externe ou non empaquetées) pour prendre une dépendance dynamique sur le package d’infrastructure SDK d'application Windows. Cela vous permet d’utiliser les API SDK d'application Windows dans votre application.

   Ouvrez le fichier de code Program.cs et remplacez le code par défaut par le code suivant pour appeler la méthode Bootstrap.Initialize pour initialiser le programme d’amorçage. Ce code définit la version du SDK d'application Windows dont l’application dépend lors de l’initialisation du programme d’amorçage.

   Important

   Vous devez modifier le code ci-dessous en fonction de votre configuration spécifique. Consultez les descriptions des paramètres de la méthode Bootstrap.Initialize afin de pouvoir spécifier l’une des versions du SDK d'application Windows que vous avez installé.

   using System;
   using Microsoft.Windows.ApplicationModel.DynamicDependency;
   
   namespace DynamicDependenciesTest
   {
       class Program
       {
           static void Main(string[] args)
           {
               Bootstrap.Initialize(0x00010002);
               Console.WriteLine("Hello, World!");
   
               // Release the DDLM and clean up.
               Bootstrap.Shutdown();
           }
       }
   }
   

   À sa racine, l’API du programme d’amorçage est une API C/C++ native qui vous permet d’utiliser les API SDK d'application Windows dans votre application. Toutefois, dans une application .NET qui utilise le SDK d'application Windows 1.0 ou version ultérieure, vous pouvez utiliser le wrapper .NET pour l’API du programme d’amorçage. Ce wrapper offre un moyen plus facile d’appeler l’API du programme d’amorçage dans une application .NET que d’appeler directement les fonctions C/C++ natives. L’exemple de code précédent appelle les méthodes statiques Initialize et Shutdown de la classe Bootstrap dans le wrapper .NET pour l’API du programme d’amorçage.

6. Pour démontrer que les composants du runtime SDK d'application Windows ont été chargés correctement, ajoutez du code qui utilise la classe ResourceManager dans le SDK d'application Windows pour charger une ressource de chaîne.

   1. Ajoutez un nouveau fichier de ressources (.resw) à votre projet (conservez le nom par défaut).

   2. Une fois le fichier de ressources ouvert dans l’éditeur, créez une ressource de chaîne avec les propriétés suivantes.

      • Nom : Message
      • Valeur : Bonjour, ressources !

   3. Enregistrez le fichier de ressources.

   4. Ouvrez le fichier de code Program.cs et remplacez la Console.WriteLine("Hello, World!"); ligne par le code suivant.

   // Create a resource manager using the resource index generated during build.
    var manager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager("DynamicDependenciesTest.pri");
   
   // Look up a string in the .resw file using its name.
   Console.WriteLine(manager.MainResourceMap.GetValue("Resources/Message").ValueAsString);
   

   1. Cliquez sur Démarrer sans débogage (ou Démarrer le débogage) pour générer et exécuter votre application. Vous devriez voir la chaîne Hello, resources! affichée avec succès.

C++

Suivez ces instructions pour configurer un projet WinUI 3 C++ empaqueté avec un emplacement externe ou non empaqueté.

1. Dans Visual Studio, créez un projet d’application console C++. Nommez le projet DynamicDependenciesTest.

   

   Après avoir créé le projet, vous devez avoir un « Hello, World ! » Application console C++.

2. Ensuite, installez le package NuGet SDK d'application Windows dans votre projet.

   1. Dans Explorateur de solutions, cliquez avec le bouton droit sur le nœud Références et choisissez Gérer les packages Nuget.
   2. Dans la fenêtre Gestionnaire de package NuGet , sélectionnez l’onglet Parcourir , puis recherchez Microsoft.WindowsAppSDK.

3. Vous êtes maintenant prêt à utiliser l’API du programme d’amorçage (voir Utiliser le runtime SDK d'application Windows pour les applications empaquetées avec un emplacement externe ou non empaquetées) pour initialiser le runtime SDK d'application Windows dans votre application. Cela vous permet d’utiliser les API SDK d'application Windows dans l’application.

   1. Ajoutez les fichiers include suivants en haut de votre fichier DynamicDependenciesTest.cpp . L’en-tête mddbootstrap.h est disponible via le package NuGet SDK d'application Windows.

   #include <windows.h>
   #include <MddBootstrap.h>
   

   1. Ensuite, ajoutez ce code au début de votre méthode main pour appeler la fonction MddBootstrapInitialize afin d’initialiser le programme d’amorçage et de gérer les erreurs éventuelles. Ce code définit la version du SDK d'application Windows dont l’application dépend lors de l’initialisation du programme d’amorçage.

   Important

   Vous devez modifier le code ci-dessous en fonction de votre configuration spécifique. Consultez les descriptions des paramètres de la fonction MddBootstrapInitialize afin de pouvoir spécifier l’une des versions du SDK d'application Windows que vous avez installé.

   const UINT32 majorMinorVersion{ 0x00010002 }; 
   PCWSTR versionTag{ L"" }; 
   const PACKAGE_VERSION minVersion{};
   
   const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
   // Check the return code for errors. If there is an error, display the result.
   if (FAILED(hr)) 
   { 
       wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
           hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
       return hr; 
   } 
   

   1. Enfin, ajoutez ce code pour afficher la chaîne Hello, World! et appelez la fonction MddBootstrapShutdown pour annuler l’initialisation du programme d’amorçage.

   std::cout << "Hello, World!\n"; 
   
   // Release the DDLM and clean up.
   MddBootstrapShutdown(); 
   

   1. Votre code final doit ressembler à ceci.

   #include <iostream> 
   #include <windows.h> 
   #include <MddBootstrap.h>
   
   int main() 
   { 
       // Take a dependency on Windows App SDK Stable.
       const UINT32 majorMinorVersion{ 0x00010002 }; 
       PCWSTR versionTag{ L"" }; 
       const PACKAGE_VERSION minVersion{};
   
       const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
       // Check the return code. If there is a failure, display the result.
       if (FAILED(hr)) 
       { 
           wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
               hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
           return hr; 
       } 
   
       std::cout << "Hello, World!\n"; 
   
       // Release the DDLM and clean up.
       MddBootstrapShutdown(); 
   } 
   

4. Cliquez sur Démarrer sans débogage (ou Démarrer le débogage) pour générer et exécuter votre application.

Si votre projet est WPF

Pour une application Windows Presentation Foundation (WPF), consultez Utiliser la SDK d'application Windows dans une application WPF.

Rubriques connexes

• Guide de déploiement du SDK d’application Windows pour les applications dépendantes de l’infrastructure empaquetées avec un emplacement externe ou non empaquetées
• Architecture d’exécution