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

In diesem Artikel erfahren Sie, wie Sie eine App konfigurieren, die nicht mithilfe von MSIX installiert ist (d. h. sie ist mit einem externen Speicherort verpackt oder entpackt), um die Bootstrapper-API so zu verwenden, dass die Windows App SDK Runtime explizit geladen und Windows App SDK APIs aufgerufen wird. Apps, die nicht über MSIX installiert werden, enthalten Apps, die mit einem externen Speicherort gepackt sind, und nicht gepackte 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 zur automatischen 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 unter Verwenden der Windows App SDK Runtime für Apps, die mit einem externen Speicherort verpackt oder entpackt sind.

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

Bevor Sie dieses Tutorial abschließen, sollten Sie die Laufzeitarchitektur überprüfen, um mehr über die Framework-Paketabhängigkeit zu erfahren, die Ihre App akzeptiert, wenn sie die Windows App SDK verwendet, und die zusätzlichen Komponenten, die erforderlich sind, um in einem mit einem externen Speicherort oder einer nicht gepackten App zu arbeiten.

Voraussetzungen

1. Installieren von Tools für das Windows App SDK.
2. Stellen Sie sicher, dass alle Abhängigkeiten für mit externem Speicherort gepackte und nicht gepackte Apps installiert sind (siehe Windows App SDK Bereitstellungshandbuch für frameworkabhängige Apps, die mit externem Speicherort verpackt oder entpackt sind). Eine einfache Möglichkeit ist die Ausführung des Windows App SDK Runtime-Installers.

Instructions

Sie können dieses Tutorial mithilfe eines C#- oder C++-Projekts befolgen.

Hinweis

Die dynamischen Abhängigkeiten und Bootstrapper-APIs schlagen fehl, wenn sie von einem Prozess mit erhöhten Rechten aufgerufen werden. Daher sollte Visual Studio nicht mit erhöhten Rechten gestartet werden. Weitere Informationen finden Sie unter Dynamische Abhängigkeiten unterstützen keine Erhöhung #567 .

C#

Befolgen Sie diese Anweisungen, um ein C#-WinUI 3-Projekt zu konfigurieren, das entweder mit einem externen Speicherort gepackt oder entpackt ist.

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

2. Konfigurieren Sie als Nächstes Ihr Projekt.

   1. Klicken Sie in 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 Target Framework-Moniker. Verwenden Sie beispielsweise Folgendes, wenn Ihre App auf Windows 10, Version 2004, abzielt.

   <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, winUI 3 unterstützt diese Plattform jedoch nicht.

   1. Wählen Sie Erstellen>Configuration Manager aus.
   2. Wählen Sie die Dropdownliste unter Aktive Lösungsplattform aus, und klicken Sie auf Neu , um das Dialogfeld Neue Projektmappenplattform zu öffnen.
   3. Wählen Sie in der Dropdownliste unter Typ oder wählen Sie die neue Plattformx64 aus.
   4. Klicken Sie auf OK , um das Dialogfeld Neue Projektmappenplattform zu schließen.
   5. Klicken Sie in Configuration Manager auf Schließen.

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

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

5. Sie sind jetzt bereit, die Bootstrapper-API (siehe Verwenden der Windows App SDK Runtime für Apps, die mit einem externen Speicherort verpackt oder entpackt sind) zu verwenden, um dynamisch eine Abhängigkeit vom Windows App SDK Frameworkpaket zu nehmen. Dadurch können Sie die Windows App SDK-APIs in Ihrer App verwenden.

   Öffnen Sie die Codedatei Program.cs , und ersetzen Sie den Standardcode durch den folgenden Code, um die Bootstrap.Initialize-Methode aufzurufen, um den Bootstrapper zu initialisieren. Dieser Code definiert, von welcher 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 Bootstrap.Initialize-Methode an, damit Sie eine der Versionen der installierten Windows App SDK angeben können.

   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 Stamm ist die Bootstrapper-API eine native C/C++-API, mit der Sie die Windows App SDK-APIs in Ihrer App verwenden können. In einer .NET-App, die die 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 nativen 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 Windows App SDK Laufzeitkomponenten 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 (behalten Sie den Standardnamen bei).

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

      • Name: Nachricht
      • Wert: Hallo, Ressourcen!

   3. Speichern Sie die Ressourcendatei.

   4. Öffnen Sie die Codedatei Program.cs , 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 Starten ohne Debuggen (oder Debuggen starten), 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 einem externen Speicherort gepackt oder entpackt ist.

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

   

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

2. Installieren Sie als Nächstes das Windows App SDK NuGet-Paket in Ihrem 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 Fenster NuGet-Paket-Manager 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 Runtime für Apps, die mit einem externen Speicherort verpackt oder entpackt sind), um die Windows App SDK Runtime in Ihrer App zu initialisieren. Dadurch können Sie die Windows App SDK-APIs in der App verwenden.

   1. Fügen Sie am Anfang der Datei DynamicDependenciesTest.cpp die folgenden Includedateien hinzu. Der Mddbootstrap.h-Header ist über das nuGet-Paket Windows App SDK verfügbar.

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

   1. Fügen Sie als Nächstes diesen Code am Anfang Ihrer Standard-Methode hinzu, um die MddBootstrapInitialize-Funktion aufzurufen, um den Bootstrapper zu initialisieren und alle Fehler zu behandeln. Dieser Code definiert, von welcher 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 der installierten Windows App SDK angeben können.

   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 schließlich diesen Code hinzu, um die Zeichenfolge Hello, World! anzuzeigen, und rufen Sie die MddBootstrapShutdown-Funktion auf, um den Bootstrapper zu initialisieren.

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

   1. Ihr endgültiger 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 Starten ohne Debuggen (oder Debuggen starten), um Ihre App zu erstellen und auszuführen.

Wenn Ihr Projekt WPF ist

Informationen zu einer Windows Presentation Foundation -App (WPF) finden Sie unter Verwenden der Windows App SDK in einer WPF-App.

Zugehörige Themen

• Windows App SDK-Bereitstellungsleitfaden für frameworkabhängige gepackte Apps mit externem Speicherort oder nicht gepackte Apps
• Architektur des Laufzeitmoduls