Verwenden der winapp CLI mit WinUI

In diesem Handbuch wird gezeigt, wie Sie winapp CLI in der gesamten inneren Schleife einer WinUI 3-App verwenden: Erstellen eines Projekts aus einer offiziellen Vorlage, Erstellen und Starten mit Paketidentität, Debuggen von Abstürze, Suchen von Steuerelementen und APIs, Automatisieren der Benutzeroberfläche und Erstellen eines signierten MSIX-Pakets. Jeder Schritt wird über die Befehlszeile ausgeführt, sodass er in jedem Editor, in CI und mit KI-Codierungs-Agents funktioniert.

WinUI-Projektvorlagen enthalten bereits eine Package.appxmanifest, sodass Sie winapp init für eine WinUI-App nicht ausführen müssen. Wenn Sie einer vorhandenen .NET-App, die WinUI nicht verwendet, paketidentität hinzufügen, lesen Sie stattdessen die Verwendung der winapp CLI mit .NET.

Prerequisites

  • Windows 10 Version 1809 oder höher oder Windows 11.

  • Das .NET SDK, Version 8.0.100 oder höher. Für die experimentellen Reactor-Vorlagen ist das .NET 10 SDK erforderlich. winapp CLI installiert keine Toolchains, daher brechen winapp new und winapp run mit einem Hinweis ab, wenn das .NET SDK fehlt.

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • Entwicklermodus, den Windows benötigt, um die App aus Ihrer Buildausgabe zu registrieren. Aktivieren Sie es unter Einstellungen > System > Für Entwickler. Welche Änderungen dies auf Ihrem Computer vornimmt, finden Sie unter Sicherheit.

Erstellen einer WinUI-App

winapp new Erstellt ein Gerüst für eine WinUI-App aus dem offiziellen Microsoft.WindowsAppSDK.WinUI.CSharp.Templates Paket. Es installiert oder aktualisiert das Vorlagenpaket bei Bedarf und ruft dann dotnet new für Sie auf.

# Pick a template and a name interactively
winapp new

# Or create a NavigationView app without prompts
winapp new --name MyApp --template winui-navview --use-defaults

Führen Sie winapp new --list aus, um die Vorlagen im installierten Paket anzuzeigen. Das Paket enthält die folgenden Vorlagen:

Template Description
winui Minimale leere XAML-App (Standard). Siehe Screenshot
winui-navview XAML-App mit einer NavigationView-Shell. Siehe Screenshot
winui-tabview XAML-App mit einer TabView-Shell. Siehe Screenshot
winui-mvvm XAML-App, die das MVVM-Muster mit CommunityToolkit.Mvvm verwendet. Siehe Screenshot
winui-lib WinUI-Klassenbibliothek
winui-unittest Verpacktes MSTest-Projekt für WinUI-Unit-Tests
reactor, reactor-mvu, reactor-navview, reactor-tabview Experimentell. Nur in C# geschriebene WinUI-Apps ohne XAML

Note

Die Reactor templates verweisen auf Vorabversionen Microsoft.UI.Reactor von Paketen. Ihre APIs können in einer zukünftigen Version geändert oder entfernt werden.

Informationen zu jeder Option finden Sie in der new Befehlsreferenz.

Erstellen und Ausführen mit Identität

Im Projektordner erstellt winapp run das Projekt, installiert die Windows App SDK-Laufzeit, die Ihrer Architektur entspricht, falls sie fehlt, registriert die App mit Paketidentität und startet sie.

cd MyApp
winapp run

winapp run akzeptiert eine Projektdatei, eine Lösungsdatei, einen Ordner, der einen davon enthält, oder einen Ordner mit Buildausgabe:

# A specific project and configuration
winapp run .\MyApp.csproj -c Release --arch arm64

# A solution: winapp CLI finds the single app project and skips libraries and tests
winapp run .\MySolution.sln

# A solution with more than one app project
winapp run .\MySolution.sln --project MyApp

# Build output that you produced yourself
winapp run .\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64

Die winapp-CLI liest die WindowsPackageType-Eigenschaft des Projekts, um zu entscheiden, wie es gestartet werden soll. Ein verpacktes Projekt wird mit Paketidentität ausgeführt. Ein Projekt, das WindowsPackageType auf None festlegt, wird als ungepackte App ohne Identität ausgeführt. Um ein verpacktes Projekt als nicht paketiertes Projekt auszuführen, übergeben Sie die Eigenschaft in der Befehlszeile:

winapp run -p WindowsPackageType=None

Weitere nützliche Optionen sind das --clean Entfernen der vorherigen Registrierung und der gespeicherten Daten der App (LocalState und Einstellungen) für eine neue erste Ausführung, --no-launch zum Registrieren ohne Starten der App und --detach --json zum Zurückgeben der Prozess-ID und zum Beenden, damit Skripts und Agents während der Ausführung der App weiterarbeiten können. Die vollständige Liste finden Sie unter Project mode (.NET SDK-Projekte).

Verwenden Sie stattdessen dotnet run

Verwenden Sie bei Bedarf dotnet rundas Microsoft.Windows.SDK.BuildTools.WinApp NuGet-Paket. Das Paket bindet sich in dotnet run ein, sodass es winapp run aufruft und die App mit Identität startet. Projekte, die Sie mit winapp new erstellen, verweisen bereits auf das Paket, sodass dotnet run ohne zusätzliche Einrichtung funktioniert. Fügen Sie für andere Projekte zuerst das Paket hinzu:

dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease
dotnet run

Sie können WinAppRun* Optionen als winapp run MSBuild-Eigenschaften übergeben, z. B. dotnet run -p:WinAppRunDebugOutput=true. Um die Integration zu deaktivieren, setzen Sie EnableWinAppRunSupport in der Projektdatei auf false. Ausführliche Informationen finden Sie unter dotnet run support.

Debuggen von Abstürzen

Fügen Sie --debug-output hinzu, um OutputDebugString Nachrichten und First-Chance-Ausnahmen zu erfassen, während die App ausgeführt wird. Wenn eine WinUI-App mit einer Stowed Exception fehlschlägt, analysiert winapp CLI das Absturzabbild und druckt den ursprünglichen Fehler- und Aufrufstapel anstelle eines generischen Fehlercodes.

winapp run --debug-output

Fügen Sie --symbols zum Herunterladen von Symbolen für vollständige systemeigene Funktionsnamen hinzu. Da --debug-output die winapp-CLI als Debugger anfügt, können Sie Visual Studio oder einen anderen Debugger nicht an denselben Prozess anfügen. Informationen zum Debuggen mit Ihrer IDE finden Sie unter Debuggen mit winapp CLI. Ausführliche Informationen zur Analyse der stowed-exception finden Sie unter WinUI stowed-exception triage.

Steuerelemente und APIs finden

winapp find-uidurchsucht XAML- und C#-Beispiele aus der WinUI-Galerie und dem Windows Community Toolkit nach Zweck und gibt den Code für ein von Ihnen ausgewähltes Szenario zurück. winapp find-apidurchsucht die Windows- und WinRT-API-Oberfläche, auf die Ihr Projekt verweist, z. B. auf Windows App SDK und Windows SDK-Typen, -Member und -Enumerationen.

# Find a control by what you want to build
winapp find-ui "tabbed layout"

# Get the XAML and C# for one of the returned scenarios
winapp find-ui --id gallery-tabview-1

# Look up an API
winapp find-api NavigationView

Beide Befehle unterstützen --json, sodass KI-Codierungs-Agents sie verwenden können, um Steuerelemente auszuwählen und API-Namen zu überprüfen. Weitere Informationen finden Sie in den Referenzen zu find-ui und find-api.

Benutzeroberfläche automatisieren und überprüfen

winapp uisteuert eine laufende App über Microsoft Benutzeroberflächenautomatisierung. Verwenden Sie es, um die Elementstruktur zu überprüfen, Steuerelemente aufzurufen, auf Zustandsänderungen zu warten und Screenshots zu erstellen. Agents können dieselben Befehle verwenden, um ihre eigenen Änderungen zu überprüfen.

winapp run --detach
winapp ui inspect -a MyApp
winapp ui search Button -a MyApp
winapp ui invoke PART_PaneToggleButton -a MyApp
winapp ui screenshot -a MyApp

Die PART_PaneToggleButton Auswahl zielt auf die Menüschaltfläche in der winui-navview Vorlage ab. Kopieren Sie für Ihre eigenen Steuerelemente einen Selektor aus der Ausgabe von winapp ui inspect oder winapp ui search.

Um die App in Windows Sandbox anstelle des Desktops auszuführen, fügen Sie --on sandbox zu winapp run und winapp ui hinzu. Weitere Informationen finden Sie unter Benutzeroberflächenautomatisierung und Sandbox-Ausführung.

Packen und Signieren

Wenn Sie bereit sind, ein Paket lokal zu testen, generieren Sie ein Entwicklungszertifikat, dessen Herausgeber Ihrem Manifest entspricht, und erstellen und packen Sie das Projekt dann in einem Schritt:

winapp cert generate --manifest .\Package.appxmanifest
winapp pack .\MyApp.csproj -c Release --arch x64 --cert .\devcert.pfx

winapp pack erstellt das Projekt und erzeugt ein signiertes .msix. Informationen zum Kombinieren von Builds für mehrere Architekturen in einem .msixbundle finden Sie unter Pakete für mehrere Architekturen. Das Projekt muss gepackt sein, sodass ein Projekt, das WindowsPackageType auf None festlegt, nicht gepackt werden kann. Bei WinUI-Projekten besitzt der Windows App SDK Build das Manifest, den Einstiegspunkt und die Ressourcengenerierung, also --manifest, --executableund --skip-pri werden nicht akzeptiert.

Das Entwicklungszertifikat ist nur für lokale Tests vorgesehen und verwendet ein Standardkennwort. Bevor Sie Ihre App verteilen, signieren Sie sie mit einem vertrauenswürdigen Zertifikat, z. B. mit winapp az-sign und Azure Trusted Signing. Weitere Informationen finden Sie unter Ein Projekt direkt paketieren und Sicherheit.

Vorhandene WinUI-Projekte

winapp CLI arbeitet mit WinUI-Projekten, die Sie in Visual Studio erstellt haben. Verweisen Sie mit winapp run auf die Projektdatei, die Projektmappendatei oder den Ordner, der eine solche Datei enthält. Übergeben Sie für winapp pack.csproj. Sie können das Erstellen und Debuggen in Visual Studio beibehalten und winapp CLI für Skripts, CI- und Agent-Workflows verwenden.

WinUI mit C++

winapp run erstellt und startet auch C++/WinRT-WinUI-Projekte (.vcxproj), die Sie aus der Visual Studio-Vorlage Leere WinUI-App (gepackt) erstellt haben. Es erstellt das Projekt mit msBuild von Visual Studio, registriert die App mit paketidentität und startet sie:

winapp run .\MyApp.vcxproj

# Or from the folder that contains the project
winapp run .

C++-Projekte benötigen Visual Studio oder Buildtools für Visual Studio mit der Desktopentwicklung mit C++-Workload und C++-WinUI-App-Entwicklungstools. winapp pack erstellt keine .vcxproj-Projekte. Erstellen Sie das MSIX-Paket daher in Visual Studio. Voraussetzungen und Optionen finden Sie unter C++-Projekte (.vcxproj). Informationen zu C++-Apps, die WinUI nicht verwenden, finden Sie unter Using winapp CLI with C++.

Beispiele

  • winui-app: eine verpackte WinUI-App mit Steuerelementen, die für winapp ui-Automatisierung eingerichtet sind
  • winui-unpackaged-app: eine WinUI-App, die ohne Paketidentität ausgeführt wird
  • winui-solution: eine Projektmappe mit mehreren Projekten, die zeigt, wie winapp run das App-Projekt auswählt
  • cpp-winui-app: eine verpackte C++/WinRT WinUI-App (Visual Studio .vcxproj mit XAML), die mit winapp run ausgeführt wird

Nächste Schritte

  • Zuletzt aktualisiert um