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 Windows App SDK Bereitstellungshandbuch für frameworkabhängige gepackte Apps.

Wenn Ihre App nicht mit MSIX installiert wird (d. h. sie ist mit einem externen Speicherort verpackt oder entpackt), müssen Sie die Windows App SDK zur 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 Runtime initialisieren, bevor Sie ein anderes Feature der Windows App SDK verwenden.

  • Ab Windows App SDK 1.0 kann dies automatisch erfolgen, wenn Ihre App über die automatische Initialisierung gestartet wird (legen Sie die Projekteigenschaft <WindowsPackageType>None</WindowsPackageType>fest). Eine Demonstration finden Sie unter Erstellen Ihres ersten WinUI 3-Projekts.
  • Wenn Sie jedoch erweiterte Anforderungen haben (z. B. die Behandlung von Fehlern durch Anzeigen Ihrer eigenen benutzerdefinierten Benutzeroberfläche oder Protokollierung, oder wenn Sie eine Version der Windows App SDK laden müssen, die sich von der Version unterscheidet, mit der Sie erstellt haben), 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, zur Laufzeit eine dynamische Abhängigkeit vom Windows App SDK.

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

Hinter den Kulissen und Deaktivieren der automatischen Modulinitialisierung

Der von der WindowsPackageType oben genannten Eigenschaft generierte Code nutzt Modulinitialisierer, um die Bootstrapper-API aufzurufen. Der Bootstrapper führt die schwere Hebearbeitung durch, um die Windows App SDK zu finden und den aktuellen Prozess zu aktivieren, um es zu verwenden. Der generierte Code verarbeitet 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 Die 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 ein Fail fast aus, wenn ein Fehler auftritt.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
    • Fordern Sie den Benutzer auf, die Windows App SDK Runtime abzurufen, wenn keine übereinstimmende Runtime gefunden werden kann.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Erfolgreich, wenn in einem Prozess mit Paketidentität aufgerufen wird (andernfalls tritt ein Fehler auf, und es wird ein Fehler zurückgegeben).

Wenn Ihre App explizit gesteuert werden soll, können Sie die Boostrapper-API zu einem frühen Zeitpunkt 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 stellt die Windows App SDK auch eine Implementierung der dynamischen Abhängigkeits-API bereit. Diese API ermöglicht es Ihren nicht gepackten Apps, eine Abhängigkeit von jedem Frameworkpaket (nicht nur vom Windows App SDK Frameworkpaket) zu nehmen, 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 zum Verweisen auf MSIX-Pakete zur Laufzeit.

Deaktivieren der automatischen Modulinitialisierung

Die Project-Eigenschaft <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 (über den 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). Dadurch soll verhindert werden, dass automatisch initialisierer standardmäßig zu Klassenbibliotheks-DLLs und anderen nicht ausführbaren Dateien hinzugefügt werden. 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 explizit einen automatischen Initialisierer in Ihrem Projekt 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 Bootstrapperbibliothek 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 aufrufenden Prozess, um die Version des Windows App SDK Frameworkpakets zu verwenden, die den Kriterien am besten entspricht, die Sie an die Funktionsparameter übergeben. In der Regel führt dies dazu, dass auf die Version des Frameworkpakets verwiesen wird, die mit dem installierten Windows App SDK NuGet-Paket übereinstimmt. Wenn mehrere Pakete die Kriterien erfüllen, wird der beste Kandidat ausgewählt. Diese Funktion muss einer der ersten Aufrufe im Start der App sein, um sicherzustellen, dass die Bootstrapperkomponente die Windows App SDK ordnungsgemäß initialisieren und den Laufzeitverweis zum Frameworkpaket hinzufügen kann.

Die Bootstrapper-API verwendet die API für dynamische Abhängigkeiten, um das Frameworkpaket der Windows App SDK Runtime dem Paketgraphen 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 stellt eine Infrastruktur bereit, um zu verhindern, dass das Betriebssystem das Windows App SDK Frameworkpaket verwaltet, während es von einer nicht gepackten App verwendet wird.

MddBootstrapShutdown

Diese Funktion entfernt die Änderungen am aktuellen Prozess, die durch einen Aufruf von MddBootstrapInitialize vorgenommen wurden. Nachdem diese Funktion aufgerufen wurde, kann Ihre App Windows App SDK-APIs, einschließlich der API für dynamische Abhängigkeiten, nicht mehr aufrufen.

Diese Funktion beendet auch den Dynamic Dependency Lifetime Manager (DDLM), damit Windows das Frameworkpaket nach Bedarf verwalten 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 von Plattformaufrufen , um die Funktionen aufzurufen. In Windows App SDK Version 1.0 und höher ist in der Microsoft.WindowsAppRuntime.Bootstrap.Net.dll Assembly ein .NET-Wrapper für die Bootstrapper-API 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 Funktionen MddBootstrapInitialize und MddBootstrapShutdown für die häufigsten Szenarien umschließen. Ein Beispiel für die Verwendung des .NET-Wrappers für die Bootstrapper-API finden Sie in den C#-Anweisungen in Tutorial: Verwenden der Bootstrapper-API in einer App, die mit externem Speicherort verpackt oder entpackt ist, die die Windows App SDK verwendet.

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

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

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

Weitere Informationen finden Sie unter Bootstrapper C++-API.

Deklarieren der Betriebssystemkompatibilität im Anwendungsmanifest

Um die Betriebssystemkompatibilität zu deklarieren und zu vermeiden, dass die Windows App SDK standardmäßig Windows 8 Verhalten (und potenzielle Abstürze) aufweist, können Sie ein paralleles Anwendungsmanifest mit externem Speicherort oder nicht gepackter App 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 einer vorhandenen App Windows App SDK Unterstützung hinzufügen, anstatt eine neue über eine Visual Studio-Projektvorlage zu erstellen.

Wenn Sie noch kein paralleles Anwendungsmanifest in Ihrem Projekt haben, fügen Sie dem Projekt eine neue XML-Datei hinzu, und benennen Sie sie wie in Anwendungsmanifesten empfohlen. Fügen Sie der Datei das Compatibility-Element und die im folgenden Beispiel gezeigten untergeordneten Elemente hinzu. Diese Werte steuern die Mackenebene 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, die Sie als Ziel verwenden (muss 10.0.17763.0 oder eine höhere Version sein). Beachten Sie, dass das Festlegen eines höheren Werts bedeutet, dass ihre App in älteren Versionen von Windows nicht ordnungsgemäß ausgeführt wird, da jede Windows-Version nur versionen vor ihr kennt. Wenn Sie also möchten, dass Ihre App unter Windows 10, Version 1809 (10.0; Build 17763), dann sollten Sie entweder den Wert 10.0.17763.0 unverändert belassen oder mehrere maxversiontested-Elemente für die verschiedenen Werte hinzufügen, die Ihre App unterstützt.

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