Verpacken Ihrer App mithilfe von MSIX mit nur einem Projekt

  • Artikel

MSIX für ein einzelnes Projekt ist ein Feature, mit dem Sie eine verpackte WinUI-3-Desktop-App erstellen können, ohne dass ein separates Paketerstellungsprojekt erforderlich ist. Bei einer WinUI-3-App handelt es sich um eine App, die das Framework der Windows-UI-Bibliothek (WinUI) 3 für die Benutzeroberfläche und das Windows App SDK nutzt. Informationen zum Verpacken einer Desktop-App, die keine WinUI 3-App ist, finden Sie unter Einrichten der Desktopanwendung für MSIX-Verpackungen in Visual Studio.

Die MSIX-Funktion für ein einzelnes Projekt ist als Visual-Studio-Erweiterung verfügbar, die Sie für diese Szenarien verwenden können:

  • Erstellen Sie eine neue WinUI 3-Desktop-App mit der Visual-Studio-Projektvorlage Leere App, gepackt (WinUI 3 in Desktop), die im Lieferumfang des Windows App SDK enthalten ist. Dieses Projekt ist so konfiguriert, dass Ihre Anwendung in einem MSIX-Paket erstellt wird, ohne dass ein separates Paketerstellungsprojekt erforderlich ist.
  • Ändern Sie eine vorhandene WinUI 3-Desktop-App, die ein separates Paketerstellungsprojekt verwendet. Die Änderung umfasst das Entfernen des separaten Paketerstellungsprojekts, wie in der nachstehenden Illustration dargestellt.

Comparing packaging project to single project

Überblick

In diesem Abschnitt werden einige wichtige Details zum MSIX-Feature mit einem Projekt vorgestellt.

Vorteile

Vor der Einführung des MSIX-Features für ein einzelnes Projekt benötigten Sie zum Erstellen einer paketierten WinUI 3-Desktopanwendung zwei Projekte in Ihrer Lösung – Ihr App-Projekt sowie ein zusätzliches Paketerstellungsprojekt für Windows-Anwendungen (siehe Einrichten der Desktopanwendung für MSIX-Verpackungen in Visual Studio). Mit dem MSIX-Feature für ein einzelnes Projekt können Sie Ihre App mit nur einem Projekt für Ihre App entwickeln und erstellen. Das sorgt für eine übersichtlichere Projektstruktur und eine unkompliziertere Entwicklungsumgebung. Beispielsweise müssen Sie das separate Paketerstellungsprojekt nicht mehr als Startup-Projekt auswählen.

Unterstützte Projekttypen

Das MSIX-Feature für ein einzelnes Projekt unterstützt WinUI 3-Vorlagen in Visual Studio (C# und C++) für das Windows App SDK.

Begrenzungen

MSIX für ein einzelnes Projekt unterstützt nur eine einzelne ausführbare Datei im generierten MSIX-Paket. Wenn Sie mehrere ausführbare Dateien in einem einzigen MSIX-Paket kombinieren müssen, müssen Sie weiterhin ein Paketerstellungsprojekt für Windows-Anwendungen in Ihrer Lösung verwenden.

Installieren Sie die MSIX-Pakettools für einzelne Projekte

Die MSIX-Paketierungstools für ein einzelnes Projekt enthalten Visual-Studio-Projektvorlagen, mit denen Sie neue verpackte WinUI 3-Desktop-Apps erstellen können. Diese Tools sind in der Erweiterung des Windows App SDK für Visual Studio enthalten. Installationsanweisungen für das Windows App SDK finden Sie unter Installieren von Tools für das Windows App SDK.

Windows App SDK 0.8 und C# Version von 1.0 Preview 3: Die MSIX-Paketierungstools für ein einzelnes Projekt sind nicht in der Windows App SDK-Erweiterung für Visual Studio für Windows App SDK Version 0.8 oder für C#-Projekte mit bis zu und einschließlich Preview 3 des Windows App SDK 1.0 enthalten. Wenn Sie diese Versionen verwenden, müssen Sie möglicherweise explizit die MSIX-Paketierungstools für einzelne Projekte explizit installieren. Siehe die unten stehenden Informationen:

Sie können dann in Visual Studio bestätigen, dass Sie die Erweiterung installiert haben. Klicken Sie auf Erweiterungen>Erweiterungen verwalten>Installiert>Alle und bestätigen Sie, dass MSIX-Paketierungstools für ein einzelnes Projekts aufgelistet sind.

Erstellen eines neuen Projekts

Wenn Sie Windows App SDK 1.0 Preview 2 oder höher verwenden, können Sie eine neue WinUI 3-basierte App erstellen, die die MSIX-Unterstützung für ein einzelnes Projekt enthält, indem Sie einfach die Vorlage Leere App, verpackt (WinUI 3 in Desktop) verwenden. Weitere Informationen finden Sie unter Erstellen Ihres ersten WinUI 3-Projekts.

Ändern eines vorhandenen Projekts

Führen Sie die Schritte in diesem Abschnitt aus, um eine vorhandene WinUI 3-basierte App zu ändern, die ein separates Paketerstellungsprojekt verwendet. Die Schritte umfassen das Verschieben des Paketmanifests (und andere Unterstützung, die zum Erstellen eines MSIX-Pakets erforderlich sind) in das Anwendungsprojekt und dann das Entfernen des separaten Paketerstellungsprojekts.

Schritt 1: Erstellen oder Öffnen eines vorhandenen Paketerstellungsprojekts

Wenn Sie bereits über eine Lösung für eine WinUI 3-Desktop-App verfügen (siehe WinUI 3-Vorlagen in Visual Studio), die ein Paketerstellungsprojekt für Windows-Anwendungen enthält (siehe Einrichten der Desktopanwendung für MSIX-Verpackungen in Visual Studio), öffnen Sie diese Lösung jetzt in Visual Studio.

Falls nicht, erstellen Sie eine neue WinUI 3-Desktop-App in Visual Studio, indem Sie die Vorlage Leere App, gepackt mit Paketerstellungsprojekt für Windows-Anwendungen (WinUI 3 in Desktop) verwenden. Ihre Lösung sieht etwa wie der folgende Screenshot aus.

A solution using the packaging project

Schritt 2: Bearbeiten Sie die Einstellungen des Anwendungsprojekts

Bearbeiten Sie als Nächstes einige Konfigurationseinstellungen, um das MSIX-Feature für einzelne Projekte zu verwenden. Je nach Projekttyp und Visual-Studio-Version gibt es unterschiedliche Anweisungen.

  1. Doppelklicken Sie im Projektmappen-Explorer auf den Projektknoten für Ihre Anwendung, um die .csproj-Datei im XML-Editor zu öffnen. Fügen Sie dem Hauptelement <PropertyGroup> die folgende XML-Datei hinzu.

    <EnableMsixTooling>true</EnableMsixTooling>
<PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile>

    Wenn Sie fertig sind, sollte das <PropertyGroup>-Element ungefähr wie dieses aussehen.

    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    ...
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>

  2. Speichern Sie Ihre Änderungen und schließen Sie die .csproj-Datei.

  3. Führen Sie je nach Version von Visual Studio eines der folgenden Verfahren aus.

    Für Visual Studio 2022 oder höher:

    1. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf den Ordner Eigenschaften unter dem Projektknoten für Ihre Anwendung und wählen Sie Neues Element...>hinzufügen aus.

    2. Wählen Sie Textdatei aus, benennen Sie die neue Datei launchSettings.json und klicken Sie auf Hinzufügen. Stellen Sie sicher, dass sich die neue Datei im Ordner Eigenschaften des Anwendungsprojekts befindet.

    3. Kopieren Sie die folgenden Einstellungen in die neue Datei. Sie können die Werte nach Bedarf für Ihr Szenario ändern. Der Wert MyApp kann eine beliebige Zeichenkette sein. Er muss nicht mit dem Namen Ihrer Anwendung übereinstimmen.

      {
    "profiles": {
        "MyApp": {
            "commandName": "MsixPackage",
            "commandLineArgs": "", /* Command line arguments to pass to the app. */
            "alwaysReinstallApp": false, /* Uninstall and then reinstall the app. All information about the app state is deleted. */
            "remoteDebugEnabled": false, /* Indicates that the debugger should attach to a process on a remote machine. */
            "allowLocalNetworkLoopbackProperty": true, /* Allow the app to make network calls to the device it is installed on. */
            "authenticationMode": "Windows", /* The authentication scheme to use when connecting to the remote machine. */
            "doNotLaunchApp": false, /* Do not launch the app, but debug my code when it starts. */
            "remoteDebugMachine": "", /* The name of the remote machine. */
            "nativeDebugging": false /* Enable debugging for managed and native code together, also known as mixed-mode debugging. */
        }
    }
}

    4. Speichern und schließen Sie die Datei launchSettings.json.

    Für Visual Studio 2019:

    1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten für Ihre Anwendung und wählen Sie Eigenschaften aus.

    2. Wählen Sie die Registerkarte Debuggen aus und legen Sie die Eigenschaft Starten auf MsixPackage fest. Möglicherweise müssen Sie diese Option zweimal auswählen, wenn sie beim ersten Versuch zurückgesetzt wird.

      Enabling MsixProject option

    3. Speichern Sie die Änderungen.

Schritt 3: Verschieben Sie Dateien in das Anwendungsprojekt

Verschieben Sie als Nächstes mehrere wichtige Dateien in das Anwendungsprojekt. Je nach Projekttyp gibt es unterschiedliche Anweisungen.

  1. Verschieben Sie in Datei-Explorer die Datei Package.appxmanifest und den Ordner Bilder aus Ihrem Paketerstellungsprojekt in Ihr Anwendungsprojekt. Platzieren Sie diese Datei und diesen Ordner auf der obersten Ebene der Ordnerhierarchie des Anwendungsprojekts.
  2. Wählen Sie in Visual Studio in Projektmappen-Explorer alle Bilder im Ordner Bilder mehrfach aus. Legen Sie im Fenster Eigenschaften die Buildaktion auf Inhalt fest.
  3. Entfernen Sie das Paketerstellungsprojekt aus Ihrer Lösung.

Illustration of moving files to main app

Schritt 4: Aktivieren Sie die Bereitstellung in Configuration Manager

  1. Wählen Sie Build>Konfigurations-Manager aus.
  2. Aktivieren Sie in Configuration Manager für jede Kombination aus Konfiguration und Plattform das Kontrollkästchen Bereitstellen (z. B. Debug und x86, Debug und arm64, Release und x64 usw.)

    Hinweis

    Stellen Sie sicher, dass Sie oben die Dropdownlisten Aktive Projektmappenkonfiguration und Aktive Projektmappenplattform anstelle der Dropdownlisten Konfiguration und Plattform in derselben Zeile wie das Kontrollkästchen Bereitstellen verwenden.

Enabling Deploy in Configuration Manager

Schritt 5: Bereitstellen Ihrer App

Erstellen und Bereitstellen Ihrer Anwendung. Visual Studio erstellt Ihre Anwendung in einem MSIX-Paket, installiert das Paket und führt die Anwendung anschließend aus.

Schritt 6: Verpacken der App für die Veröffentlichung

Verwenden Sie den Befehl Verpacken und Veröffentlichen in Visual Studio, um Ihre Anwendung zu verpacken und im Microsoft Store zu veröffentlichen.

Automatisieren des Erstellens und Packens Ihrer MSIX-Einzelprojekt-App

Sie können msbuild verwenden, um Ihre MSIX-App für ein einzelnes Projekt zu erstellen und zu verpacken, wodurch Sie den Workflow automatisieren können. Die Technik für eine Einzelprojektlösung und die Befehlszeile unterscheidet sich nur geringfügig von dem, was Sie möglicherweise bereits tun, wenn Sie eine Lösung mit zwei Projekten haben – eines mit einem Paketerstellungsprojekt für Windows-Anwendungen (siehe Einrichten der Desktopanwendung für MSIX-Verpackungen in Visual Studio).

Die wichtige Buildbefehlsoption für eine Einzelprojektlösung ist /p:GenerateAppxPackageOnBuild=true. Ohne diese Option wird das Projekt erstellt, aber Sie erhalten kein MSIX-Paket. Wenn Sie diese Option einschließen, wird das MSIX-Paket generiert.

Es gibt ein vollständiges Beispiel in Form einer GitHub-Aktion, die eine WinUI 3-Einzelprojektlösung erstellt.

Hinweis

MSIX für ein einzelnes Projekt unterstützt derzeit nicht die Erstellung von MSIX-Bundles (siehe Bündelung von MSIX-Paketen). Es erzeugt nur einen einzigen MSIX. Sie können jedoch .msix-Dateien in einem MSIX-Bündel bündeln, indem Sie die GitHub Action MSIX Bundler verwenden.

Ausführen einer verpackten Desktop-App unter Windows

Einen tieferen Einblick in das, was mit Dateien und Registrierungseinträgen geschieht, wenn Sie ein Windows-Anwendungspaket für Ihre Desktopanwendung erstellen, finden Sie unter Grundlegendes zur Funktion von verpackten Desktop-Apps unter Windows.

Feedback geben

Um uns Ihr Feedback zu senden, Probleme zu melden oder Fragen zum MSIX-Feature mit einem Projekt zu stellen, posten Sie eine Diskussion oder ein Problem im GitHub-Repository des Windows App SDK.