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

  • Artikel

Dieses Thema enthält Anleitungen zum Bereitstellen von Apps, die mit einem externen Speicherort gepackt oder entpackt sind und die die Windows App SDK verwenden.

Übersicht

Entwickler von mit externen Speicherorten gepackten und unverpackten Apps sind für die Bereitstellung erforderlicher Windows App SDK Runtime-Pakete für ihre Endbenutzer verantwortlich. Dies kann entweder durch Ausführen des Installers oder durch direkte Installation der MSIX-Pakete erfolgen. Diese Optionen werden im Abschnitt Bereitstellen von Windows App SDK Runtime weiter unten ausführlicher beschrieben.

Gepackt mit externem Speicherort und unverpackten Apps haben auch zusätzliche Laufzeitanforderungen. Sie müssen den Zugriff auf die Windows App SDK Runtime mithilfe der Bootstrapper-API initialisieren. Darüber hinaus kann die API für dynamische Abhängigkeiten verwendet werden, wenn Ihre App neben dem Windows App SDK andere Frameworkpakete verwendet. Diese Anforderungen werden im Abschnitt Laufzeitanforderungen für Apps, die mit externem Speicherort oder unverpackt verpackt sind , ausführlicher beschrieben.

Voraussetzungen

Zusätzliche Voraussetzungen

  • Experimentelle Versionen und Vorschauversionen der Windows App SDK erfordern, dass das Querladen aktiviert ist, um die Runtime zu installieren.

    • Das Querladen wird ab Windows 10 Version 2004 automatisch aktiviert.

    • Wenn auf Ihrem Entwicklungscomputer oder auf dem Bereitstellungscomputer Windows 11 ausgeführt wird, überprüfen Sie, ob das Querladen aktiviert ist:

      • Einstellungen>Datenschutzsicherheit &>für Entwickler. Stellen Sie sicher, dass die Einstellung Entwicklermodus aktiviert ist.

    • Wenn auf ihrem Entwicklungscomputer oder auf dem Bereitstellungscomputer Windows 10 Version 1909 oder einer früheren Version ausgeführt wird, überprüfen Sie, ob das Querladen aktiviert ist:

      • Einstellungen>Aktualisieren & Sicherheit>für Entwickler>Verwenden Sie Entwicklerfeatures. Vergewissern Sie sich, dass Apps quer laden oder der Entwicklermodus ausgewählt ist.

    • Die Einstellung "Entwicklermodus " umfasst das Querladen sowie andere Features.

      Hinweis

      Wenn der Computer in einer Unternehmensumgebung verwaltet wird, gibt es möglicherweise eine Richtlinie, die verhindert, dass diese Einstellungen geändert werden. Wenn Sie in diesem Fall eine Fehlermeldung erhalten, wenn Sie oder Ihre App versucht, die Windows App SDK Runtime zu installieren, wenden Sie sich an Ihren IT-Spezialisten, um das Querladen oder den Entwicklermodus zu aktivieren.

Bereitstellen Windows App SDK Runtime

Gepackt mit externem Speicherort und unverpackten Apps verfügen über zwei Optionen zum Bereitstellen der Windows App SDK Runtime:

Option 1: Verwenden des Installers

Sie können alle Windows App SDK Laufzeitpakete bereitstellen, indem Sie das Installationsprogramm ausführen. Das Installationsprogramm finden Sie unter Downloads für die Windows App SDK. Beim Ausführen des Installers (.exe) sollte eine Ausgabe ähnlich der folgenden angezeigt werden:

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: MicrosoftCorporationII.WindowsAppRuntime.Main.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.Singleton_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x6_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x8_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

All install operations successful.

Sie können das Installationsprogramm ohne Benutzerinteraktion ausführen und die gesamte Textausgabe mit der --quiet Option unterdrücken:

WindowsAppRuntimeInstall.exe --quiet

Sie können auch die Aktualisierung der MSIX-Pakete erzwingen und alle derzeit ausgeführten Windows App SDK Prozesse mithilfe der --force Option herunterfahren. Dieses Feature wird in Version 1.1 eingeführt.

WindowsAppRuntimeInstall.exe --force

Führen Sie aus, um alle Befehlszeilenoptionen des Installers WindowsAppRuntimeInstall --hanzuzeigen.

Nach Abschluss der Installation können Sie Ihr Paket mit einem externen Speicherort oder einer unverpackten App ausführen. Ein Beispiel für das Erstellen und Ausführen eines Pakets mit externem Speicherort oder einer unverpackten App, die den Windows App SDK verwendet, finden Sie unter Tutorial: Verwenden der Bootstrapper-API in einer App, die mit einem externen Speicherort verpackt ist, oder in einer entpackten App, die die Windows App SDK verwendet.

Verketten des Windows App SDK Installers mit dem Setup Ihrer App

Wenn Sie über ein benutzerdefiniertes Setupprogramm für Ihre App verfügen, können Sie den Windows App SDK Setupprozess im Setupprozess Ihrer App verketten. Das Windows App SDK-Installers stellt derzeit keine Standard-Benutzeroberfläche bereit, sodass Sie die Verkettung mithilfe der benutzerdefinierten Benutzeroberfläche Ihres Setups durchführen müssen.

Sie können das Windows App SDK Setup im Hintergrund starten und nachverfolgen, während Sie ihre eigene Ansicht des Setupfortschritts mithilfe von ShellExecute anzeigen. Das Windows App SDK-Installationsprogramm entpackt das Windows-App-MSIX-Paket im Hintergrund und ruft die PackageManager.AddPackageAsync-Methode auf, um die Installation abzuschließen. Dies ähnelt anderen Runtime-Installern, die Sie möglicherweise verwendet haben, z. B. .NET, Visual C++ oder DirectX.

Ein Codebeispiel, das veranschaulicht, wie Sie den Windows App SDK Installer über Ihr Setupprogramm ausführen, finden Sie in der Funktion RunInstaller in den Funktionstests des Installers.

Installationsbeispiel

Im folgenden Beispiel erfahren Sie, wie Sie das Installationsprogramm über ein Win32-Setupprogramm starten, ohne während des Setups ein Konsolenfenster zu öffnen:

Installationsbeispiel erkunden

Problembehandlung

Rückgabecodes

In der folgenden Tabelle sind die gängigsten Rückgabecodes für das Windows App SDK .exe-Installationsprogramm aufgeführt. Die Rückgabecodes sind für alle Versionen des Installationsprogramms identisch.

Rückgabecode Beschreibung
0x0 Die Paketinstallation oder -bereitstellung wurde erfolgreich abgeschlossen.
0x80073d06 Mindestens ein Paket konnte nicht installiert werden.
0x80070005 Eine systemweite Installation oder Bereitstellung war nicht möglich, da die App nicht mit erhöhten Rechten ausgeführt wird oder der Benutzer, der die Installation ausführt, keine Administratorrechte hat.

Installationsfehler

Wenn das Windows App SDK-Installationsprogramm während der Installation einen Fehler zurückgibt, gibt es einen Fehlercode zurück, der das Problem beschreibt.

Option 2: Direktes Bereitstellen Windows App SDK Runtimepakete

Alternativ zur Verwendung des Windows App SDK Installers für die Bereitstellung für Endbenutzer können Sie die MSIX-Pakete manuell über das Programm oder MSI Ihrer App bereitstellen. Diese Option eignet sich am besten für Entwickler, die mehr Kontrolle wünschen.

Ein Beispiel, das veranschaulicht, wie Ihr Setupprogramm die MSIX-Pakete installieren kann, finden Sie unter install.cpp im Windows App SDK Installercode.

Bereitstellungsszenarien

  • Systemweite Installation der Windows App SDK Runtime: Die systemweite Installation ändert den Computer für alle Benutzer, einschließlich neuer Benutzer, die in Zukunft hinzugefügt werden. Wenn die App mit erhöhten Rechten ausgeführt wird und der Benutzer, der die Installation ausführt, Über Administratorrechte verfügt, registriert das Installationsprogramm die MSIX-Pakete systemweit, indem das ProvisionPackageForAllUsersAsync aufgerufen wird. Wenn die systemweite Registrierung nicht erfolgreich ist, wird die Installation nur für den aktuellen Benutzer ausgeführt, der die Installation ausführt. In einer verwalteten Unternehmensumgebung sollte der IT-Administrator in der Lage sein, wie gewohnt für alle Benutzer bereitzustellen.

  • Vom Windows App SDK-Installationsprogramm verteilte Architekturen: Das Windows App SDK-Installationsprogramm ist in den x86Architekturen und x64Arm64 verfügbar. Jede Version des Installers enthält die MSIX-Pakete für diese spezifische Architektur. Wenn Sie beispielsweise die x86-WindowsAppRuntimeInstall.exe auf einem x64- oder Arm64-Gerät ausführen, stellt das Installationsprogramm die Pakete für diese Gerätearchitektur bereit.

  • Alle Windows App SDK MSIX-Pakete sind bereits auf dem Computer installiert: MSIX-Pakete werden an einem systemweiten Speicherort mit nur einer Kopie auf dem Datenträger installiert. Wenn eine App die Installation des Windows App SDK versucht, wenn alle MSIX-Paketabhängigkeiten bereits auf dem Computer installiert sind, wird die Installation nicht ausgeführt.

  • Mindestens eines der Windows App SDK MSIX-Pakete ist nicht auf dem Computer installiert: Versuchen Sie beim Bereitstellen des Windows App SDK immer, alle MSIX-Pakete (Framework, Standard, Singleton, DDLM) zu installieren, um sicherzustellen, dass alle Abhängigkeiten installiert sind und Sie Störungen der Endbenutzerumgebung vermeiden.

Laufzeitanforderungen für Apps, die mit einem externen Speicherort gepackt oder entpackt sind

Apps, die mit einem externen Speicherort gepackt oder entpackt sind, haben zusätzliche Laufzeitanforderungen, um die Windows App SDK Runtime zu verwenden. Dies umfasst das Verweisen und Initialisieren des Windows App SDK Framework-Pakets zur Laufzeit. Darüber hinaus kann die API für dynamische Abhängigkeiten verwendet werden, um auf andere Frameworkpakete außerhalb des Windows App SDK zu verweisen.

Verwenden der Windows App SDK-Laufzeit

Gepackt mit externem Speicherort und unverpackten Apps muss die Bootstrapper-API aufrufen, um die Windows App SDK zur Laufzeit zu verwenden. Dies ist erforderlich, bevor die App Windows App SDK Features wie WinUI, App Lifecycle, MRT Core und DWriteCore verwenden kann. Eine Bootstrapperkomponente ermöglicht es, mit externen Speicherorten und unverpackten Apps die folgenden wichtigen Aufgaben auszuführen:

  • Suchen Sie das Windows App SDK Frameworkpaket, und laden Sie es in das Paketdiagramm der App.
  • Initialisieren Sie den Dynamic Dependency Lifetime Manager (DDLM) für das Windows App SDK Frameworkpaket. Der Zweck des DDLM besteht darin, die Wartung des Windows App SDK Frameworkpakets zu verhindern, während es von einem mit einem externen Speicherort oder einer nicht gepackten App verwendet wird.

Die einfachste Möglichkeit zum Laden der Windows App SDK Runtime für gepackt mit externem Speicherort und nicht gepackten Apps besteht darin, die <WindowsPackageType>None</WindowsPackageType> -Eigenschaft in Ihrer Projektdatei (CSPROJ oder VCXPROJ) festzulegen. Sie können die Bootstrapper-API auch direkt im Startcode Ihrer App aufrufen, um die Initialisierung besser steuern zu können. Weitere Informationen finden Sie unter Verwenden der Windows App SDK Runtime für Apps, die mit einem externen Speicherort verpackt oder entpackt sind, und Tutorial: Verwenden der Bootstrapper-API in einer App, die mit externem Speicherort verpackt oder entpackt ist, die die Windows App SDK verwendet.

Die Unterstützung dynamischer Abhängigkeiten ermöglicht es, mit externen Speicherorten und nicht gepackten Apps ihren vorhandenen Bereitstellungsmechanismus wie MSI oder ein beliebiges Installationsprogramm beizubehalten und die Windows App SDK in ihrer Anwendung zu nutzen. Dynamische Abhängigkeiten können von gepackten, mit externen Speicherorten gepackten und nicht gepackten Apps verwendet werden. obwohl es in erster Linie für die Verwendung mit externem Speicherort und nicht gepackten Apps vorgesehen ist.

Es gibt einen DDLM für jede Version und Architektur des Windows App SDK Framework-Pakets. Dies bedeutet, dass Sie auf einem x64 Computer möglicherweise sowohl über eine x86 als auch über eine x64 Version des DDLM verfügen, um Apps beider Architekturen zu unterstützen.

Verweisen auf andere Frameworkpakete mithilfe der API für dynamische Abhängigkeiten

Wenn Sie Features in anderen Frameworkpaketen außerhalb der Windows App SDK (z. B. DirectX) verwenden möchten, können Sie die API für dynamische Abhängigkeiten aufrufen, die mit externem Speicherort und nicht gepackten Apps verpackt ist. Zusätzlich zur Bootstrapperkomponente bietet der Windows App SDK auch einen breiteren Satz von C/C++-Funktionen und WinRT-Klassen, die die dynamische Abhängigkeits-API implementieren. Diese API ist so konzipiert, dass zur Laufzeit dynamisch auf jedes Frameworkpaket verwiesen wird.

Weitere Informationen finden Sie unter Dynamisches Verwenden von MSIX-Frameworkpaketen aus Ihrer Desktop-App und beispiel für dynamische Abhängigkeiten.

Bereitstellen von WINMD-Dateien auf dem Zielcomputer

Zusammen mit Ihrer App wird empfohlen, windows-Metadatendateien (.winmd) bereitzustellen. Metadaten können zur Laufzeit von verschiedenen APIs und Verhaltensweisen verwendet werden, und ihr Fehlen kann die Funktionalität einschränken oder unterbrechen. Metadaten können beispielsweise verwendet werden, um Objekte über Wohnungsgrenzen hinweg zu marshallen. und die Notwendigkeit, marshallen zu müssen, kann eine Funktion der Computerleistung sein. Da es keine deterministische Möglichkeit gibt, zu wissen, ob Sie Metadaten benötigen, sollten Sie s bereitstellen .winmd, es sei denn, Sie haben große Bedenken hinsichtlich der Größe.