Verwenden der winapp CLI mit .NET

Dieser Leitfaden sollte für die meisten .NET Projekttypen funktionieren. Die Schritte wurden sowohl mit Konsolen- als auch ui-basierten Projekten wie WPF getestet. Für Arbeitsbeispiele lesen Sie die Beispiele dotnet-app (Konsole) und wpf-app (WPF) im Beispielordner.

In diesem Handbuch wird veranschaulicht, wie Sie die cli winapp mit einer .NET Anwendung zum Debuggen mit Paketidentität und Verpacken Ihrer Anwendung als MSIX verwenden.

Die Paketidentität ist ein Kernkonzept im Windows app-Modell. Sie ermöglicht Ihrer Anwendung den Zugriff auf bestimmte Windows-APIs (z. B. Benachrichtigungen, Sicherheit, AI-APIs usw.), eine Benutzeroberfläche für die Neuinstallation/Deinstallation und vieles mehr.

Eine Standard-Ausführungsdatei (wie eine, die mit dotnet build erstellt wurde) hat keine Paketidentität. In diesem Handbuch wird gezeigt, wie Sie es zum Debuggen hinzufügen und dann für die Verteilung verpacken.

Voraussetzungen

1. .NET SDK: Installieren Sie das .NET SDK (erfordert einen Neustart nach der Installation):

   winget install Microsoft.DotNet.SDK.10 --source winget
   

2. winapp CLI: Installieren Sie das winapp Tool über winget (oder aktualisieren Sie, falls bereits installiert):

   winget install Microsoft.winappcli --source winget
   

1. Erstellen einer neuen .NET App

Erstellen Sie zunächst eine einfache .NET Konsolenanwendung:

dotnet new console -n dotnet-app
cd dotnet-app

Führen Sie sie aus, um sicherzustellen, dass alles funktioniert:

dotnet run

Die Ausgabe sollte "Hallo, Welt!" sein.

2. Aktualisieren von Code zum Überprüfen der Identität

Wir aktualisieren die App, um zu überprüfen, ob sie mit Paketidentität ausgeführt wird. Wir verwenden die Windows-Runtime-API für den Zugriff auf die Paket-APIs.

Aktualisieren Sie zunächst Ihre project-Datei auf eine bestimmte Windows SDK-Version. Öffnen Sie dotnet-app.csproj, und ändern Sie die TargetFramework, um die Windows SDK-Version einzuschließen:

  <TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>

Dadurch erhalten Sie Zugriff auf Windows-Runtime APIs, ohne dass zusätzliche Pakete erforderlich sind.

Ersetzen Sie nun den Inhalt Program.cs durch den folgenden Code. Dieser Code versucht, die aktuelle Paketidentität mithilfe der Windows-Runtime-API abzurufen. Wenn er erfolgreich ist, wird der Paketfamilienname gedruckt. andernfalls wird "Nicht verpackt" gedruckt.

using Windows.ApplicationModel;

try
{
    var package = Package.Current;
    var familyName = package.Id.FamilyName;
    Console.WriteLine($"Package Family Name: {familyName}");
}
catch (InvalidOperationException)
{
    // Thrown when app doesn't have package identity
    Console.WriteLine("Not packaged");
}

3. Ohne Identität ausführen

Führen Sie nun die App wie gewohnt aus:

dotnet run

"Sie sollten die Ausgabe 'Nicht verpackt' angezeigt sehen." Dadurch wird bestätigt, dass die standardmäßige ausführbare Datei ohne Paketidentität ausgeführt wird.

4. Projekt mit winapp CLI initialisieren

Der Befehl winapp init erkennt automatisch .csproj-Dateien und führt ein .NET-spezifisches Setup aus. Es richtet alles ein, was Sie in einem Schritt benötigen: Überprüft Ihre TargetFramework, fügt erforderliche NuGet-Pakete hinzu, generiert das App-Manifest und Ressourcen.

Führen Sie den folgenden Befehl aus, und folgen Sie den Eingabeaufforderungen:

winapp init

Wenn Sie dazu aufgefordert werden:

• Paketname: Drücken Sie die EINGABETASTE, um die Standardeinstellung zu akzeptieren (dotnet-app)
• Publisher Name: Drücken Sie die EINGABETASTE, um die Standardeinstellung zu akzeptieren oder Ihren Namen einzugeben.
• Version: Drücken Sie die EINGABETASTE, um 1.0.0.0 zu akzeptieren.
• Description: Drücken Sie die EINGABETASTE, um die Standardeinstellung (Windows Anwendung) zu akzeptieren, oder geben Sie eine Beschreibung ein.
• Windows App SDK-Setup: Wählen Sie „Stable“, „Preview“ oder „Experimental“ (bestimmt, welche Windows App SDK-Version hinzugefügt wird)
• TargetFramework update: Wenn Ihr TargetFramework keine unterstützte Windows SDK-Version enthält, werden Sie aufgefordert, es zu aktualisieren (z. B. auf net10.0-windows10.0.26100.0)
• Entwicklermodus: Wenn Sie zu "Entwicklermodus" aufgefordert werden, können Sie sie aktivieren, wenn Sie möchten, aber beachten Sie, dass sie Administratorrechte erfordert.

Dieser Befehl bewirkt Folgendes:

• Aktualisieren Sie das TargetFramework in Ihrem .csproj bei Bedarf auf ein unterstütztes Windows-TFM.
• Fügen Sie Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools und Microsoft.Windows.SDK.BuildTools.WinApp NuGet-Paketverweise zu Ihrem .csproj
• Erstellen Package.appxmanifest und Assets Ordner für Ihre App-Identität

Sie können Package.appxmanifest öffnen, um Eigenschaften wie den Anzeigenamen, den Herausgeber und die Funktionen weiter anzupassen.

So überprüfen Sie, ob die Pakete zu Ihrem Projekt hinzugefügt wurden:

dotnet list package

In der Ausgabe sollte Microsoft.WindowsAppSDK und Microsoft.Windows.SDK.BuildTools angezeigt werden.

Ausführungsalias hinzufügen (für Konsolen-Apps)

Da wir eine Konsolen-App erstellen, müssen wir sicherstellen, dass dotnet run die Konsolenausgabe im aktuellen Terminal erhalten bleibt. Standardmäßig startet dotnet run die verpackte App über die AUMID-Aktivierung, wodurch ein neues Fenster geöffnet wird. Dieses wird sofort geschlossen, sobald die Konsolen-App ihre Ausführung beendet, und verwirft dabei jegliche Ausgaben.

Um dies zu beheben, fügen Sie dem Manifest einen Ausführungsalias hinzu und weisen die Ausführungsintegration stattdessen an, über diesen Alias zu starten.

Skip diesen Schritt, wenn Sie eine UI-App erstellen (WPF, WinForms, WinUI). Diese Apps rendern ihr eigenes Fenster, sodass der standardmäßige AUMID-Start das gewünschte ist.

1. Fügen Sie Ihrem Manifest den Ausführungsalias hinzu:

   winapp manifest add-alias
   

   Dies fügt einen uap5:ExecutionAlias zu Package.appxmanifest hinzu (standardmäßig der EXE-Name Ihres Projekts), sodass die App mittels eines Namens von einem Terminal gestartet werden kann.

2. Teilen Sie der dotnet run-Integration mit, den Alias zu verwenden. Öffnen Sie dotnet-app.csproj und fügen Sie das Folgende in einem beliebigen <PropertyGroup> ein (oder erstellen Sie bei Bedarf ein neues <PropertyGroup>).

   <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
   

   Mit diesem Eigenschaftensatz dotnet run startet die App über den Ausführungsalias und erbt den stdin/stdout/stderr des aktuellen Terminals, sodass die Konsolenausgabe inline angezeigt wird.

5. Debuggen mit Identität

Da winapp init das Microsoft.Windows.SDK.BuildTools.WinApp NuGet-Paket zu Ihrem Projekt hinzugefügt hat, können Sie einfach folgendes ausführen:

dotnet run

Dadurch wird automatisch winapp run unter der Haube aufgerufen – erstellen Sie ein loses Layoutpaket, registrieren Sie es mit Windows, und starten Sie Ihre App mit vollständiger Paketidentität.

Die Ausgabe sollte ähnlich wie folgt angezeigt werden:

Package Family Name: dotnet-app_12345abcde

Dadurch wird bestätigt, dass Ihre App mit einer gültigen Paketidentität ausgeführt wird!

Alternative: Manuell winapp run

Wenn Sie das NuGet-Paket winapp init entfernt haben oder nicht verwendet haben, können Sie manuell kompilieren und ausführen.

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

So fügen Sie das NuGet-Paket wieder hinzu: dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Alternative: Sparse Paketidentität

Wenn Sie ein geringes Paketverhalten speziell benötigen (Identität ohne Kopieren von Dateien), können Sie stattdessen verwenden create-debug-identity . Dadurch wird ein sparse Paket registriert, das auf Ihre Exe zeigt, anstatt ein loses Layout zu erstellen:

winapp create-debug-identity .\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Führen Sie dann die ausführbare Datei direkt aus (verwenden Sie dotnet run nicht, da sie die Datei neu erstellen/überschreiben kann):

.\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Alternative: Manuelles MSBuild-Ziel

Wenn Sie das NuGet-Paket nicht verwenden möchten, können Sie ein benutzerdefiniertes MSBuild-Ziel hinzufügen, das nach Debug-Builds den Vorgang create-debug-identity ausführt. Fügen Sie dies am Ende der .csproj-Datei direkt vor dem schließenden </Project>-Tag hinzu:

  <!-- Automatically apply debug identity after Debug builds -->
  <Target Name="ApplyDebugIdentity" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
    <Exec Command="winapp create-debug-identity &quot;$(TargetDir)$(TargetName).exe&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Wendet mit dieser Konfiguration dotnet build die Debugidentität an, und Sie können die ausführbare Datei direkt ausführen. Beachten Sie, dass dotnet run die Identität neu erstellen und überschreiben kann. Führen Sie die exe daher manuell nach dem Build aus.

Wenn Sie dies überspringen möchten: Wenn Sie die explizite Kontrolle darüber bevorzugen, wann die Identität angewendet wird, oder wenn Sie an Code arbeiten, der für den großteil Ihres Entwicklungszyklus keine Identität benötigt, ist der oben genannte manuelle Ansatz möglicherweise einfacher.

6. Verwenden von Windows App SDK (Optional)

Mit dem Windows App SDK erhalten Sie Zugriff auf moderne Windows-APIs, die über das grundlegende Windows SDK hinausgehen– z. B. das Benachrichtigungssystem, Fenster-APIs, App-Lebenszyklusverwaltung und KI auf dem Gerät. Wenn Ihre App eine dieser Funktionen benötigt, ist dieser Schritt für Sie vorgesehen. Wenn Sie nur die Paketidentität für die Verteilung benötigen, können Sie mit Schritt 7 fortfahren.

Wenn Sie winapp init (Schritt 4) ausgeführt haben, wurde Microsoft.WindowsAppSDK bereits als NuGet-Paketreferenz zu Ihrem .csproj hinzugefügt. Sie können mit dotnet list package überprüfen. Wenn Sie das SDK-Setup während der Initialisierung übersprungen haben oder es manuell hinzufügen müssen, führen Sie den folgenden Befehl aus:

dotnet add package Microsoft.WindowsAppSDK

Aktualisieren der Datei "Program.cs"

Ersetzen Sie den gesamten Inhalt von Program.cs durch den folgenden Code, der eine Windows-App Laufzeitversionsprüfung hinzufügt:

using Windows.ApplicationModel;

class Program
{
    static void Main(string[] args)
    {
        try
        {
            var package = Package.Current;
            var familyName = package.Id.FamilyName;
            Console.WriteLine($"Package Family Name: {familyName}");
            
            // Get Windows App Runtime version using the API
            var runtimeVersion = Microsoft.Windows.ApplicationModel.WindowsAppRuntime.RuntimeInfo.AsString;
            Console.WriteLine($"Windows App Runtime Version: {runtimeVersion}");
        }
        catch (InvalidOperationException)
        {
            // Thrown when app doesn't have package identity
            Console.WriteLine("Not packaged");
        }
    }
}

Erstellen und Ausführen

Erstellen Sie die Anwendung neu, und führen Sie sie mit Windows App SDK aus. Da wir die WinAppSDK hinzugefügt haben, müssen wir die Registrierung mit der Identität erneut durchführen, damit winapp die Laufzeitabhängigkeit hinzufügt. Wenn Sie das WinApp NuGet-Paket hinzugefügt haben (empfohlen), führen Sie einfach den Befehl dotnet run aus. Andernfalls (ersetzen Sie dotnet-app durch den Projektnamen):

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Nun sollte die Ausgabe wie folgt angezeigt werden:

Package Family Name: dotnet-app.debug_12345abcde
Windows App Runtime Version: 8000.770.947.0

Das Windows App SDK NuGet-Paket enthält alle erforderlichen Assemblys für den Zugriff auf moderne Windows-APIs, einschließlich:

• Benachrichtigungen und Live-Kacheln
• Fenster- und App-Lebenszyklus
• Pushbenachrichtigungen
• Und viele weitere Windows App SDK Komponenten

Weitere Informationen zur erweiterten Windows App SDK-Verwendung finden Sie in der Dokumentation Windows App SDK.

7. Paket mit MSIX

Sobald Sie bereit sind, Ihre App zu verteilen, können Sie sie mit demselben Manifest als MSIX verpacken.

Build für Veröffentlichung

Erstellen Sie zunächst Ihre Anwendung im Releasemodus, um eine optimale Leistung zu erzielen:

dotnet build -c Release

Generieren eines Entwicklungszertifikats

Vor dem Verpacken benötigen Sie ein Entwicklungszertifikat zum Signieren. Generieren Sie eines, falls Sie das noch nicht getan haben.

winapp cert generate --if-exists skip

Signieren und Packen

Jetzt können Sie packen und signieren. Führen Sie den Packbefehl auf den Ordner mit dem Build-Output aus (ersetzen Sie dotnet-app und den TFM-Pfad durch die Werte Ihres Projekts):

# package and sign the app with the generated certificate
winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --manifest .\Package.appxmanifest --cert .\devcert.pfx 

Hinweis: Der pack Befehl verwendet automatisch das Package.appxmanifest aus Ihrem aktuellen Verzeichnis und kopiert es vor dem Verpacken in den Zielordner. Die generierte MSIX-Datei befindet sich im aktuellen Verzeichnis.

Installieren des Zertifikats

Bevor Sie das MSIX-Paket installieren können, müssen Sie das Entwicklungszertifikat installieren. Führen Sie diesen Befehl als Administrator aus:

winapp cert install .\devcert.pfx

Installieren und Ausführen

Installieren Sie das Paket, indem Sie auf die generierte *.msix-Datei doppelklicken.

Jetzt können Sie Ihre App von praktisch überall im Terminal ausführen, indem Sie Folgendes eingeben:

dotnet-app

Die Ausgabe "Paketfamilienname" sollte angezeigt werden, wobei bestätigt wird, dass sie installiert ist und mit Identität ausgeführt wird.

Tipps

1. Sobald Sie bereit für die Verteilung sind, können Sie Ihr MSIX mit einem Codesignaturzertifikat von einer Zertifizierungsstelle signieren, damit Ihre Benutzer kein selbstsigniertes Zertifikat installieren müssen.
2. Der Microsoft Store signiert das MSIX für Sie, sodass Sie vor der Übermittlung nicht unterschreiben müssen.
3. Möglicherweise müssen Sie mehrere MSIX-Pakete erstellen, eine für jede architektur, die Sie unterstützen (x64, Arm64). Verwenden Sie das -r-Flag mit dotnet build, um bestimmte Architekturen ins Visier zu nehmen: dotnet build -c Release -r win-x64 oder dotnet build -c Release -r win-arm64.

Automatisieren von MSIX Packaging (Optional)

Um die MSIX-Verpackung als Teil Ihrer Releasebuilds zu automatisieren, fügen Sie dieses Ziel zu Ihrer .csproj Datei hinzu (Sie können es zusammen mit dem Debugidentitätsziel hinzufügen):

  <!-- Automatically package as MSIX after Release builds -->
  <Target Name="PackageMsix" AfterTargets="Build" Condition="'$(Configuration)' == 'Release'">
    <!-- Package and sign directly from build output -->
    <Exec Command="winapp pack &quot;$(TargetDir.TrimEnd('\'))&quot; --cert &quot;$(ProjectDir)devcert.pfx&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Mit dieser Konfiguration:

• Das Erstellen im Releasemodus (dotnet build -c Release) erstellt automatisch das MSIX-Paket.
• Das MSIX ist gepackt und mit Ihrem Entwicklungszertifikat signiert.
• Die endgültige .msix Datei befindet sich im Stammverzeichnis des Projekts.

Sie können auch eine benutzerdefinierte Konfiguration (z. B. PackagedRelease) erstellen, indem Sie die Bedingung zu '$(Configuration)' == 'PackagedRelease' ändern.

Nächste Schritte

• Distribute via winget: Übermitteln Sie Ihren MSIX an das Windows Paket-Manager Community-Repository
• Publish to the Microsoft Store: Verwenden Sie winapp store, um Ihr Paket zu übermitteln.
• Set up CI/CD: Verwenden Sie die setup-WinAppCli GitHub Action, um die Paketerstellung in Ihrer Pipeline zu automatisieren.
• Explore Windows-APIs: Mit Paketidentität können Sie jetzt Benachrichtigungen, gerätenahe KI und andere identitätsabhängige APIs verwenden.