Freigeben über

Verteilen einer entpackten WinUI 3-App

Mit der entpackten Verteilung können Sie eine WinUI 3-App ohne MSIX versenden – nützlich für Unternehmensszenarien, in denen DIE MSIX-Bereitstellung nicht verfügbar ist, oder für Entwickler, die eine herkömmliche ordnerbasierte Installation bevorzugen.

Von Bedeutung

Überprüfen Sie diese Einschränkungen, bevor Sie beginnen. Entpackte WinUI 3-Apps haben Einschränkungen, die sich auf Ihre Verteilungsstrategie auswirken:

  • No single-file EXE – Die Abhängigkeiten der Windows App SDK-Laufzeit und von WinUI 3 müssen als separate Dateien vorhanden sein. Die .NET-Einzeldateipublikationsfunktion (PublishSingleFile) kann sie nicht zu einer ausführbaren Datei bündeln. Sie verteilen immer einen Ordner mit Dateien (oder umschließen sie in einem herkömmlichen Installationsprogramm wie WiX oder Inno Setup).
  • Runtime-Abhängigkeit – Die Windows App SDK Laufzeit muss auf dem Computer des Benutzers vorhanden sein. Sie müssen entweder das Laufzeitinstallationsprogramm mit Ihrer App bündeln oder eine eigenständige Bereitstellung verwenden (wodurch die Ausgabegröße erheblich erhöht wird). Siehe Deploying the Windows App SDK runtime below.
  • No package identity – Ohne ein Paketmanifest kann Ihre App keine manifestbasierten Windows Features verwenden: keine automatischen Updates über app Installer oder Store, keine Registrierung von Hintergrundaufgaben und keine Dateitypzuordnungen oder Anpassung der Kacheln im Startmenü über das Paketmanifest. (Herkömmliche Win32-Mechanismen wie vom Installer geschriebene Registrierungseinträge und Verknüpfungen funktionieren weiterhin.)
  • No MSIX/package-identity Store-Übermittlung – Dieses Verteilungsmodell hat keine Paketidentität und ist nicht als MSIX-Einreichung zum Microsoft Store berechtigt. (Sie können ein herkömmliches Installationsprogramm über den Übermittlungspfad für MSI- oder EXE-Installationsprogramme an den Store übermitteln, aber das ist ein separater Workflow von dem, was in diesem Artikel beschrieben wird.)

Wenn diese Einschränkungen ein Problem darstellen, sollten Sie erwägen, Ihre App zu verpacken (empfohlen für die meisten Apps) oder mit externem Speicherort zu verpacken, um die Paketidentität ohne vollständige MSIX-Konvertierung hinzuzufügen.

Ausführliche Informationen zu allen Verpackungsoptionen finden Sie unter Vor- und Nachteile des Verpackens Ihrer App.

Wenn Sie eine neue oder vorhandene WinUI-App entpacken möchten, führen Sie die folgenden Schritte aus:

Suchen Sie in Ihrer .csproj Datei das erste vorhandene PropertyGroup-Element, das auch OutputType, TargetFramework und andere Eigenschaften enthält.

  • Fügen Sie die Projekteigenschaft WindowsPackageType diesem PropertyGroup hinzu. Legen Sie den Wert der Eigenschaft auf Nonefest.
<Project ...>
  ...
  <PropertyGroup>
    <WindowsPackageType>None</WindowsPackageType><!-- add this -->
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    ...
  </PropertyGroup> 
  ...
</Project>

So starten Sie die App aus Visual Studio (entweder Debugging oder Without Debugging, wählen Sie das Unpackaged Startprofil aus der Dropdownliste Start aus. Wenn das Profil Package ausgewählt ist, wird in Visual Studio ein Bereitstellungsfehler angezeigt. Dieser Schritt ist nicht erforderlich, wenn Sie die Anwendung (.exe) über die Befehlszeile oder über Windows Datei-Explorer starten.

Visual Studio – Start-Dropdown mit hervorgehobenen Startprofil für unverpackte C#-Anwendung

Die Bootstrapper-API

Das Festlegen der <WindowsPackageType>None</WindowsPackageType>-Projekteigenschaft bewirkt, dass der auto-initializer eine Version der Windows App SDK sucht und lädt, die für Ihre App am besten geeignet ist.

Wenn Sie erweiterte Anforderungen haben (z. B. benutzerdefinierte Fehlerbehandlung oder zum Laden einer bestimmten Version der Windows App SDK), können Sie stattdessen die Bootstrapper-API explizit aufrufen. Weitere Informationen finden Sie unter Verwenden Sie das Windows-App-SDK-Laufzeitpaket für Apps, die extern oder nicht verpackt sind, und Tutorial: Verwenden Sie die Bootstrapper-API in einer App, die extern oder nicht verpackt ist und das Windows-App-SDK verwendet.

Weitere Informationen zum Bootstrapper finden Sie unter Bereitstellungsarchitektur und Übersicht für frameworkabhängige Apps.

Bereitstellung der Windows App SDK Laufzeitumgebung

Entpackte WinUI 3-Apps hängen von der Windows App SDK Laufzeit ab, die auf dem Computer des Benutzers installiert wird. Sie haben zwei Optionen, um sicherzustellen, dass die Laufzeit verfügbar ist:

Option 1: Windows App SDK Laufzeitinstallationsprogramm (.exe) (empfohlen)

Fügen Sie das Windows App SDK Laufzeitinstallationsprogramm zusammen mit Ihrer App hinzu. Das Laufzeitinstallationsprogramm ist ein weiterverteilbarer .exe, der die erforderlichen Windows App SDK-Laufzeitpakete installiert. Laden Sie es von der Seite Windows App SDK Versionen herunter, und bündeln Sie es mit Ihrem eigenen Installationsprogramm oder Setupskript. Für vollständige Anweisungen sehen Sie unter Verwenden Sie das Windows App SDK-Runtime für Apps, die mit externem Speicherort gepackt oder unverpackt sind.

Benutzer müssen das Laufzeitinstallationsprogramm einmal ausführen. Nachfolgende App-Updates erfordern keine Erneuteinstallation der Laufzeit, es sei denn, die erforderliche Windows App SDK Version ändert sich.

Option 2: Eigenständige Bereitstellung

Legen Sie <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained> in Ihrer Projektdatei fest, um die Windows App SDK Laufzeit direkt in den Ausgabeordner Ihrer App zu bündeln. Dadurch wird die Laufzeitabhängigkeit entfernt– Benutzer müssen nichts separat installieren.

<PropertyGroup>
  <WindowsPackageType>None</WindowsPackageType>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
</PropertyGroup>

Der Kompromiss: Ihr Ausgabeordner ist erheblich größer (die vollständige Laufzeit ist enthalten), und jedes App-Update trägt die vollständige Laufzeitnutzlast. Verwenden Sie diese Option für einfache Verteilungsszenarien oder wenn Sie nicht steuern können, was auf dem Zielcomputer installiert ist.

Bereitstellen von nicht verpackten Apps, die das Windows App SDK verwenden für die vollständige Laufzeit-Bereitstellungreferenz.

Einschränkung eines Einzeldatei-EXE

Von Bedeutung

Entpackte WinUI 3-Apps können nicht als EXE-Datei veröffentlicht werden. Die Windows App SDK Laufzeit und mehrere WinUI 3-Abhängigkeiten müssen als separate Dateien vorhanden sein — das .NET-Einzeldatei-Publishing-Feature kann sie nicht in einer ausführbaren Datei bündeln.

Wenn für Ihr Szenario eine Einzeldatei-Vertriebserfahrung wichtig ist, sollten Sie die folgenden Alternativen in Betracht ziehen:

  • Verwenden von MSIX-Verpackungen – Benutzer erhalten eine einzige Installationsprogrammumgebung (App Installer behandelt alle Dateien), und Sie erhalten Store-Berechtigung, Paketidentität und integrierte Updates
  • Verwenden Sie ein herkömmliches Installationsprogramm (WiX, Inno Setup) – schließen Sie den Ausgabeordner in ein einzelnes EXE-Installationsprogramm ein, das alle erforderlichen Dateien transparent extrahiert und installiert.
  • Ein anderes Framework verwenden – WPF- und WinForms-Apps mit können eine Einzeldatei-EXE erstellen, obwohl einige native Abhängigkeiten dennoch zur Laufzeit extrahiert werden können

Verteilungsüberlegungen für entpackte Apps

Entpackte WinUI 3-Apps weisen keine Paketidentität auf, was bedeutet, dass sie nicht auf bestimmte Windows Features zugreifen können:

  • Keine automatische Aktualisierung über den App-Installer oder Windows Store
  • Keine Registrierung von Hintergrundaufgaben über das Paketmanifest
  • Keine Dateitypzuordnungen oder Protokollhandler über das Paketmanifest
  • Keine Anpassung der Startmenü-Kacheln über das Paketmanifest

Wenn Sie diese Features benötigen, sollten Sie das Verpacken mit externem Speicherort als mittleren Pfad in Betracht ziehen, der die Paketidentität hinzufügt, ohne dass eine vollständige MSIX-Konvertierung erforderlich ist.

→ Veröffentlichen Sie Ihre erste Windows-App für eine vollständige Übersicht über die Verteilungsoptionen für WinUI 3 und andere Windows-App-Frameworks.

  • Last updated on