Tutorial: Verwenden der Bootstrapping-API in einer gepackten App mit externem Speicherort oder nicht gepackten App, die Windows App SDK verwendet

In diesem Artikel wird gezeigt, wie Sie eine App konfigurieren, die nicht mithilfe von MSIX (d. h. mit externem Speicherort oder entpackt) installiert ist, um die Bootstrapper-API zu verwenden, sodass sie die Windows App SDK-Laufzeit explizit lädt und Windows App SDK-APIs aufruft. Apps, die nicht über MSIX installiert sind, umfassen Apps, die mit externem Speicherort verpackt sind, und entpackte Apps.

Wichtig

Ab dem Windows App SDK 1.0 besteht die standardmäßige Vorgehensweise zum Laden des Windows App SDK über eine mit externem Speicherort gepackte App oder über eine nicht gepackte App darin, die automatische Initialisierung über die Projekteigenschaft <WindowsPackageType> zu verwenden (und zusätzliche Konfigurationsänderungen vorzunehmen). Die Schritte für die automatische Initialisierung im Kontext des WinUI 3-Projekts finden Sie unter Erstellen Ihres ersten WinUI 3-Projekts. Wenn Sie hingegen über ein Projekt verfügen, bei dem es sich nicht um ein WinUI 3-Projekt handelt, lesen Sie unter Verwenden des Windows App SDK in einem vorhandenen Projekt weiter.

Wenn Sie komplexere Anforderungen haben (z. B. benutzerdefinierte Fehlerbehandlung oder das Laden einer bestimmten Version des Windows App SDK), können Sie stattdessen die Bootstrapper-API explizit aufrufen. Und das ist der Ansatz, den dieses Thema veranschaulicht. Weitere Informationen finden Sie auch unter Verwenden der Windows App SDK-Runtime für Apps, die mit externem Speicherort verpackt oder entpackt wurden.

In diesem Thema wird das explizite Aufrufen der Bootstrapper-API aus einem einfachen Konsolen-App-Projekt veranschaulicht. die Schritte gelten jedoch für alle entpackten Desktop-Apps, die das Windows App SDK verwenden.

Bevor Sie dieses Lernprogramm abschließen, empfehlen wir Ihnen, die Laufzeitarchitektur zu überprüfen, um mehr über die Abhängigkeit des Framework-Pakets zu erfahren, die Ihre App benötigt, wenn sie das Windows App SDK verwendet, und die zusätzlichen Komponenten, die zum Arbeiten in einem Paket mit externem Speicherort oder entpackten Apps erforderlich sind.

Voraussetzungen

1. Installieren von Tools für das Windows App SDK.
2. Stellen Sie sicher, dass alle Abhängigkeiten für paketierte Apps mit externem Speicherort und entpackten Apps installiert werden (siehe Windows App SDK-Bereitstellungshandbuch für frameworkabhängige Apps, die mit externem Speicherort verpackt oder entpackt sind). Eine einfache Möglichkeit besteht darin, das Windows App SDK-Laufzeitinstallationsprogramm auszuführen.

Anweisungen

Sie können diesem Lernprogramm mithilfe eines C#- oder C++-Projekts folgen.

Hinweis

Die dynamischen Abhängigkeiten und Bootstrapper-APIs schlagen fehl, wenn sie von einem erhöhten Prozess aufgerufen werden. Daher sollte Visual Studio nicht mit erhöhten Rechten gestartet werden. Weitere Details finden Sie unter "Dynamische Abhängigkeiten" .

C#

Führen Sie die folgenden Anweisungen aus, um ein C#WinUI 3-Projekt zu konfigurieren, das entweder mit externem Speicherort verpackt oder entpackt wird.

1. Erstellen Sie in Visual Studio ein neues C# -Konsolen-App-Projekt . Benennen Sie das Projekt DynamicDependenciesTest. Nachdem Sie das Projekt erstellt haben, sollten Sie ein "Hello, World!" haben. C#-Konsolen-App.

2. Konfigurieren Sie als Nächstes Ihr Projekt.

   1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Ihr Projekt, und wählen Sie Projektdatei bearbeiten aus.
   2. Ersetzen Sie den Wert des TargetFramework-Elements durch einen Zielframeworkmoniker. Verwenden Sie beispielsweise Folgendes, wenn Ihre App auf Windows 10, Version 2004 ausgerichtet ist:

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

   1. Speichere und schließe die Projektdatei.

3. Ändern Sie die Plattform für Ihre Lösung in x64. Der Standardwert in einem .NET-Projekt ist AnyCPU, aber WinUI 3 unterstützt diese Plattform nicht.

   1. Wählen Sie Build>Konfigurations-Manager aus.
   2. Wählen Sie das Dropdownmenü unter Aktive Projektmappenplattform aus, und klicken Sie auf Neu, um das Dialogfeld Neue Projektmappenplattform zu öffnen.
   3. Wählen Sie im Dropdownmenü unter Neue Plattform eingeben oder auswählen die Option x64 aus.
   4. Klicken Sie auf OK , um das Dialogfeld Neue Projektmappenplattform zu schließen.
   5. Klicken Sie im Konfigurations-Manager auf Schließen.

4. Installieren Sie das Windows App SDK NuGet-Paket im Projekt.

   1. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf den Knoten Abhängigkeiten, und wählen Sie NuGet-Pakete verwalten aus.
   2. Wählen Sie im NuGet-Paket-Manager-Fenster die Registerkarte "Durchsuchen" aus, und installieren Sie das Microsoft.WindowsAppSDK-Paket.

5. Sie können jetzt die Bootstrapper-API verwenden (siehe Verwenden der Windows App SDK-Runtime für Apps, die mit externem Speicherort oder entpackt sind), um dynamisch eine Abhängigkeit vom Windows App SDK-Frameworkpaket zu übernehmen. Auf diese Weise können Sie die Windows App SDK-APIs in Ihrer App verwenden.

   Öffnen Sie die Program.cs Codedatei, und ersetzen Sie den Standardcode durch den folgenden Code, um die Bootstrap.Initialize-Methode aufzurufen, um den Bootstrapper zu initialisieren. Dieser Code definiert, welche Version des Windows App SDK die App beim Initialisieren des Bootstrappers abhängig ist.

   Wichtig

   Sie müssen den folgenden Code entsprechend Ihrer spezifischen Konfiguration bearbeiten. Lesen Sie die Beschreibungen der Parameter der Bootstrap.Initialize-Methode , damit Sie eine der Versionen des Windows App SDK angeben können, das Sie installiert haben.

   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();
           }
       }
   }
   

   Im Stammverzeichnis ist die Bootstrapper-API eine systemeigene C/C++-API, mit der Sie die Windows App SDK-APIs in Ihrer App verwenden können. In einer .NET-App, die das Windows App SDK 1.0 oder höher verwendet, können Sie jedoch den .NET-Wrapper für die Bootstrapper-API verwenden. Dieser Wrapper bietet eine einfachere Möglichkeit, die Bootstrapper-API in einer .NET-App aufzurufen, als die systemeigenen C/C++-Funktionen direkt aufzurufen. Im vorherigen Codebeispiel werden die statischen Initialize - und Shutdown-Methoden der Bootstrap-Klasse im .NET-Wrapper für die Bootstrapper-API aufgerufen.

6. Um zu veranschaulichen, dass die Komponenten der Windows App SDK-Runtime ordnungsgemäß geladen wurden, fügen Sie Code hinzu, der die ResourceManager-Klasse im Windows App SDK zum Laden einer Zeichenfolgenressource verwendet.

   1. Fügen Sie Ihrem Projekt eine neue Ressourcendatei (.resw) hinzu (lassen Sie den Standardnamen).

   2. Wenn die Ressourcendatei im Editor geöffnet ist, erstellen Sie eine neue Zeichenfolgenressource mit den folgenden Eigenschaften.

      • Name: Meldung
      • Wert: Hallo, Ressourcen!

   3. Speichern Sie die Ressourcendatei.

   4. Öffnen Sie die Program.cs Codedatei, und ersetzen Sie die Console.WriteLine("Hello, World!"); Zeile durch den folgenden Code.

   // 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. Klicken Sie auf "Ohne Debuggen starten" (oder starten Sie das Debuggen), um Ihre App zu erstellen und auszuführen. Die Zeichenfolge Hello, resources! sollte erfolgreich angezeigt werden.

C++

Befolgen Sie diese Anweisungen, um ein C++-WinUI 3-Projekt zu konfigurieren, das entweder mit externem Speicherort verpackt oder entpackt wird.

1. Erstellen Sie in Visual Studio ein neues C++-Konsolen-App-Projekt. Benennen Sie das Projekt DynamicDependenciesTest.

   

   Nachdem Sie das Projekt erstellt haben, sollten Sie ein "Hello, World!" haben. C++-Konsolen-App.

2. Als Nächstes installieren Sie das Windows App SDK NuGet-Paket im Projekt.

   1. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf den Knoten Verweise, und wählen Sie NuGet-Pakete verwalten aus.
   2. Wählen Sie im NuGet-Paket-Manager-Fenster die Registerkarte "Durchsuchen" aus, und suchen Sie nach Microsoft.WindowsAppSDK.

3. Sie können jetzt die Bootstrapper-API verwenden (siehe Verwenden der Windows App SDK-Laufzeit für Apps, die mit externem Speicherort oder entpackt sind), um die Windows App SDK-Laufzeit in Ihrer App zu initialisieren. Auf diese Weise können Sie die Windows App SDK-APIs in der App verwenden.

   1. Fügen Sie oben in der DynamicDependenciesTest.cpp-Datei die folgenden Includedateien hinzu. Der mddbootstrap.h-Header ist über das Windows App SDK NuGet-Paket verfügbar.

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

   1. Fügen Sie als Nächstes diesen Code am Anfang der Hauptmethode hinzu, um die MddBootstrapInitialize-Funktion aufzurufen, um den Bootstrapper zu initialisieren und alle Fehler zu behandeln. Dieser Code definiert, welche Version des Windows App SDK die App beim Initialisieren des Bootstrappers abhängig ist.

   Wichtig

   Sie müssen den folgenden Code entsprechend Ihrer spezifischen Konfiguration bearbeiten. Sehen Sie sich die Beschreibungen der Parameter der MddBootstrapInitialize-Funktion an, damit Sie eine der Versionen des Windows App SDK angeben können, das Sie installiert haben.

   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. Fügen Sie abschließend diesen Code hinzu, um die Zeichenfolge Hello, World! anzuzeigen und die MddBootstrapShutdown-Funktion aufzurufen, um den Bootstrapper zu entinitialisieren.

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

   1. Der resultierende Code sollte wie folgt aussehen:

   #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. Klicken Sie auf "Ohne Debuggen starten" (oder starten Sie das Debuggen), um Ihre App zu erstellen und auszuführen.

Wenn Ihr Projekt WPF ist

Eine WPF-App (Windows Presentation Foundation) finden Sie unter Verwenden des Windows App SDK in einer WPF-App.

Zugehörige Themen

• Windows App SDK-Bereitstellungsleitfaden für von Framework abhängige gepackte Apps mit externem Speicherort oder nicht gepackte Apps
• Laufzeitarchitektur