Freigeben über

Entpacken einer WinUI 3-App

Verpackungen sind ein wichtiger Bestandteil jedes Windows App SDK Projekts. Ausführliche Informationen zu Ihren Optionen 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