Uso de la CLI de winapp con WinUI

En esta guía se muestra cómo usar la CLI de winapp en el bucle interno completo de una aplicación WinUI 3: crear un proyecto a partir de una plantilla oficial, compilarlo e iniciarlo con la identidad del paquete, depurar cierres inesperados, buscar controles y API, automatizar la interfaz de usuario y generar un paquete MSIX firmado. Cada paso se ejecuta desde la línea de comandos, por lo que funciona en cualquier editor, en CI y con agentes de codificación de IA.

Las plantillas de proyecto de WinUI ya incluyen un Package.appxmanifest, por lo que no es necesario ejecutar winapp init para una aplicación WinUI. Si va a agregar la identidad del paquete a una aplicación de .NET existente que no usa WinUI, consulte Uso de winapp CLI con .NET en su lugar.

Prerequisites

  • Windows 10 versión 1809 o posterior, o Windows 11.

  • El .NET SDK, versión 8.0.100 o posterior. Las plantillas experimentales de Reactor requieren el SDK de .NET 10. La CLI de winapp no instala cadenas de herramientas, por lo que winapp new y winapp run se detienen con instrucciones si falta el SDK de .NET.

  • CLI de winapp:

    winget install Microsoft.winappcli --source winget

  • Modo de desarrollador, que Windows requiere para registrar la aplicación desde la salida de la compilación. Actívalo en Configuración > Sistema > Para desarrolladores. Para saber qué cambia en su máquina, consulte Seguridad.

Creación de una aplicación WinUI

winapp new genera la estructura de una aplicación WinUI desde el paquete oficial Microsoft.WindowsAppSDK.WinUI.CSharp.Templates. Instala o actualiza el paquete de plantillas a petición y, a continuación, invoca dotnet new por usted.

# 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

Ejecute winapp new --list para ver las plantillas en el paquete instalado. El paquete incluye estas plantillas:

Template Description
winui Aplicación XAML en blanco mínima (valor predeterminado). Vea la captura de pantalla
winui-navview Aplicación XAML con un shell NavigationView. Vea la captura de pantalla
winui-tabview Aplicación XAML con un shell de TabView. Ver la captura de pantalla
winui-mvvm Aplicación XAML que usa el patrón MVVM con CommunityToolkit.Mvvm. Ver la captura de pantalla
winui-lib Biblioteca de clases WinUI
winui-unittest Proyecto MSTest empaquetado para pruebas unitarias de WinUI
reactor, reactor-mvu, , reactor-navview, reactor-tabview Experimental. Solo aplicaciones winUI escritas en C#, sin XAML

Note

Las plantillas de Reactor hacen referencia a los paquetes de versión preliminar Microsoft.UI.Reactor . Sus API pueden cambiar o quitarse en una versión futura.

Para cada opción, consulte la referencia denew comandos.

Compilar y ejecutar con identidad

Desde la carpeta del proyecto, winapp run compila el proyecto, instala el entorno de ejecución de SDK de Aplicaciones para Windows que coincide con la arquitectura si falta, registra la aplicación con la identidad del paquete y la inicia.

cd MyApp
winapp run

winapp run acepta un archivo de proyecto, un archivo de solución, una carpeta que contiene uno de ellos o una carpeta de salida de compilación:

# 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

La CLI de winapp lee la propiedad del WindowsPackageType proyecto para decidir cómo iniciarlo. Un proyecto empaquetado se ejecuta con la identidad del paquete. Un proyecto que establece WindowsPackageType en None se ejecuta como una aplicación sin empaquetar y sin identidad. Para ejecutar un proyecto empaquetado sin empaquetar, pase la propiedad en la línea de comandos:

winapp run -p WindowsPackageType=None

Otras opciones útiles incluyen --clean para quitar el registro anterior y los datos guardados de la aplicación (LocalState y configuración) para una nueva primera ejecución, --no-launch para registrar sin iniciar la aplicación y --detach --json para devolver el identificador de proceso y salir para que los scripts y agentes puedan seguir funcionando mientras se ejecuta la aplicación. Para obtener la lista completa, consulte modo de proyecto (proyectos del SDK de .NET).

Usa dotnet run en su lugar.

Si prefiere dotnet run, use el paquete NuGet Microsoft.Windows.SDK.BuildTools.WinApp. El paquete enlaza dotnet run para que llame a winapp run e inicie la aplicación con identidad. Los proyectos que crea con winapp new ya hacen referencia al paquete, por lo que dotnet run funciona sin configuración adicional. Para otros proyectos, agregue primero el paquete:

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

Puede pasar winapp run opciones como WinAppRun* propiedades de MSBuild, por ejemplo dotnet run -p:WinAppRunDebugOutput=true. Para desactivar la integración, establezca EnableWinAppRunSupport en false en el archivo del proyecto. Para más información, consulte soporte para dotnet run.

Fallos de depuración

Agregue --debug-output para capturar mensajes OutputDebugString y excepciones de primera oportunidad mientras se ejecuta la aplicación. Cuando se produce un error en una aplicación WinUI con una stowed exception, la CLI de Winapp analiza el volcado de memoria e imprime el error original y la pila de llamadas en lugar de un código de error genérico.

winapp run --debug-output

Agregue --symbols para descargar símbolos que muestren los nombres completos de las funciones nativas. Dado que --debug-output asocia la CLI de winapp como depurador, no puedes asociar Visual Studio ni otro depurador al mismo proceso. Para depurar con el IDE en su lugar, consulte Depuración con la CLI de winapp. Para obtener más información sobre el análisis de excepciones almacenadas, consulte Triaje de excepciones almacenadas de WinUI.

Buscar controles y APIs

winapp find-uibusca ejemplos de XAML y C# desde la Galería de WinUI y el kit de herramientas de la comunidad de Windows por intención y devuelve el código para un escenario que elijas. winapp find-apibusca en la superficie de API de Windows y WinRT a la que hace referencia tu proyecto, como tipos, miembros y enumeraciones de SDK de Aplicaciones para Windows y 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

Ambos comandos admiten --json, por lo que los agentes de codificación de IA pueden usarlos para elegir controles y comprobar nombres de API. Para obtener más información, consulte las referencias find-ui y find-api.

Automatiza y verifica la interfaz de usuario

winapp uicontrola una aplicación en ejecución a través de Microsoft Automatización de la interfaz de usuario. Úselo para inspeccionar el árbol de elementos, invocar controles, esperar cambios de estado y tomar capturas de pantalla. Los agentes pueden usar los mismos comandos para comprobar sus propios cambios.

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

El PART_PaneToggleButton seleccionador se dirige al botón de menú de la plantilla winui-navview. Para sus propios controles, copie un selector de la salida de winapp ui inspect o winapp ui search.

Para ejecutar la aplicación en Windows Sandbox en lugar de en el escritorio, agregue --on sandbox a winapp run y winapp ui. Para obtener más información, consulte Automatización de la interfaz de usuario y ejecución en entorno aislado.

Empaquetar y suscribir

Cuando esté listo para probar un paquete localmente, genere un certificado de desarrollo cuyo editor coincida con el manifiesto y, a continuación, compile y empaquete el proyecto en un solo paso:

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

winapp pack compila el proyecto y genera un .msix firmado. Para combinar compilaciones para varias arquitecturas en una .msixbundle, consulte Paquetes para varias arquitecturas. El proyecto debe estar empaquetado, por lo que un proyecto que establezca WindowsPackageType en None no se puede empaquetar. En el caso de los proyectos de WinUI, la compilación de SDK de Aplicaciones para Windows posee el manifiesto, el punto de entrada y la generación de recursos, por lo que --manifest, --executable y --skip-pri no se aceptan.

El certificado de desarrollo es solo para pruebas locales y usa una contraseña predeterminada. Antes de distribuir la aplicación, fírmela con un certificado de confianza, por ejemplo, con winapp az-sign y Firma de confianza de Azure. Para obtener más información, consulte Empaquetado de un proyecto directamente y Seguridad.

Proyectos de WinUI existentes

La CLI de winapp funciona con proyectos de WinUI creados en Visual Studio. Indique winapp run el archivo del proyecto, el archivo de solución o la carpeta que contiene alguno de ellos. Para winapp pack, pase .csproj. Puede seguir compilando y depurando en Visual Studio y usar la CLI de Winapp para scripts, CI y flujos de trabajo del agente.

WinUI con C++

winapp runtambién compila e inicia proyectos winUI de C++/WinRT (.vcxproj) creados a partir de la plantilla aplicación en blanco (empaquetada) de WinUI Visual Studio. Compila el proyecto con MSBuild de Visual Studio, registra la aplicación con la identidad del paquete y la inicia:

winapp run .\MyApp.vcxproj

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

Los proyectos de C++ necesitan Visual Studio o Herramientas de compilación para Visual Studio con la carga de trabajo Desarrollo de escritorio con C++ y las herramientas de desarrollo de aplicaciones WinUI de C++. winapp packno compila .vcxproj proyectos, por lo que cree el paquete MSIX en Visual Studio. Consulte los requisitos previos y las opciones en proyectos de C++ (.vcxproj). Para las aplicaciones de C++ que no usan WinUI, consulte Uso de la CLI de Winapp con C++.

Samples

  • winui-app: una aplicación WinUI empaquetada con controles configurados para la automatización de winapp ui
  • winui-unpackaged-app: una aplicación winUI que se ejecuta sin identidad de paquete
  • winui-solution: una solución de varios proyectos que muestra cómo winapp run selecciona el proyecto de aplicación.
  • cpp-winui-app: una aplicación WinUI de C++/WinRT empaquetada (Visual Studio .vcxproj con XAML) que se ejecuta conwinapp run

Pasos siguientes

  • Se actualizó por última vez el