Utilisation de winapp CLI avec WinUI

Ce guide montre comment utiliser l’interface CLI winapp tout au long de la boucle interne d’une application WinUI 3 : créez un projet à partir d’un modèle officiel, générez et lancez-le avec l’identité du package, déboguez les plantages, recherchez des contrôles et DES API, automatisez l’interface utilisateur et produisez un package MSIX signé. Chaque étape s’exécute à partir de la ligne de commande, de sorte qu’elle fonctionne dans n’importe quel éditeur, dans CI et avec les agents de codage IA.

Les modèles de projet WinUI incluent déjà un Package.appxmanifest. Vous n’avez donc pas besoin d’exécuter winapp init pour une application WinUI. Si vous ajoutez une identité de package à une application .NET existante qui n'utilise pas WinUI, consultez Utilisation de l'interface CLI winapp avec .NET à la place.

Prerequisites

  • Windows 10 version 1809 ou ultérieure, ou Windows 11.

  • Le SDK .NET, version 8.0.100 ou ultérieure. Les modèles Reactor expérimentaux nécessitent le SDK .NET 10. Winapp CLI n'installe pas les chaînes d'outils, donc winapp new et winapp run s’arrêtent avec des conseils si le SDK .NET est manquant.

  • CLI winapp :

    winget install Microsoft.winappcli --source winget

  • Mode développeur, dont Windows a besoin pour enregistrer l’application à partir de votre sortie de build. Activez-le dans Paramètres > Système > Pour les développeurs. Pour savoir ce que cela change sur votre ordinateur, consultez Sécurité.

Créer une application WinUI

winapp new génère une structure d’application WinUI à partir du pack officiel Microsoft.WindowsAppSDK.WinUI.CSharp.Templates . Il installe ou met à jour le pack de modèles à la demande, puis appelle dotnet new pour vous.

# 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

Exécutez winapp new --list pour afficher les modèles dans le package installé. Le pack inclut ces modèles :

Template Description
winui Application XAML vierge minimale (valeur par défaut). Voir la capture d’écran
winui-navview Application XAML avec un shell NavigationView. Voir la capture d’écran
winui-tabview Application XAML avec un shell TabView. Voir la capture d’écran
winui-mvvm Application XAML qui utilise le modèle MVVM avec CommunityToolkit.Mvvm. Voir la capture d’écran
winui-lib Bibliothèque de classes WinUI
winui-unittest Projet MSTest empaqueté pour les tests unitaires WinUI
reactor, reactor-mvu, reactor-navview, reactor-tabview Expérimental. Applications WinUI écrites en C# uniquement, sans XAML

Note

Les modèles Reactor référencent des paquets préliminaires Microsoft.UI.Reactor. Leurs API peuvent changer ou être supprimées dans une version ultérieure.

Pour chaque option, consultez la référence desnew commandes.

Compiler et exécuter avec l’identité

À partir du dossier du projet, winapp run génère le projet, installe le runtime SDK d'application Windows qui correspond à votre architecture s'il est manquant, inscrit l'application avec l'identité du package et la lance.

cd MyApp
winapp run

winapp run accepte un fichier projet, un fichier solution, un dossier qui contient l’un d’eux ou un dossier de sortie de build :

# 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

winapp CLI lit la propriété WindowsPackageType du projet pour décider comment le lancer. Un projet packagé s’exécute avec l’identité de package d’application. Un projet qui définit WindowsPackageType sur None s’exécute en tant qu’application non empaquetée sans identité. Pour exécuter un projet empaqueté comme non empaqueté, passez la propriété sur la ligne de commande :

winapp run -p WindowsPackageType=None

D’autres options utiles incluent --clean la suppression de l’enregistrement précédent et les données enregistrées de l’application (LocalState et paramètres) pour une nouvelle première exécution, --no-launch pour enregistrer sans démarrer l’application, et --detach --json pour retourner l’ID de processus et quitter afin que les scripts et les agents puissent continuer à fonctionner pendant l’exécution de l’application. Pour obtenir la liste complète, consultez Project mode (projets .NET SDK).

Utiliser dotnet run à la place

Si vous préférez dotnet run, utilisez le Microsoft.Windows.SDK.BuildTools.WinApp package NuGet. Le package s’accroche à dotnet run pour qu’il appelle winapp run et lance l’application avec l’identité. Les projets que vous créez avec winapp new référencent déjà le package, donc dotnet run fonctionne sans configuration supplémentaire. Pour les autres projets, ajoutez d’abord le package :

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

Vous pouvez passer des winapp run options en tant que WinAppRun* propriétés MSBuild, par exemple dotnet run -p:WinAppRunDebugOutput=true. Pour désactiver l’intégration, définissez EnableWinAppRunSupport sur false dans le fichier projet. Pour plus d’informations, consultez la prise en charge de dotnet run.

Diagnostiquer les plantages

Ajoutez --debug-output pour capturer OutputDebugString messages et des exceptions de première chance pendant l’exécution de l’application. Lorsqu’une application WinUI échoue avec une exception stowed, winapp CLI analyse le vidage sur incident et imprime l’erreur d’origine et la pile des appels au lieu d’un code d’échec générique.

winapp run --debug-output

Ajouter --symbols pour télécharger des symboles pour les noms de fonctions natives complètes. Étant donné que --debug-output attache winapp CLI comme débogueur, vous ne pouvez pas attacher Visual Studio ou un autre débogueur au même processus. Pour déboguer avec votre IDE à la place, consultez Débogage avec winapp CLI. Pour plus d’informations sur l’analyse des exceptions stockées, consultez le triage des exceptions stockées WinUI.

Rechercher des contrôles et des API

winapp find-uirecherche des exemples XAML et C# à partir de la galerie WinUI et de la Windows Community Toolkit par intention, puis retourne le code d’un scénario que vous choisissez. winapp find-apirecherche la surface de l’API Windows et WinRT que votre projet référence, telles que les types, membres et énumérations de SDK d'application Windows et du Windows SDK.

# 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

Les deux commandes prennent en charge --json, afin que les agents de codage IA puissent les utiliser pour choisir des contrôles et vérifier les noms d’API. Pour plus d’informations, consultez les références find-ui et find-api.

Automatiser et vérifier l’interface utilisateur

winapp uipilote une application en cours d’exécution via Microsoft UI Automation. Utilisez-le pour inspecter l’arborescence des éléments, activer des contrôles, attendre les modifications d’état et prendre des captures d’écran. Les agents peuvent utiliser les mêmes commandes pour vérifier leurs propres modifications.

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

Le PART_PaneToggleButton sélecteur cible le bouton de menu dans le winui-navview modèle. Pour vos propres contrôles, copiez un sélecteur à partir de la sortie de winapp ui inspect ou winapp ui search.

Pour exécuter l’application dans Windows Sandbox au lieu de votre bureau, ajoutez --on sandbox à winapp run et winapp ui. Pour plus d’informations, consultez l’automatisation de l’interface utilisateur et l’exécution du bac à sable.

Emballer et signer

Lorsque vous êtes prêt à tester un package localement, générez un certificat de développement dont l’éditeur correspond à votre manifeste, puis générez et empaquetez le projet en une seule étape :

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

winapp pack compile le projet et produit un fichier signé .msix. Pour combiner des builds pour plusieurs architectures en une .msixbundleseule, consultez les bundles multi-architecture. Le projet doit être empaqueté, donc un projet qui définit WindowsPackageType sur None ne peut pas être emballé. Pour les projets WinUI, la build SDK d'application Windows possède le manifeste, le point d'entrée et la génération de ressources, de sorte que --manifest, --executable et --skip-pri ne sont pas acceptés.

Le certificat de développement est destiné uniquement aux tests locaux et utilise un mot de passe par défaut. Avant de distribuer votre application, signez-la avec un certificat approuvé, par exemple avec winapp az-sign et Signatures de confiance Azure. Pour plus d’informations, consultez Empaquetage d’un projet directement et sécurité.

Projets WinUI existants

Winapp CLI fonctionne avec les projets WinUI que vous avez créés dans Visual Studio. Pointez winapp run sur le fichier projet, le fichier solution ou le dossier qui en contient un. Pour winapp pack, passez le .csproj. Vous pouvez continuer à créer et déboguer dans Visual Studio et utiliser winapp CLI pour les scripts, CI et les flux de travail de l’agent.

WinUI avec C++

winapp rungénère et lance également des projets WinUI C++/WinRT (.vcxproj) que vous avez créés à partir du modèle Visual Studio WinUI Blank App (Packaged). Il génère le projet avec msBuild de Visual Studio, inscrit l'application avec l'identité du package et la lance :

winapp run .\MyApp.vcxproj

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

Les projets C++ nécessitent Visual Studio ou Build Tools pour Visual Studio avec le workload Développement d’applications de bureau en C++ et les outils de développement d’applications WinUI C++. winapp packne compile pas les projets .vcxproj, donc créez le package MSIX dans Visual Studio. Pour connaître les prérequis et les options, consultez les projets C++ (.vcxproj). Pour les applications C++ qui n’utilisent pas WinUI, consultez Utilisation de l’interface CLI winapp avec C++.

Samples

  • winui-app: une application WinUI empaquetée avec des contrôles configurés pour l’automatisation winapp ui
  • winui-unpackaged-app: application WinUI qui s’exécute sans identité de package
  • winui-solution: solution multi-projet qui montre comment winapp run choisit le projet d’application
  • cpp-winui-app: application WinUI C++/WinRT empaquetée (Visual Studio .vcxproj avec XAML) qui s’exécute avecwinapp run

Étapes suivantes

  • Dernière mise à jour :