Verwenden der Windows App SDK-Runtime für gepackte Apps mit externem Speicherort oder nicht gepackte Apps

  • Artikel

Hinweis

Wenn Ihre App mithilfe der MSIX-Technologie installiert wird, lesen Sie das Windows App SDK-Bereitstellungshandbuch für frameworkabhängige verpackte Apps.

Wenn Ihre App nicht mithilfe von MSIX installiert ist (d. h. mit externem Speicherort verpackt oder entpackt), müssen Sie das Windows App SDK für die Verwendung initialisieren, bevor Sie Windows App SDK-Features wie WinUI 3, App Lifecycle, MRT Core und DWriteCore aufrufen können. Ihre App muss die Windows App SDK-Laufzeit initialisieren, bevor Sie ein anderes Feature des Windows App SDK verwenden.

  • Ab Windows App SDK 1.0 kann dies automatisch erfolgen, wenn Die App über die automatische Initialisierung gestartet wird (Projekteigenschaft <WindowsPackageType>None</WindowsPackageType>festlegen). Eine Demonstration finden Sie unter Erstellen Ihres ersten WinUI 3-Projekts.
  • Wenn Sie jedoch erweiterte Anforderungen haben (z. B. Fehler behandeln, indem Sie ihre eigene benutzerdefinierte Benutzeroberfläche oder Protokollierung anzeigen oder eine Version des Windows App SDK laden müssen, die sich von der von Ihnen erstellten Version unterscheidet), lesen Sie dieses Thema weiter. In diesen Szenarien können Sie anstelle der automatischen Initialisierung die Bootstrapper-API explizit aufrufen.

Eine der beiden oben genannten Techniken ermöglicht einer App, die MSIX nicht verwendet, um zur Laufzeit eine dynamische Abhängigkeit vom Windows App SDK zu übernehmen.

Hintergrundinformationen zu dynamischen Abhängigkeiten finden Sie unter MSIX-Frameworkpakete und dynamische Abhängigkeiten.

Im Hintergrund und Deaktivieren der automatischen Modulinitialisierung

Der von der WindowsPackageType oben erwähnten Eigenschaft generierte Code nutzt Modulinitialisierer, um die Bootstrapper-API aufzurufen. Der Bootstrapper führt die schwere Hebearbeitung durch, um das Windows App SDK zu finden und den aktuellen Prozess für die Verwendung zu aktivieren. Der generierte Code behandelt sowohl die Initialisierung als auch das Herunterfahren. Sie können das Verhalten der Initialisierung mit den folgenden Projekteigenschaften steuern:

  • <WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
    • Verwenden Sie Standardoptionen.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
    • Verwenden Sie keine Optionen.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
    • Rufen Sie DebugBreak() auf, wenn ein Fehler nur auftritt, wenn ein Debugger an den Prozess angefügt ist.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
    • Führen Sie einen Fehler aus, wenn ein Fehler auftritt.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
    • Fordern Sie den Benutzer auf, die Windows App SDK-Laufzeit zu erwerben, wenn ein übereinstimmende Nicht gefunden werden kann.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Wurde erfolgreich ausgeführt, wenn ein Prozess mit Paketidentität aufgerufen wird (andernfalls tritt ein Fehler auf, und es wird ein Fehler zurückgegeben).

Wenn Ihre App explizite Kontrolle haben soll, können Sie die Boostrapper-API frühzeitig beim Start Ihrer Anwendung direkt aufrufen. In diesem Fall benötigen WindowsPackageType Sie die Projektdatei nicht.

Hinweis

Neben der automatischen Initialisierung und der Bootstrapper-API bietet das Windows App SDK auch eine Implementierung der dynamischen Abhängigkeits-API. Diese API ermöglicht es Ihren entpackten Apps, eine Abhängigkeit von jedem Frameworkpaket (nicht nur dem Windows App SDK-Frameworkpaket) zu übernehmen, und sie wird intern von der Bootstrapper-API verwendet. Weitere Informationen zur dynamischen Abhängigkeits-API finden Sie unter Verwenden der dynamischen Abhängigkeits-API, um zur Laufzeit auf MSIX-Pakete zu verweisen.

Deaktivieren (oder Aktivieren) der automatischen Modulinitialisierung

Die Projekteigenschaft <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> deaktiviert die oben beschriebene automatische Modulinitialisierung (die Bootstrapper-API wird nicht aufgerufen). Dadurch kann Ihre App Verantwortung übernehmen und die Bootstrapper-API direkt aufrufen.

Ab Version 1.2 des Windows App SDK (aus dem stabilen Kanal) gilt die automatische Modulinitialisierung nur für Projekte, die eine ausführbare Datei erzeugen (d. h. die OutputType-Projekteigenschaft ist auf Exe oder WinExe festgelegt). Dies besteht darin, das Hinzufügen von automatischen Initialisierern zu Klassenbibliothek-DLLs und anderen nicht ausführbaren Dateien standardmäßig zu verhindern. Wenn Sie einen automatischen Initialisierer in einer nicht ausführbaren Datei benötigen (z. B. eine test-DLL, die von einer ausführbaren Hostprozessdatei geladen wird, die den Bootstrapper nicht initialisiert), können Sie einen automatischen Initialisierer in Ihrem Projekt explizit mit <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>aktivieren.

Verwenden der Bootstrapper-API

Wichtig

Die unten erwähnte MddBootstrapInitialize2-Funktion ist ab Version 1.1 verfügbar.

Die Bootstrapper-API besteht aus drei C/C++-Funktionen, die in der Headerdatei mddbootstrap.h im Windows App SDK deklariert sind: MddBootstrapInitialize, MddBootstrapInitialize2 und MddBootstrapShutdown. Diese Funktionen werden von der Bootstrapper-Bibliothek im Windows App SDK bereitgestellt. Diese Bibliothek ist eine kleine DLL, die Sie mit Ihrer App verteilen müssen. es ist nicht Teil des Frameworkpakets selbst.

MddBootstrapInitialize2

Diese Funktion initialisiert den Aufrufprozess, um die Version des Windows App SDK-Frameworkpakets zu verwenden, die am besten den Kriterien entspricht, die Sie an die Funktionsparameter übergeben. Dies führt in der Regel dazu, dass auf die Version des Frameworkpakets verwiesen wird, die mit dem Windows App SDK NuGet-Paket übereinstimmt, das installiert ist. Wenn mehrere Pakete den Kriterien entsprechen, wird der beste Kandidat ausgewählt. Diese Funktion muss einer der ersten Aufrufe im Start der App sein, um sicherzustellen, dass die Bootstrapper-Komponente das Windows App SDK ordnungsgemäß initialisieren und den Laufzeitverweis zum Frameworkpaket hinzufügen kann.

Die Bootstrapper-API verwendet die dynamische Abhängigkeits-API, um das Frameworkpaket der Windows App SDK-Laufzeit dem Paketdiagramm des aktuellen Prozesses hinzuzufügen und andernfalls den Zugriff auf das Paket zu ermöglichen.

Diese Funktion initialisiert auch den Dynamic Dependency Lifetime Manager (DDLM). Diese Komponente bietet Infrastruktur, um zu verhindern, dass das Betriebssystem das Windows App SDK-Frameworkpaket gewartet, während es von einer entpackten App verwendet wird.

MddBootstrapShutdown

Diese Funktion entfernt die Änderungen an dem aktuellen Prozess, die durch einen Aufruf von MddBootstrapInitialize vorgenommen wurden. Nachdem diese Funktion aufgerufen wurde, kann Ihre App keine Windows App SDK-APIs mehr aufrufen, einschließlich der dynamischen Abhängigkeits-API.

Mit dieser Funktion wird auch der Dynamic Dependency Lifetime Manager (DDLM) heruntergefahren, sodass Windows das Frameworkpaket bei Bedarf bedienen kann.

.NET-Wrapper für die Bootstrapper-API

Obwohl Sie die C/C++-Bootstrapper-API direkt aus .NET-Apps aufrufen können, erfordert dies die Verwendung des Plattformaufrufs, um die Funktionen aufzurufen . In Windows App SDK 1.0 und höheren Versionen ist ein .NET-Wrapper für die Bootstrapper-API in der Microsoft.WindowsAppRuntime.Bootstrap.Net.dll Assembly verfügbar. Diese Assembly bietet eine einfachere und natürlichere API für .NET-Entwickler, um auf die Funktionalität des Bootstrappers zuzugreifen. Die Bootstrap-Klasse stellt statische Initialize-, TryInitialize- und Shutdown-Funktionen bereit, die Aufrufe der MddBootstrapInitialize- und MddBootstrapShutdown-Funktionen für die meisten gängigen Szenarien umschließen. Ein Beispiel zur Verwendung des .NET-Wrappers für die Bootstrapper-API finden Sie in den C#-Anweisungen im Lernprogramm: Verwenden der Bootstrapper-API in einer App, die mit externem Speicherort verpackt ist oder entpackt wird, die das Windows App SDK verwendet.

Weitere Informationen zum .NET-Wrapper für die Bootstrapper-API finden Sie in den folgenden Ressourcen:

  • Bootstrapper C#-APIs.
  • Abschnitt 6.1.4 der Spezifikation für dynamische Abhängigkeiten.
  • Bootstrap.cs: Die Open Source-Implementierung des .NET-Wrappers für die Bootstrapper-API.

C++-Wrapper für die Bootstrapper-API

Ab Windows App SDK 1.1 ist ein C++-Wrapper für die Bootstrapper-API verfügbar.

Siehe Bootstrapper C++-API.

Deklarieren der Betriebssystemkompatibilität im Anwendungsmanifest

Um die Betriebssystemkompatibilität (Betriebssystemkompatibilität) zu deklarieren und das Windows App SDK-Standardverhalten auf Windows 8 (und potenzielle Abstürze) zu vermeiden, können Sie ein paralleles Anwendungsmanifest mit Ihrem Paket mit externem Speicherort oder entpackten Apps einschließen. Siehe Anwendungsmanifeste (das ist die Datei, in der Dinge wie DPI deklariert sind, und die während des Buildvorgangs in den .exe Ihrer App eingebettet wird). Dies kann ein Problem sein, wenn Sie windows App SDK-Unterstützung zu einer vorhandenen App hinzufügen, anstatt eine neue über eine Visual Studio-Projektvorlage zu erstellen.

Wenn Sie noch nicht über ein paralleles Anwendungsmanifest in Ihrem Projekt verfügen, fügen Sie dem Projekt eine neue XML-Datei hinzu, und nennen Sie sie in Anwendungsmanifesten wie empfohlen. Fügen Sie der Datei das Kompatibilitätselement und die im folgenden Beispiel gezeigten untergeordneten Elemente hinzu. Diese Werte steuern die Quirksebene für die Komponenten, die im Prozess Ihrer App ausgeführt werden.

Ersetzen Sie das ID-Attribut des maxversiontested-Elements durch die Versionsnummer von Windows, auf die Sie abzielen (muss 10.0.17763.0 oder eine höhere Version sein). Beachten Sie, dass das Festlegen eines höheren Werts bedeutet, dass ältere Versionen von Windows Ihre App nicht ordnungsgemäß ausführen, da jede Windows-Version nur von Versionen vorher kennt. Wenn Ihre App also unter Windows 10, Version 1809 (10.0) ausgeführt werden soll; Build 17763), dann sollten Sie entweder den Wert 10.0.17763.0 unverändert lassen oder mehrere maxversiontested-Elemente für die verschiedenen Von Ihrer App unterstützten Werte hinzufügen.

<?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>

Weitere Informationen