Windows App SDK Bereitstellungshandbuch für frameworkabhängige verpackte Apps

Dieser Artikel enthält Anleitungen zum Bereitstellen frameworkabhängiger verpackter Apps (siehe What is MSIX?), die den Windows App SDK verwenden. Das entsprechende Thema für andere frameworkabhängige Verpackungsoptionen ist das Windows App SDK-Bereitstellungshandbuch für frameworkabhängige Apps, die an einem externen Speicherort verpackt oder nicht verpackt sind.

Overview

Standardmäßig ist Ihr Projekt, wenn Sie es mithilfe einer der WinUI 3-Vorlagen in Visual Studio erstellen, so konfiguriert, dass die App als MSIX-Paket erstellt wird, wobei entweder Einzelprojekt-MSIX verwendet wird (siehe Verpacken Ihrer App mithilfe von Einzelprojekt-MSIX) oder ein Windows Application Packaging-Projekt (siehe Einrichten Ihrer Desktopanwendung für die MSIX-Paketierung in Visual Studio). Anschließend können Sie ein MSIX-Paket für Ihre App erstellen, indem Sie die Anweisungen in Package einer Desktop- oder UWP-App in Visual Studio verwenden. Nachdem Sie ein MSIX-Paket für Ihre Anwendung erstellt haben, stehen Ihnen mehrere Optionen zur Verwaltung Ihrer MSIX-Verteilungzur Verfügung.

Weitere Informationen zu den Paketen, die ihre verpackte App bei Verwendung des Windows App SDK möglicherweise benötigt, finden Sie unter Deployment-Architektur für die Windows App SDK. Dazu gehören die Pakete Framework, Main und Singleton ; die alle von Microsoft signiert und veröffentlicht werden. Es gibt zwei Hauptanforderungen für die Bereitstellung einer verpackten App:

  1. Stellen Sie das Windows App SDK-Frameworkpaket bereit.
  2. Rufen Sie die Bereitstellungs-API auf.

Prerequisites

Bereitstellen des Windows App SDK Framework-Pakets

Das Windows App SDK Frameworkpaket enthält die Windows App SDK Binärdateien, die zur Laufzeit verwendet werden, und es wird mit Ihrer Anwendung installiert. Das Framework verfügt über unterschiedliche Bereitstellungsanforderungen für verschiedene Kanäle des Windows App SDK.

Stabile Version

Wenn Sie eine stabile Releaseversion des Windows App SDK NuGet-Pakets auf Ihrem Entwicklungscomputer installieren und ein Projekt mit einer der bereitgestellten WinUI-Projektvorlagen erstellen, enthält das generierte Paketmanifest eine PackageDependency Element, das eine Abhängigkeit vom Frameworkpaket angibt.

Wenn Sie das App-Paket jedoch manuell mit einem separaten Windows Application Packaging Project erstellen, müssen Sie ein PackageReference in Ihrer Application (package).wapproj-Datei wie folgt deklarieren:

<ItemGroup>
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.260209005">
       <IncludeAssets>build</IncludeAssets>
   </PackageReference>
</ItemGroup>

Diese Paketabhängigkeit stellt sicher, dass das Framework-Paket installiert wird, wenn Ihre App auf einem anderen Computer bereitgestellt wird.

Vorschauversion

Wenn Sie eine Vorschauversion des Windows App SDK NuGet-Pakets auf Ihrem Entwicklungscomputer installieren, wird während der Buildzeit eine Vorschauversion des Windows App SDK Framework-Pakets als NuGet-Paketabhängigkeit bereitgestellt.

Rufen Sie die Bereitstellungs-API auf

Siehe auch Initialize the Windows App SDK.

Die Bereitstellungs-API wird vom Windows App SDK Framework-Paket bereitgestellt und ist im Microsoft.Windows.ApplicationModel.WindowsAppRuntime Namespace verfügbar. Das Windows Anwendungsmodell unterstützt das Deklarieren einer Abhängigkeit von den Haupt- und Singleton-Paketen nicht. Die Bereitstellungs-API ist daher aus folgenden Gründen erforderlich:

  1. So stellen Sie das Singleton-Paket für Features bereit, die nicht im Framework-Paket enthalten sind (z. B. Pushbenachrichtigungen).
  2. Bereitstellen des Hauptpakets, das automatische Updates für das Frameworkpaket aus dem Microsoft Store ermöglicht.

Für verpackte Apps, die nicht über den Store verteilt werden, sind Sie als Entwickler für die Verteilung des Framework-Pakets verantwortlich. Es wird empfohlen, die Bereitstellungs-API aufzurufen, damit alle kritischen Wartungsupdates bereitgestellt werden. Beachten Sie, dass für die Verwendung von Features außerhalb des Framework-Pakets (z. B. Pushbenachrichtigungen) das Singleton-Paket bereitgestellt werden muss (dies kann mit der Bereitstellungs-API erfolgen, oder indem die MSIX-Pakete mithilfe Ihrer eigenen Installationsmethode verteilt werden).

Important

Nur verpackte Apps, die voll vertrauenswürdig sind oder über die eingeschränkte PackageManagement-Funktion verfügen, verfügen über die Berechtigung, die Bereitstellungs-API zum Installieren der Main- und Singleton-Paketabhängigkeiten zu verwenden.

Sie sollten die Bereitstellungs-API aufrufen, nachdem der Prozess Ihrer App initialisiert wurde, aber bevor Ihre App Windows App SDK Laufzeitfeatures verwendet, die das Singleton-Paket verwenden (z. B. Pushbenachrichtigungen). Die wichtigsten Methoden der Bereitstellungs-API sind die statischen GetStatus - und Initialize-Methoden der DeploymentManager-Klasse .

  • Die methode GetStatus gibt den aktuellen Bereitstellungsstatus der derzeit geladenen Windows App SDK Laufzeit zurück. Verwenden Sie diese Methode, um zu ermitteln, ob Windows App SDK Laufzeitpakete installiert werden müssen, bevor die aktuelle App Windows App SDK Features verwenden kann.
  • Die Methode Initialize überprüft, ob alle erforderlichen Pakete für eine Mindestversion vorhanden sind, die von der derzeit geladenen Windows App SDK Laufzeit benötigt wird. Wenn Paketabhängigkeiten fehlen, versucht die Methode, diese fehlenden Pakete zu registrieren. Ab Windows App SDK 1.1 unterstützt die Methode Initialize auch die Option, die Bereitstellung der Windows App SDK Laufzeitpakete zu erzwingen. Dadurch werden jegliche Prozesse der Laufzeitpakete Main und Singleton heruntergefahren, wodurch ihre Dienste unterbrochen werden. Beispielsweise werden während dieser Zeit keine Push-Benachrichtigungen übermittelt. Sie sollten Initialize nur einmal aufrufen. Sie müssen Initialize nicht für Apps aufrufen, die über die Befehle Start Without Debugging und Start Debugging in Visual Studio bereitgestellt werden.

Important

Der Standardwert der eigenschaft Visual Studio<WindowsAppSdkDeploymentManagerInitialize> ist true. Wenn Sie also DeploymentManager.Initialize explizit aufrufen möchten, legen Sie <WindowsAppSdkDeploymentManagerInitialize>false</WindowsAppSdkDeploymentManagerInitialize> in Ihrer Visual Studio Projektdatei fest.

Beispiel-App zur Bereitstellungs-API

Weitere Anleitungen zur Verwendung der GetStatus - und Initialize-Methoden der DeploymentManager-Klasse finden Sie in der verfügbaren Beispiel-App.

Beispiel-App für Bereitstellungs-API kennenlernen

Beheben von Installationsfehlern

Wenn bei der Installation der Windows App SDK Laufzeitpakete ein Fehler auftritt, wird ein Fehlercode zurückgegeben, der das Problem beschreibt.

Die folgende Tabelle enthält allgemeine Fehlercodes aus der Bereitstellungs-API und deren typische Ursachen:

Fehlercode Name Übliche Ursache
0x80070005 ACCESS_DENIED Die App ist nicht voll vertrauenswürdig oder verfügt nicht über die eingeschränkte PackageManagement-Funktion . Führen Sie die erforderliche Funktion mit erhöhten Rechten aus, oder fügen Sie sie hinzu.
0x80073CF0 ERROR_INSTALL_OPEN_PACKAGE_FAILED Das MSIX-Paket ist beschädigt oder nicht zugänglich. Überprüfen Sie, ob die Paketdatei intakt ist und der Pfad korrekt ist.
0x80073CF3 ERROR_INSTALL_PREREQUISITE_FAILED Ein erforderliches Abhängigkeitspaket fehlt oder ist nicht kompatibel. Stellen Sie sicher, dass das VCLibs-Frameworkpaket und alle anderen erforderlichen Komponenten installiert sind.
0x80073D06 ERROR_PACKAGES_IN_USE Mindestens ein Paket wird verwendet und kann nicht aktualisiert werden. Schließen Sie alle Apps mit der Windows App SDK Laufzeit, und versuchen Sie es dann erneut.
0x80073CFB ERROR_PACKAGE_ALREADY_EXISTS Die Paketversion ist bereits registriert. Dies ist informational – Ihre App kann fortfahren.
0x80073CF9 ERROR_INSTALL_FAILED Ein allgemeiner Installationsfehler. Weitere Details finden Sie in den Ereignisprotokollen (siehe unten).

Tip

Eine vollständige Liste der MSIX-Paketinstallationsfehlercodes finden Sie unter "Problembehandlung beim Packen, Bereitstellen und Abfragen von Windows-Apps".

Wenn der Fehlercode nicht genügend Informationen bereitstellt, finden Sie weitere Diagnoseinformationen in den detaillierten Ereignisprotokollen (siehe Abrufen von Diagnoseinformationen). Ereignisprotokolle befinden sich in Ereignisanzeige unter Anwendungs- und Dienstprotokolle>Microsoft>Windows>AppxDeployment-Server.

Wenn Fehler auftreten, die Sie nicht diagnostizieren können, speichern Sie ein Problem im WindowsAppSDK GitHub Repo mit dem Fehlercode und den Ereignisprotokollen, damit wir das Problem untersuchen können.

  • Last updated on