Documentación y uso de la CLI

Finalización del shell

Habilite la finalización de tabulación para comandos, opciones y valores. Consulte la guía de finalización del shell para obtener instrucciones de configuración.

# Quick setup for PowerShell (permanent — add to profile)
winapp complete --setup powershell >> $PROFILE

# Or try it in the current session only
winapp complete --setup powershell | Out-String | Invoke-Expression

inicialización

Inicialice un directorio con Windows SDK, SDK de Aplicaciones para Windows y los recursos necesarios para el desarrollo moderno de Windows.

winapp init [base-directory] [options]

Argumentos:

  • base-directory - Directorio base/raíz para la aplicación o área de trabajo (valor predeterminado: directorio actual)

Opciones:

  • --config-dir <path> - Directorio para leer o almacenar la configuración (valor predeterminado: el directorio del proyecto seleccionado o el directorio actual si no se detecta ningún proyecto)
  • --setup-sdks - Modo de instalación del SDK: "estable" (valor predeterminado), "preview", "experimental" o "none" (omitir la instalación del SDK)
  • --ignore-config, --no-config : no use el archivo de configuración para la administración de versiones.
  • --no-gitignore - No actualice el archivo .gitignore.
  • --use-defaults, --no-prompt : no preguntar y usar el valor predeterminado de todas las solicitudes
  • --config-only - Controle solo las operaciones de archivo de configuración, omita la instalación del paquete.
  • --exe <path> : ruta de acceso al ejecutable de la aplicación. Se requiere --sparse. Genera un manifiesto disperso de solo identidad para el exe en lugar de un paquete completo o una configuración del SDK.
  • --sparse - Generar un manifiesto de identidad disperso (appxmanifest.xml) para un exe de escritorio existente. Omite la instalación del SDK o el paquete. Se usa con --exe.
  • --name <name> - Invalidar el nombre del paquete (solo disperso; valor predeterminado: inferido de la exe)
  • --publisher <CN> - Invalidar el CN del publicador (solo disperso; predeterminado: inferido del nombre de la compañía del exe)
  • --output-dir <path> - Directorio para escribir el manifiesto disperso y Assets/ (solo disperso; valor predeterminado: una sparse/ carpeta en el directorio actual)
  • --force - Sobrescribir un existente appxmanifest.xml en el directorio de destino (solo disperso). Sin él, se produce un error en init en lugar de reemplazar un manifiesto o recursos existentes.
  • --add-js-bindings (solo npm): agregue winapp.jsBindings a package.json y genere enlaces JS/TypeScript, sin preguntar (incompatible con --setup-sdks none)

Qué hace:

  • Crea un winapp.yaml archivo de configuración (solo cuando se administran paquetes de SDK; se omiten con --setup-sdks none)
  • Descarga paquetes de Windows SDK y SDK de Aplicaciones para Windows
  • Genera encabezados y archivos binarios de C++/WinRT
  • Crea Package.appxmanifest
  • Configura las herramientas de compilación y habilita el modo de desarrollador
  • Actualiza .gitignore para excluir los archivos generados.
  • Almacena archivos que se pueden compartir en el directorio de caché global.
  • Genera enlaces JS para SDK de Aplicaciones para Windows API cuando está habilitado (solo npm)

Detección automática de proyectos:

Cuando init se ejecuta sin un argumento de directorio, realiza una búsqueda de amplitud del árbol de directorios actual para buscar proyectos compatibles (hasta 10). Tipos de proyecto admitidos:

  • Tauri : tauri.conf.json se encontró un nivel por debajo del directorio.
  • Electron : package.json con electron en dependencias o devDependencies
  • Flutter : pubspec.yaml en la raíz del proyecto
  • .NET:.csproj en la raíz del proyecto
  • Rust : Cargo.toml en la raíz del proyecto
  • C++:CMakeLists.txt en la raíz del proyecto

La búsqueda omite los directorios omitido normalmente (node_modules, bin, obj, .git, etc.). Cuando se encuentra un proyecto compatible, no se buscan subdirectorios debajo de él.

  • Si se proporciona un argumento de directorio (por ejemplo, winapp init . o winapp init path/to/project), la búsqueda se omite y init comprueba solo ese directorio para un proyecto compatible.
  • Si --use-defaults (o --no-prompt) se establece sin un argumento de directorio, init omite la búsqueda e inicializa el directorio actual de forma no interactiva, en primer lugar se advierte si no se detecta ningún tipo de proyecto conocido (por ejemplo, winapp init --use-defaults).
  • En entornos no interactivos (stdin canalizado, CI, entrada redirigida), init usa --use-defaults automáticamente el comportamiento y emite una advertencia: Non-interactive environment detected. Using default values.
  • Si el directorio actual es un proyecto compatible, init continúa inmediatamente.
  • Si se encuentra exactamente un proyecto en otro lugar, se le pedirá que confirme.
  • Si se encuentran varios proyectos, puede seleccionar cuál se va a inicializar; el directorio actual siempre está disponible como opción de reserva.
  • Si no se encuentra ningún proyecto, se le advierte y se le pregunta si debe continuar de todos modos.
  • Si la búsqueda alcanza el límite de 10 proyectos, una advertencia sugiere proporcionar un argumento de directorio.

Flujo de proyecto de .NET automático:

Cuando se encuentra un archivo .csproj en el directorio de destino, init utiliza un flujo optimizado específico de .NET.

  • Valida y actualiza el TargetFramework a un TFM compatible con Windows (por ejemplo, net10.0-windows10.0.26100.0)
  • Agrega Microsoft.WindowsAppSDK y Microsoft.Windows.SDK.BuildTools como entradas de NuGet PackageReference directamente en .csproj
  • Genera Package.appxmanifest, recursos y un certificado de desarrollo
  • No crea ni descarga una proyección de C++ winapp.yaml (utilice dotnet restore para paquetes NuGet)

Modo de identidad dispersa (--exe + --sparse):

Genera un manifiesto de paquete disperso de solo identidad para un archivo ejecutable de escritorio existente, el primer paso del flujo de trabajo de empaquetado disperso. A diferencia del flujo completo init , esto omite toda la instalación del SDK o paquete (los paquetes de identidad dispersos no tienen dependencias del SDK) y solo genera un manifiesto y recursos de marcador de posición.

  • Deduce el nombre del paquete, el publicador, la descripción y la versión de exe a través FileVersionInfo de (invalidar con --name, --publishero interactivamente)
  • appxmanifest.xml Escribe (con el nombre exe sustituido por Executable) más una Assets/ carpeta en una sparse/ carpeta del directorio actual (o --output-dir)
  • Usa --use-defaults/--no-prompt para omitir las solicitudes de invalidación interactivas (compatibles con CI)
  • --exe sin --sparse es un error

Los recursos son externos. El disperso .msix es de solo identidad: el generado Assets/ se resuelve desde el directorio de instalación de la aplicación (la ubicación de contenido externo) en tiempo de ejecución, no incluido en ..msix Impleméntelos junto con la aplicación.

Pasos siguientes después winapp init --exe <exe> --sparsede : winapp pack <appxmanifest.xml> para compilar la identidad .msixy, a continuación winapp embed-identity <exe>, . Consulte la Guía de empaquetado disperso para ver el tutorial completo.

Ejemplos:

# Initialize current directory
winapp init

# Initialize with experimental packages
winapp init --setup-sdks experimental

# Initialize specific directory without prompts
winapp init ./my-project --use-defaults

# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init

# Generate a sparse identity manifest for an existing exe (no SDK install)
winapp init --exe ./bin/Release/net8.0-windows/MyApp.exe --sparse --use-defaults

Sugerencia: Instalación de SDK después de la instalación inicial

Si se ejecutó init con --setup-sdks none (o se omitió la instalación del SDK) y más adelante necesitará los SDK:

# Re-run init to install SDKs - preserves existing files (manifest, etc.)
winapp init . --use-defaults --setup-sdks stable

Use --setup-sdks preview o para versiones preliminares o --setup-sdks experimental experimentales del SDK.

nuevo

Cree una nueva aplicación winUI a partir de una plantilla de SDK de Aplicaciones para Windows dotnet new oficial. Interactivo de forma predeterminada; usa automáticamente los valores predeterminados en entornos no interactivos.

winapp new [options]

Opciones:

  • -t, --template <short-name>- Nombre corto de plantilla (por ejemplowinui, , winui-navview, winui-mvvmwinui-lib, winui-unittesto una plantilla experimental de Reactor como reactor o reactor-mvu). Validado con el paquete instalado en tiempo de ejecución; ejecute winapp new --list para ver todo. Valor predeterminado: winui (aplicación XAML en blanco).
  • -n, --name <name> - Nombre para la nueva aplicación o proyecto (valor predeterminado: derivado de --output, else WinUIApp)
  • -o, --output <path> - Directorio para crear la aplicación en (valor predeterminado: ./<name>)
  • --use-defaults, --no-prompt : no preguntar; use los valores predeterminados (plantilla en blanco, nombre de --output/--namey mantenga el paquete de plantillas instalado en lugar de actualizarlo).
  • --force - Scaffold incluso si el directorio de salida ya contiene archivos
  • --template-version <latest|installed|version> - Versión del paquete de plantillas de WinUI: latest instala el paquete publicado más reciente, installed mantiene lo que ya esté descargado (sin red) o ancle una versión explícita, como 1.2.3. Valor predeterminado: instale la versión más reciente cuando no haya ningún paquete presente; de lo contrario, pida que actualice un paquete obsoleto (mantenido as-is en --use-defaults).
  • --list - Enumerar las plantillas de WinUI disponibles y salir (instala primero el paquete más reciente si no hay ninguna instalada)
  • --json - Dar formato a la salida como JSON

Plantillas:

El paquete incluye dos estilos de aplicación WinUI. Las plantillas XAML definen la interfaz de usuario en el marcado con un código subyacente de C#. Las plantillas de reactor son C# puras sin XAML, usando un patrón MVU (Modelo-View-Update). La lista de plantillas se lee en directo desde el paquete instalado, por lo que siempre refleja la versión que tiene, ejecute winapp new --list para ver el conjunto actual. Plantillas comunes:

Nombre corto Descripción
winui Aplicación XAML en blanco mínima (empaquetado MSIX)
winui-navview Aplicación de inicio XAML NavigationView
winui-tabview Aplicación de inicio tabView XAML
winui-mvvm Aplicación MVVM XAML (CommunityToolkit.Mvvm)
winui-lib Biblioteca de clases winUI 3
winui-unittest Aplicación MSTest empaquetada; las pruebas se ejecutan cuando se inicia
reactor Experimental. Aplicación Reactor en blanco: C#puro, sin XAML
reactor-mvu Experimental. Aplicación reactor que muestra el patrón MVU
reactor-navview Experimental. Aplicación de inicio Reactor NavigationView
reactor-tabview Experimental. Aplicación de inicio TabView de Reactor

Las plantillas de reactor son experimentales. Hacen referencia a los paquetes de versión Microsoft.UI.Reactor preliminar, cuyas API pueden cambiar o quitarse en una versión futura. winapp new los marca (Experimental) en --list y en el selector interactivo, establece "Experimental": true en --jsone imprime una advertencia después de aplicar scaffolding a uno. Nunca se eligen como la plantilla predeterminada. Reactor también requiere el SDK de .NET 10 o posterior; en un SDK winapp new anterior se produce un error por adelantado con la versión que necesita en lugar de aplicar scaffolding a un proyecto que no se puede compilar.

El nombre corto canónico de cada plantilla es la primera lista de alias dotnet new ; también se acepta cualquier alias enumerado (por ejemplo winui3, , wasdk-single, winui-reactor). Cuando se ejecuta dentro de un proyecto de WinUI existente, dotnet new también muestra plantillas de elementos (por ejemplo, una página en blanco), que winapp new se agrega al proyecto actual en lugar de crear uno nuevo.

Control de versiones del paquete de plantillas:

winapp new ya no ancla una versión específica del paquete de plantillas. Si no hay ningún paquete instalado, instala la versión más reciente. Si un paquete anterior ya está instalado comprueba la fuente y, cuando existe una más reciente, pregunta si se va a actualizar, excepto en ejecuciones no interactivas--use-defaults, que mantienen el paquete instalado. Use --template-version latest para tomar siempre la más reciente sin preguntar, o --template-version installed para usar siempre el paquete descargado sin una comprobación de red. Pasar una versión explícita (por ejemplo --template-version 1.2.3, ) siempre instala exactamente esa versión ( reinstalar incluso cuando ya hay un paquete más reciente), por lo que el scaffolding se puede reproducir entre las máquinas.

Una primera ejecución puede tardar más tiempo: La instalación o actualización del paquete de plantillas o la restauración de paquetes NuGet que faltan SDK de Aplicaciones para Windows que usa la plantilla seleccionada pueden requerir descargas adicionales. Esto también puede ocurrir después de publicar una nueva versión de SDK de Aplicaciones para Windows. Si el scaffolding sigue ejecutándose después de 10 segundos, winapp new actualiza su mensaje de estado para indicar que los paquetes pueden estar descargando o restaurando.

Qué hace:

  • Comprueba que el SDK de .NET está instalado (se produce un error rápido con instrucciones si falta, winapp no instala cadenas de herramientas).
  • Instala o actualiza el paquete oficial de plantillas de WinUI (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) a petición
  • Enumera las plantillas disponibles del paquete instalado y delega scaffolding en dotnet new <short-name>

Las plantillas de aplicación winUI ya incluyen Windows empaquetado e identidad (Package.appxmanifest), por lo que no se requiere ningún paso independientewinapp init. En el caso de las plantillas de aplicación, use winapp run para compilar e iniciar la aplicación. La winui-lib plantilla genera una biblioteca de clases para hacer referencia desde un proyecto de aplicación (no tiene ningún manifiesto de aplicación). La winui-unittest plantilla es una aplicación MSTest empaquetada cuyas pruebas se ejecutan cuando se inicia la aplicación (winapp run), no a través de dotnet test. winapp newscaffoldings en el marco de destino del SDK de .NET instalado e imprime el siguiente paso adecuado para la plantilla que elija.

Pase la marca global --verbose (-v) para hacer eco de cada invocación subyacente dotnet (consulta de paquete, comprobación de actualizaciones, instalación, dotnet new list, scaffolding) junto con su salida completa, útil para diagnosticar problemas de scaffolding o paquete de plantillas.

Ejemplos:

# Interactive: pick a template, then a name (output defaults to ./<name>)
winapp new

# List the available templates without scaffolding
winapp new --list

# One-shot with a specific template
winapp new --name MyApp --template winui-navview

# Experimental Reactor app (pure C#, no XAML) — requires the .NET 10 SDK
winapp new --name MyApp --template reactor-mvu

# Always use the newest template pack, no prompts
winapp new --name MyApp --template-version latest --use-defaults

# Show the underlying dotnet commands and their output
winapp new --name MyApp --verbose

# Non-interactive (agent) with machine-readable output
winapp new --use-defaults --name MyApp --json

restaurar

Restaure los paquetes y vuelva a generar archivos en función de la configuración existente winapp.yaml .

winapp restore [base-directory] [options]

Argumentos:

  • base-directory - Directorio que se va a restaurar (valor predeterminado: directorio actual). También selecciona dónde winapp.yaml y nuget.config se leen a menos que --config-dir lo invalide.

Opciones:

  • --config-dir <path> - Directorio que contiene winapp.yaml (valor predeterminado: base-directory)

Qué hace:

  • Lee la configuración existente winapp.yaml.
  • Descarga o actualiza paquetes del SDK en versiones especificadas
  • Regenera encabezados y archivos binarios de C++/WinRT
  • Almacena archivos que se pueden compartir en el directorio de caché global.

Nota:

Para .NET proyectos no hay ninguna winapp.yaml versión del SDK en directo como PackageReference entradas, .csproj por lo que winapp restore se ejecuta dotnet restore automáticamente.

Ejemplos:

# Restore from winapp.yaml in current directory
winapp restore

# Restore a specific project directory (reads ./my-project/winapp.yaml)
winapp restore ./my-project

Fuentes De NuGet personalizadas y privadas:

winapp init, restorey update descargue el SDK de Windows y los paquetes de SDK de Aplicaciones para Windows a través de NuGet, lo que respeta la jerarquía estándarnuget.config. Fuentes privadas y reflejos, credenciales de fuente (incluidos los proveedores de credenciales) y un personalizado globalPackagesFolder todo funciona como lo hacen para dotnet restore. Para restaurar exclusivamente desde su propio reflejo, <clear /> los orígenes heredados y agregue solo los suyos:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/winsdk-mirror/nuget/v3/index.json" />
  </packageSources>
</configuration>

Nota:

En el caso de los proyectos nativos nuget.config winapp se resuelve desde el directorio en el que opera: elrestoreinit/argumento directory, --config-dir cuando se especifica, de lo contrario, el directorio actual. En .NET proyectos, los orígenes proceden de la propia nuget.config jerarquía del proyecto en su lugar, porque es lo que dotnet add package y dotnet restore usan, por lo que colocará la configuración de una fuente privada en el directorio del proyecto o en un antecesor. Se --config-dir notifica una jerarquía externa y se omite en lugar de seleccionar de forma silenciosa las versiones que el proyecto no puede restaurar. Ejecute estos comandos solo en los directorios de confianza, la misma precaución que se aplica a dotnet restore. Cuando se configuran varios orígenes, use asignación de origen de paquetes para anclar cada paquete a una fuente.

actualización

Actualice los paquetes a sus versiones más recientes y actualice el archivo de configuración.

winapp update [options]

Opciones:

  • --setup-sdks <stable|preview|experimental|none> - Modo de instalación del SDK: stable (valor predeterminado), preview, experimentalo none (omitir la instalación del SDK)

Qué hace:

  • Lee la configuración existente winapp.yaml en el directorio actual.
  • Actualiza todos los paquetes a sus versiones disponibles más recientes
  • Actualiza el winapp.yaml archivo con nuevos números de versión
  • Regenera encabezados y archivos binarios de C++/WinRT

Ejemplos:

# Update packages to latest versions
winapp update

# Update including experimental packages
winapp update --setup-sdks experimental

pack

Cree paquetes MSIX a partir de un proyecto o directorios de aplicaciones preparados. Requiere que un archivo de manifiesto (Package.appxmanifest preferido, appxmanifest.xml también admitido) esté presente en el directorio de destino, en el directorio actual o pasado con la --manifest opción . (ejecute init o manifest generate cree un manifiesto)

Pase un solo .csproj para compilar el proyecto y empaquetar su salida en un paso (modo de proyecto, consulte Empaquetado de un proyecto directamente debajo). Pase varias carpetas de entrada para crear una .msixbundle para la distribución de varias arquitecturas (consulte Paquetes de arquitectura múltiple a continuación).

winapp pack <input-folder> [input-folder...] [options]

Argumentos:

  • input-folder - Un único .csproj para compilar y empaquetar (modo de proyecto) o uno o varios directorios que contienen los archivos de aplicación que se van a empaquetar. Pase varias carpetas (por ejemplo, ./publish/x64 ./publish/arm64) para crear un paquete MSIX. Para los paquetes de identidad dispersos, pase un archivo disperso appxmanifest.xml directamente en lugar de una carpeta (consulte Paquetes de identidad dispersos a continuación).

Opciones:

  • --output <filename> - Nombre del archivo de salida. Para paquetes individuales: <name>_<version>_<arch>.msix (revertir a <name>_<version>.msix, <name>_<arch>.msixo <name>.msix). Para agrupaciones: <name>_<version>_<arch1>_<arch2>.msixbundle.
  • --name <name> - Nombre del paquete (valor predeterminado: del manifiesto)
  • --manifest <path> - Ruta de acceso al archivo de manifiesto (Package.appxmanifest preferido, appxmanifest.xml también admitido; valor predeterminado: detección automática)
  • --cert <path> - Ruta de acceso al certificado de firma (habilita la firma automática)
  • --cert-password <password> - Contraseña de certificado (valor predeterminado: "contraseña")
  • --generate-cert - Generación de un nuevo certificado de desarrollo
  • --no-sign - Entregar el paquete sin firmar, invalidando cualquier configuración de firma de proyecto (por ejemplo, para el envío de Store o una canalización de firma externa). No se puede combinar con --cert o --generate-cert.
  • --install-cert - Instalación del certificado en la máquina
  • --publisher <name>: Publisher para la generación de certificados. Acepta un nombre distintivo X.500 completo o un nombre completo (ajustado automáticamente como CN=<name>)
  • --self-contained: tiempo de ejecución de SDK de Aplicaciones para Windows agrupación
  • --skip-pri - Omitir la generación de archivos PRI
  • --executable <path> - Ruta de acceso al archivo ejecutable en relación con la carpeta de entrada (también --exe). Se utiliza para resolver los marcadores de posición $targetnametoken$ en el manifiesto.

Project opciones en modo (requieren una .csproj entrada; rechazadas para entradas de carpeta,agrupación o manifiesto):

  • --configuration <name> (-c) - Configuración de compilación (valor predeterminado: Release)
  • --arch <arch> - Arquitectura de destino: x64, arm64o x86 (valor predeterminado: la arquitectura del proceso actual)
  • --framework <tfm> (-f) - Moniker de marco de destino para proyectos de varios destinos
  • --no-build - Empaquetar la salida de compilación existente sin volver a generar
  • --no-restore - Omitir la restauración del proyecto antes de compilar
  • --property <name=value> (-p) - Propiedad de MSBuild, reenviada a compilación y evaluación (repetible)

Nota: En el caso de winUI/ EnableMsixTooling.csproj (modo de proyecto msix-tooling), el SDK de Aplicaciones para Windows posee el manifiesto, el punto de entrada y la generación de PRI, por lo que --manifest, --executabley --skip-pri se rechazan, configuran <AppxManifest>, el punto de entrada del proyecto y su compilación de recursos en el propio proyecto. Estas tres opciones se siguen aplicando a las entradas de carpeta y al modo de proyecto genérico (no MSIX-tooling). .csproj

Qué hace:

  • Valida y procesa los archivos Package.appxmanifest
  • Resuelve los $placeholder$ tokens en el manifiesto (consulte Los marcadores de posición del manifiesto a continuación)
  • Garantiza las dependencias adecuadas del framework
  • Actualiza manifiestos lado a lado con registros
  • Detecta y agrupa automáticamente los archivos que no son de imagen a los que se hace referencia en el manifiesto (por ejemplo, AppExtension manifest.json, archivos de configuración) desde el directorio de manifiesto o la carpeta de entrada si faltan en el almacenamiento provisional.
  • Detecta automáticamente componentes de WinRT de terceros y registra sus clases activables (consulte detección de componentes de WinRT a continuación).
  • Controla la implementación autocontenida de WinAppSDK.
  • Firma el paquete si se proporciona el certificado

Empaquetado directo de un proyecto

Cuando la entrada es un solo .csproj, winapp pack compila el proyecto (con las opciones anteriores) y empaqueta la salida resultante, no es necesario compilar por separado ni localizar primero la carpeta de salida. Este modo de proyecto refleja winapp run.

# Build MyApp in Release for arm64 and package + sign it in one step
winapp pack ./MyApp.csproj -c Release --arch arm64 --cert ./devcert.pfx

# Package an existing build output without rebuilding
winapp pack ./MyApp.csproj --no-build

# Select the target architecture with an exact RID instead of --arch
winapp pack ./MyApp.csproj -p RuntimeIdentifier=win-x64

La arquitectura de destino procede de --archo de un solitario -p RuntimeIdentifier=<rid> cuando no se pasa --arch (el RID exacto se conserva y controla la compilación). Pasar y --arch-p RuntimeIdentifier es un conflicto y se rechaza.

El proyecto debe compilarse como una aplicación empaquetada (EnableMsixTooling=true con un Package.appxmanifest); un proyecto que se compila como una aplicación sin empaquetar (WindowsPackageType=None) no tiene ningún manifiesto MSIX para empaquetar e winapp pack informa de un error accionable. Las entradas de carpeta, agrupación y manifiesto disperso no se modifican.

Project modo genera un solo .msix o solo .msixbundle arquitectura (consulte Conjuntos de arquitectura múltiple). No genera archivos de carga de la Tienda ni agrupaciones de división de recursos (idioma o escala): un explícito -p UapAppxPackageBuildMode=StoreUpload o -p AppxBundleAutoResourcePackageQualifiers=... se rechaza con una nota para ejecutar el comando de empaquetado del SDK nativo directamente para esos flujos.

Paquetes de identidad dispersos

Cuando la entrada es un archivo disperso appxmanifest.xml (uno que declara <uap10:AllowExternalContent>true</uap10:AllowExternalContent> en <Properties>) en lugar de una carpeta, winapp pack compila un solo.msix identidad, empaqueta solo el manifiesto, sin archivos binarios de aplicación ni recursos. Este es el paso 2 del flujo de trabajo de empaquetado disperso.

# Build a signed identity package from a sparse manifest
winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx
  • La salida tiene <PackageName>.identity.msix como valor predeterminado en el directorio actual (invalidar con --output).
  • La firma solo se produce cuando --cert se proporciona (o --generate-cert).
  • Si en su lugar pasa una carpeta cuyo manifiesto declara AllowExternalContent, se aplica el comportamiento de empaquetado de carpetas existente, pero winapp pack advierte si encuentra activos () o archivos binarios (.jpg//.so/.png.exe.dll.ico/), para los paquetes dispersos que pertenecen a la ubicación externa, no dentro de ..msix

Después de empaquetar, ejecute winapp embed-identity <exe> y registre el paquete en el instalador con Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>. Consulte la Guía de empaquetado disperso.

Detección de componentes de WinRT

Al empaquetar, winapp pack examina automáticamente los paquetes NuGet definidos en winapp.yaml o *.csproj para componentes de WinRT de terceros (por ejemplo, Win2D). Analiza .winmd los archivos para extraer nombres de clase activables y busca sus archivos DLL de implementación. Las entradas detectadas se registran de la siguiente manera:

  • Dependiente del marco (valor predeterminado): las clases activables se agregan como <InProcessServer> entradas en . Package.appxmanifest
  • Autocontenido (--self-contained): las clases activables se insertan en manifiestos en paralelo (SxS) dentro del ejecutable.

Resolución de marcador de posición durante el empaquetado:

Si el manifiesto contiene $targetnametoken$ en el Executable atributo :

  1. Si --executable se proporciona (ruta de acceso relativa a la carpeta de entrada), el marcador de posición se reemplaza por el valor especificado.
  2. De lo contrario, winapp pack examina la raíz de la carpeta de entrada para .exe los archivos; si se encuentra exactamente una, se usa automáticamente.
  3. Si se encuentran cero o varios .exe archivos, se muestra un error que le pide que especifique. --executable

Ejemplos:

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained WinAppSDK runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable (resolves $targetnametoken$ in manifest)
winapp pack ./dist --executable MyApp.exe

Agrupaciones de arquitectura múltiple

Cuando se pasan varias carpetas de entrada, winapp pack crea una .msixbundle que contiene una .msix por arquitectura:

# Create unsigned bundle for Microsoft Store submission
winapp pack ./publish/x64 ./publish/arm64

# Create signed bundle for sideloading
winapp pack ./publish/x64 ./publish/arm64 --cert ./devcert.pfx

# Self-contained bundle
winapp pack ./publish/x64 ./publish/arm64 --self-contained --generate-cert

El comando detecta automáticamente la arquitectura de cada carpeta desde el encabezado PE del ejecutable principal, valida la coherencia entre segmentos (identidad, funcionalidades, dependencias) y genera un <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Resolución de manifiesto para agrupaciones:

Cada segmento de la agrupación necesita un manifiesto. El comando resuelve los manifiestos en este orden:

  1. --manifest <path> : si se especifica, este único manifiesto se usa para todos los segmentos. ProcessorArchitecture se actualiza automáticamente por segmento para que coincida con la arquitectura detectada.

  2. Manifiesto por carpeta : si cada carpeta de entrada contiene un Package.appxmanifest (o appxmanifest.xml), ese manifiesto de carpeta se usa para su segmento.

  3. Reserva del directorio actual : si una carpeta no tiene ningún manifiesto, el comando busca Package.appxmanifest en el directorio de trabajo actual y lo usa (con la arquitectura automarcada).

En todos los casos, el manifiesto se actualiza automáticamente: se resuelven los marcadores de posición, se insertan dependencias y ProcessorArchitecture se establece por fuerza en la arquitectura detectada. Después de la resolución, una validación entre segmentos garantiza que la identidad (nombre, versión, Publisher), las funcionalidades y las dependencias son coherentes en todos los segmentos, solo ProcessorArchitecture pueden diferir. La versión del paquete definida en los segmentos se asigna a la versión del paquete MSIX, excepto si es 0.0.0.0, en cuyo caso se genera automáticamente una versión basada en marca de tiempo.

# Option 1: Single shared manifest (simplest for most projects)
# Place Package.appxmanifest in your project root and run from there
winapp pack ./publish/x64 ./publish/arm64

# Option 2: Explicit manifest path
winapp pack ./publish/x64 ./publish/arm64 --manifest ./src/Package.appxmanifest

# Option 3: Per-folder manifests (useful if slices have different app extensions)
# Each folder already contains its own Package.appxmanifest
winapp pack ./publish/x64 ./publish/arm64

crear-debug-identidad

Cree una identidad de aplicación para la depuración mediante el empaquetado disperso. El exe permanece en su ubicación original: Windows asocia la identidad a ella a través de Add-AppxPackage -ExternalLocation.

Cuándo usar esto frente winapp runa : Usa create-debug-identity cuando el exe es independiente del código de la aplicación (por ejemplo, las aplicaciones electron donde electron.exe está en node_modules), o cuando prueba específicamente el comportamiento de paquetes dispersos. Para la mayoría de los marcos en los que el exe se encuentra en la carpeta de salida de compilación, use winapp run en su lugar: registra un paquete de diseño flexible completo e inicia la aplicación. Consulte la Guía de depuración para obtener una comparación completa.

winapp create-debug-identity [entrypoint] [options]

Argumentos:

  • entrypoint - Ruta de acceso al archivo ejecutable (.exe) o script que necesita identidad

Opciones:

  • --manifest <path> - Ruta de acceso al archivo de manifiesto de la aplicación, ya sea Package.appxmanifest o appxmanifest.xml (valor predeterminado: detección Package.appxmanifest automática o appxmanifest.xml en el directorio actual)
  • --no-install - No instale el paquete después de la creación.
  • --keep-identity : mantenga la identidad del manifiesto as-is, sin anexar .debug al nombre del paquete y al identificador de aplicación.

Qué hace:

  • Modifica el manifiesto lado a lado del ejecutable.
  • Registra el paquete disperso para la identidad.
  • Habilita la depuración de APIs que requieren identidad

Ejemplos:

# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

# Create identity for hosted app script
winapp create-debug-identity app.py

embed-identity

Conecte una aplicación de escritorio a su paquete de identidad disperso insertando el <msix> elemento en el manifiesto de la aplicación en paralelo (fusion). Este es el paso 3 del flujo de trabajo de empaquetado disperso: indica Windows a qué paquete de identidad pertenece el exe en ejecución.

winapp embed-identity <target> [options]

Argumentos:

  • target : el archivo que se va a actualizar. Detección automática por extensión:
    • .exe (modo EXE): inserta el <msix> elemento directamente en el manifiesto en paralelo del exe mediante mt.exe.
    • .xml / .manifest (modo XML): inserta o reemplaza el <msix> elemento en un archivo de manifiesto SxS externo (creado si no existe). Vuelva a compilar la aplicación después para que el manifiesto actualizado se inserte en el binario.

Opciones:

  • --manifest <path> - Ruta de acceso a la appxmanifest.xml dispersa para leer la identidad (packageName, publisher, applicationId). Cuando se omite, el comando busca en una sparse/ carpeta situada junto al destino en primer lugar, en el directorio actual y, a continuación, en el directorio del destino y en el directorio actual, para appxmanifest.xml.

Ejemplos:

# EXE mode — embed identity straight into the built exe
winapp embed-identity ./bin/Release/net8.0-windows/MyApp.exe

# XML mode — update a checked-in side-by-side manifest, then rebuild
winapp embed-identity ./app.manifest --manifest ./appxmanifest.xml

Este comando es idempotente: volver a ejecutarlo reemplaza cualquier elemento existente <msix> en lugar de duplicarlo.

manifiesto

Genere y administre archivos Package.appxmanifest.

generar manifiesto

Genere Package.appxmanifest a partir de plantillas.

winapp manifest generate [directory] [options]

Argumentos:

  • directory - Directorio en el que se va a generar el manifiesto (valor predeterminado: directorio actual)

Opciones:

  • --package-name <name> - Nombre del paquete (valor predeterminado: nombre de carpeta)
  • --publisher-name <name>- Publisher nombre distintivo (valor predeterminado: CN=<usuario> actual). Acepta un DN X.500 con componentes separados por comas (no se admiten RDN con varios valores + y barras diagonales inversas); los nombres completos se encapsulan automáticamente como CN=<name>.
  • --version <version> - Versión (valor predeterminado: "1.0.0.0")
  • --description <text> - Descripción (valor predeterminado: "Mi aplicación")
  • --entrypoint <path> - Ejecutable o script de punto de entrada
  • --template <type> - Tipo de plantilla: packaged (valor predeterminado) o sparse
  • --logo-path <path> - Ruta de acceso al archivo de imagen de logotipo
  • --if-exists <Error|Overwrite|Skip> - Comportamiento cuando el archivo de manifiesto ya existe en la ruta de acceso de destino (valor predeterminado: Error)

Plantillas:

Marcadores de posición del manifiesto

Los manifiestos generados usan $placeholder$ tokens (delimitados por signos de dólar) que se resuelven automáticamente en tiempo de empaquetado.

Marcador de posición Determinado a Ejemplo
$targetnametoken$ Nombre ejecutable sin extensión Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$ Windows.FullTrustApplication Siempre resuelto automáticamente

Esto sigue la misma convención que usa Visual Studio plantillas de proyecto, por lo que los manifiestos son portátiles entre herramientas.

Cómo se resuelven los marcadores de posición:

  • winapp pack — Durante el empaquetado, $targetnametoken$ se resuelve mediante la --executable opción o mediante la detección automática del único .exe en la carpeta de entrada. Si se encuentran varios archivos (o cero) .exe y --executable no se especifican, se muestra un error.
  • winapp create-debug-identity — Cuando se proporciona un argumento de punto de entrada, $targetnametoken$ se resuelve a partir de él. Sin un punto de entrada, el marcador de posición ejecutable ya debe resolverse en el manifiesto.
  • winapp manifest generate --executable — Cuando --executable se proporciona, los metadatos del manifiesto (versión, descripción) y los iconos se extraen del ejecutable, pero el manifiesto generado sigue usando $targetnametoken$.exe; este marcador de posición se resuelve más adelante (por ejemplo winapp pack , o winapp create-debug-identity).

PS: Mantener $targetnametoken$ en el manifiesto protegido evita nombres ejecutables de codificación rígida y funciona con compilaciones winapp pack y Visual Studio.

Ejemplos:

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

manifest add-alias

Agregue un alias de ejecución (uap5:AppExecutionAlias) a Package.appxmanifest. Esto permite iniciar la aplicación empaquetada desde la línea de comandos escribiendo el nombre del alias.

winapp manifest add-alias [options]

Opciones:

  • --name <alias> - Nombre del alias (por ejemplo, myapp.exe). Valor predeterminado: se deduce del Executable atributo en el manifiesto.
  • --manifest <path> - Ruta de acceso a Package.appxmanifest (valor predeterminado: buscar directorio actual)
  • --app-id <id> - Id. de aplicación para agregar el alias a (valor predeterminado: primer elemento Application)

Qué hace:

  • Lee el manifiesto e deduce el alias del Executable atributo (conservando marcadores de posición como $targetnametoken$.exe)
  • Agrega la declaración de uap5 espacio de nombres si aún no está presente.
  • Agrega un <Extensions> bloque con <uap5:AppExecutionAlias> dentro del elemento Application de destino
  • Si el alias ya existe, lo notifica y sale correctamente.

Ejemplos:

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

manifiesto update-assets

Genere todos los recursos de imagen MSIX necesarios a partir de una sola imagen de origen.

winapp manifest update-assets <image-path> [options]

Argumentos:

  • image-path - Ruta de acceso al archivo de imagen de origen (PNG, JPG, SVG, ICO, GIF, BMP, etc.)

Opciones:

  • --manifest <path> - Ruta de acceso al archivo Package.appxmanifest (valor predeterminado: buscar directorio actual)
  • --light-image <path> - Ruta de acceso a una imagen de origen independiente para variantes de tema claro

Descripción:

Toma una sola imagen de origen y genera un conjunto completo de recursos de imagen MSIX en función de las referencias de recursos del manifiesto:

Para cada recurso al que se hace referencia en el manifiesto:

  • 5 variantes de escala: base (sin sufijo), .scale-125, .scale-150, .scale-200.scale-400

Para el icono de la aplicación (Square44x44Logo / AppList, 44×44 base):

  • 14 variantes plateadas — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
  • 14 variantes sin plataforma : .targetsize-{size}_altform-unplated

Additionally:

  • app.ico : archivo ICO de resolución múltiple (16, 24, 32, 48, 256) para la integración del shell. Si se encuentra un archivo existente .ico en el directorio assets (por ejemplo, AppIcon.ico de una plantilla de proyecto), se reemplaza en contexto en lugar de crear un duplicado.

Con --light-image:

  • Light theme targetsize variants ( .targetsize-{size}_altform-lightunplated icono de aplicación)
  • Variantes de escala de tema claro : .scale-{factor}_altform-colorful_theme-light (iconos, logotipo de la tienda)

Compatibilidad con SVG: Los archivos SVG son totalmente compatibles como imágenes de origen. Se representan como vectores directamente en cada tamaño de destino, lo que produce resultados perfectos para píxeles en todas las resoluciones. El archivo debe declarar su propio tamaño, a través de un viewBox o absoluto width y height atributos; un ancho de porcentaje sin viewBox describe ningún tamaño determinado. Un origen que declara que ninguno de los dos se rechaza en SVG image has no usable dimensions lugar de generar recursos en blanco.

El comando escala las imágenes proporcionalmente al mantener la relación de aspecto, centralándolas con fondos transparentes cuando sea necesario. Los recursos se guardan en el directorio Assets relativo a la ubicación del manifiesto.

Ejemplos:

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Use an SVG source for best quality at all sizes
winapp manifest update-assets mylogo.svg

# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/Package.appxmanifest

# Generate light theme variants from a separate image
winapp manifest update-assets mylogo.png --light-image mylogo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets mylogo.png --light-image mylogo.png

# With verbose output
winapp manifest update-assets mylogo.png --verbose

ejecutar

Cree un paquete de diseño flexible a partir de una carpeta de salida de compilación, regístrelo con Windows mediante la API de Windows.Management.Deployment.PackageManager e inicie la aplicación, simulando una instalación completa de MSIX para la depuración. Devuelve el identificador de proceso para los datos adjuntos del depurador.

winapp run funciona en uno de estos tres modos, elegido automáticamente de la entrada:

  • Modo de carpeta : la entrada es una carpeta de salida de compilación (contiene un Package.appxmanifest/AppxManifest.xml).
  • Project modo: la entrada es , .csprojuna .sln/.slnx solución o un directorio que contiene uno. winapp run compila el proyecto e lo inicia, lo que admite aplicaciones WinUI empaquetadas y sin empaquetar . Consulta Project modo a continuación.
  • Modo de archivo único: la entrada es una .csaplicación basada en archivos .NET. winapp run lo compila, genera un manifiesto a partir de sus #:property directivas y lo inicia con la identidad del paquete.

Tip

La selección del modo es silenciosa de forma predeterminada. Si un directorio se ha tratado como una carpeta de salida de compilación cuando esperaba que se compilara como un proyecto, vuelva a ejecutarse con --verbose : el modo de carpeta notifica por qué se eligió (No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). Un directorio solo se compila como un proyecto cuando un .csproj/.slnx/.slncon una aplicación ejecutable se encuentra en su nivel superior; no se busca de forma recursiva.

Este es el comando preferido para la depuración con la identidad del paquete para la mayoría de los marcos (.NET, C++, Rust, Flutter, Tauri). A diferencia create-debug-identity de lo que registra un paquete disperso para un único exe, winapp run registra toda la carpeta como un paquete de diseño flexible, al igual que una instalación MSIX real. Consulte la Guía de depuración para ver los flujos de trabajo de depuración comunes.

winapp run [<input>] [options]

Argumentos:

  • input- La aplicación que se va a ejecutar: una carpeta de salida de compilación (modo de carpeta), una .cs aplicación basada en archivos .NET (modo de archivo único), un .csproj proyecto, una .sln/.slnx solución o un directorio que contenga uno de ellos en su nivel superior (modo de proyecto; el directorio no se busca de forma recursiva). Use . para compilar o ejecutar el proyecto en el directorio actual. Opcional: el valor predeterminado es el directorio actual cuando se omite (coincide con dotnet run).

Opciones:

  • --manifest <path> - Ruta de acceso a Package.appxmanifest (valor predeterminado: detección automática desde la carpeta de entrada o el directorio actual)
  • --output-appx-directory <path> - Directorio de salida para el diseño flexible (valor predeterminado: AppX dentro de la carpeta de entrada). El diseño predeterminado quita los archivos que ya no están en la compilación; un directorio personalizado mantiene archivos adicionales. Use un nuevo directorio personalizado cuando necesite un diseño limpio.
  • --args <string> - Argumentos de la línea de comandos que se van a pasar a la aplicación. Como alternativa, use -- seguido de argumentos para evitar el escape (por ejemplo, winapp run . -- --flag value).
  • --no-launch - Cree solo la identidad de depuración y registre el paquete sin iniciar la aplicación.
  • --with-alias - Inicie la aplicación con su alias de ejecución en lugar de la activación de AUMID. La aplicación se ejecuta en el terminal actual con stdin/stdout/stderr heredado. Rara vez es necesario: una aplicación con OutputType=Exe ya se inicia de forma predeterminada. winapp agrega el requisito uap5:ExecutionAlias al manifiesto que almacena provisionalmente en el diseño de AppX, por lo que no se necesita ningún cambio en el manifiesto protegido; se usa un alias que la aplicación declara as-is. No se puede combinar con --no-launch, --detach, --without-aliaso --json.
  • --without-alias - Forzar la activación de AUMID para una aplicación que, de lo contrario, se iniciaría a través de un alias de ejecución. A continuación, una aplicación de consola se ejecuta sin una consola e imprime nada en este terminal. No se puede combinar con --with-alias.
  • --debug-output - Capturar OutputDebugString mensajes y excepciones de primera oportunidad de la aplicación iniciada. El ruido del marco (WinUI, COM, DirectX) se filtra desde la salida de la consola; El archivo de registro completo captura todo. Si la aplicación se bloquea, captura automáticamente un minivolcado y lo analiza para mostrar el tipo de excepción, el mensaje y el seguimiento de pila con los números de archivo de origen:línea (resueltos desde archivos PDF en la carpeta de salida de compilación). Los bloqueos administrados (.NET) se analizan al instante sin herramientas externas. Los bloqueos nativos (C++/WinRT) muestran los nombres y desplazamientos de los módulos. Cuando la aplicación bloqueada es una aplicación winUI 3 (Microsoft.UI.Xaml.dll se carga), se ejecuta automáticamente una evaluación de prioridades de excepción permitida adicional para exponer el HRESULT de origen, su cadena ErrorContext y la pila de distribución XAML nativa completa; los componentes necesarios del depurador se descargan en primer uso (consulte Depuración, reemplazable a través de la WINAPP_DBGTOOLS_DIR variable de entorno). Solo un depurador puede asociarse a un proceso a la vez, por lo que no se pueden usar simultáneamente otros depuradores (Visual Studio, VS Code). Use --no-launch en su lugar si necesita adjuntar un depurador diferente. No se puede combinar con --no-launch. No se puede combinar con --json.
  • --symbols: descargue símbolos PDB de Microsoft Servidor de símbolos para obtener un análisis de bloqueo nativo más completo con nombres de función resueltos. Solo se usa con --debug-output. Si se omite y se produce un bloqueo nativo, la salida sugerirá agregar esta marca. Esta marca también mejora la pila de evaluación de prioridades de excepciones permitidas de WinUI para aplicaciones winUI 3. En primer lugar, se descargan símbolos y se almacenan en caché localmente; Las ejecuciones posteriores usan la memoria caché.
  • --unregister-on-exit : anule el registro del paquete de desarrollo después de que se cierre la aplicación. Solo quita los paquetes registrados en modo de desarrollo. No se puede combinar con --no-launch.
  • --detach - Inicie la aplicación y vuelva inmediatamente sin esperar a que salga. Resulta útil para ci/automation donde debe interactuar con la aplicación después del inicio. Las ejecuciones locales imprimen el PID; target ejecuta la impresión del destino de interfaz de usuario con ámbito. JSON incluye el PID y el ámbito de destino. No se puede combinar con --no-launch, --debug-output, --with-aliaso --unregister-on-exit.
  • --clean - Quite los datos de aplicación del paquete existente (LocalState, settings, etc.) antes de volver a implementarlos. De forma predeterminada, los datos de la aplicación se conservan en las implementaciones de nuevo.
  • --json - Dar formato a la salida como JSON para el consumo mediante programación (por ejemplo, CI/automation). Útil con --detach para capturar el PID. No se puede combinar con --with-alias o --debug-output.
  • --on <target> - Compile en el host y, a continuación, registre y ejecute en el destino. Actualmente admite sandbox, sin reserva en la ejecución local. Use --detach antes de los comandos de la interfaz de usuario de seguimiento. El espacio aislado --debug-output requiere una aplicación empaquetada. Consulte Windows ejecución del espacio aislado para la configuración, la compatibilidad en tiempo de ejecución y la duración de la aplicación desasociada.

Persistencia de datos de la aplicación:

De forma predeterminada, winapp run conserva los datos de la aplicación (LocalState, RoamingState, Settings, etc.) al volver a implementarla. Si la aplicación escribe datos en ApplicationData.Current.LocalFolder o Environment.GetFolderPath(SpecialFolder.LocalApplicationData) dentro del contexto del paquete, esos datos sobrevivirán en winapp run las invocaciones.

Use --clean cuando necesite un inicio nuevo (por ejemplo, para restablecer el estado dañado o probar el comportamiento de primera ejecución).

Qué hace:

  • Busca o genera package.appxmanifest
  • Crea y registra una identidad de depuración mediante un paquete de diseño flexible
  • Calcula el identificador del modelo de usuario de aplicación (AUMID)
  • Inicia la aplicación mediante la identidad registrada (a menos que --no-launch se especifique).
  • Imprime el identificador de proceso (PID) para los datos adjuntos del depurador.

Ejemplos:

# Register debug identity and launch app from build output
winapp run ./bin/Debug

# Launch with custom manifest and arguments
winapp run ./dist --manifest ./out/Package.appxmanifest --args "--my-flag value"

# Pass arguments after -- to avoid escaping (equivalent to --args)
winapp run ./bin/Debug -- --my-flag value

# Specify output directory for loose layout package
winapp run ./bin/Release --output-appx-directory ./AppXDebug

# Register identity without launching
winapp run ./bin/Debug --no-launch

# Launch via execution alias (console apps run in current terminal)
winapp run ./bin/Debug --with-alias

# Launch and capture OutputDebugString messages and crash diagnostics
winapp run ./bin/Debug --debug-output

# Download native symbols for richer crash analysis (C++/WinRT crashes)
winapp run ./bin/Debug --debug-output --symbols

# Combine with execution alias to debug console apps inline
winapp run ./bin/Debug --with-alias --debug-output

# Run and automatically clean up registration on exit
winapp run ./bin/Debug --with-alias --unregister-on-exit

# Launch and detach immediately (useful for CI/automation)
winapp run ./bin/Debug --detach

# Detach with JSON output (returns PID for scripting)
winapp run ./bin/Debug --detach --json

# Wipe application data (LocalState, settings) and start fresh
winapp run ./bin/Debug --clean

modo Project (proyectos del SDK de .NET)

Cuando la entrada es , .csprojuna.slnx/.sln solución o un directorio que contiene uno (incluido .),winapp run compila el proyecto con dotnet build y, a continuación, lo inicia. Admite aplicaciones WinUI empaquetadas y desempaquetadas e instala la arquitectura coincidente Aplicación de Windows runtime que la aplicación necesita antes de iniciarse.

Entrada de la solución: apunte winapp run a .sln/.slnx (o un directorio que contenga uno; se prefiere una solución sobre archivos sueltos.csproj) y resuelve el proyecto de aplicación ejecutable y, a continuación, lo compila con $(SolutionDir) y las propiedades del mismo nivel Solution* definidas, por lo que los proyectos que dependen de ellos se compilan como lo hacen en Visual Studio. Reglas de resolución:

  • Los proyectos de prueba se omiten al seleccionar automáticamente, por lo que una solución que contiene una aplicación más sus pruebas se resuelve en la aplicación sin --project necesidad. (Un proyecto de prueba de WinUI es en sí mismo una aplicación empaquetada, por lo que el tipo de salida solo no puede distinguirlo).
  • Si el único proyecto ejecutable es un proyecto de prueba, se ejecuta.
  • Si existe más de un proyecto de aplicación ejecutable, winapp run no adivina un proyecto de inicio, genera errores en la lista de candidatos. Use --project <name> para elegir, que siempre se respeta, incluido para seleccionar un proyecto de prueba.

Empaquetado frente a desempaquetado se detecta automáticamente desde la propiedad de MSBuild efectiva WindowsPackageType del proyecto (nunca desde la presencia del manifiesto):

  • Empaquetado (WindowsPackageType=MSIX, el valor predeterminado empaquetado de WinUI): compila y, a continuación, registra la salida de compilación como un paquete de diseño flexible e inicia a través de AUMID (la misma canalización que el modo de carpeta).
  • Desempaquetado (WindowsPackageType=None): compilaciones, garantiza que el entorno de Aplicación de Windows ejecución dependiente del marco está instalado y, a continuación, inicia directamente el compilado.exe. Forzar esto para un proyecto empaquetado con -p WindowsPackageType=None.

Project modo requiere el SDK de .NET 8.0.100 o posterior (para MSBuild--getProperty).

AOT nativo: agregue este grupo de propiedades dentro del elemento del archivo project <Project> y, a continuación, agregue --aot:

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

winapp run . --aot
winapp run . --aot -c Release

--aot admite proyectos x64 y ARM64. Se ejecuta dotnet publish con la configuración de AOT del proyecto y, a continuación, inicia esa salida; se usa -p PublishAot=true para una invalidación única. No realiza una certificación en tiempo de ejecución independiente y no se puede combinar con --no-build ni --manifest.

En el caso de las aplicaciones que usan la identidad del paquete sin un diseño MSIX generado, incluya Package.appxmanifest o appxmanifest.xml en la salida de publicación del proyecto. Winapp almacena provisionalmente los archivos publicados con ese manifiesto. Si ambos nombres están presentes, winapp se detiene en lugar de elegir uno; quite el manifiesto obsoleto y configure el proyecto para publicar solo el manifiesto previsto.

Project-mode options (ignored in folder mode a menos que se indique):

  • -c, --configuration <name> - Configuración de compilación. Valor predeterminado: Debug. (También se respeta en modo de archivo único).
  • --arch <x64|arm64|x86> - Arquitectura de destino. Valor predeterminado: la arquitectura del proceso actual. Determina la arquitectura rid de compilación y Aplicación de Windows runtime y selecciona un perfil de publicación dependiente de la plataforma coincidente cuando lo requiera la compilación efectiva. (También se respeta en modo de archivo único).
  • -r, --runtime <rid>- Identificador de tiempo de ejecución de .NET de destino (por ejemplo, win-x64). Project modo usa solo la arquitectura del RID, siempre compila el canónico win-<arch>y rechaza los RID no Windows (por ejemplolinux-x64, ). Su arquitectura invalida --arch y puede seleccionar el perfil de publicación necesario. (También se respeta en modo de archivo único, donde invalida un #:property RuntimeIdentifier declarado por el archivo).
  • -f, --framework <tfm> - Moniker de la plataforma de destino para proyectos de varios destinos (por ejemplo, net10.0-windows10.0.26100.0). (Rechazado en modo de archivo único: use #:property TargetFramework=...).
  • --project <name-or-path> - Cuando la entrada es una solución (.sln/.slnx) o un directorio con varios proyectos de aplicación ejecutables, selecciona qué proyecto se va a iniciar (por nombre de proyecto o ruta de acceso). (Rechazado en modo de archivo único: una .cs aplicación basada en archivos es el propio proyecto).
  • --no-build - Omita la compilación y ejecute la salida de compilación existente (sigue evaluando las propiedades de salida). (También se respeta en modo de archivo único).
  • --no-restore - Omita la restauración antes de compilar o publicar AOT nativa. (También se respeta en modo de archivo único).
  • --aot- Ejecute el proyecto configurado .NET publicación nativa de AOT. Requiere un valor efectivo PublishAot=true. Rechazado en los modos de carpeta y de archivo único.
  • -p, --property <Name=Value> - Propiedad de MSBuild, reenviada tanto a la compilación como a la evaluación de propiedades. Repita -p para varias propiedades; use %3B o %2C para un punto y coma literal o coma en un valor. (También se respeta en modo de archivo único, donde es la única manera de establecer TargetFramework).

Resultado de compilación y detalle: una ejecución de proyecto normal usa dotnet buildy, a continuación, evalúa la salida compilada. Restaure y compile el flujo de salida en vivo, con credenciales de direcciones URL de fuente autenticadas redactadas. Con --aot, winapp usa dotnet publish; --verbose muestra el comando publish y las rutas de acceso resueltas. Use las opciones de detalle siguientes para controlar lo que se muestra:

Flag dotnet verbosity Agrega
(predeterminado) minimal —
--verbose minimal Seguimientos de decisión de compilación de winapp
--quiet quiet —

Los flujos de salida de publicación de AOT nativos a medida que llegan, incluido el JSON de la propiedad final de MSBuild. En --json, las invocaciones de restauración y compilación y la salida secundaria van a stderr para que stdout permanezca en JSON puro. En --quiet, las invocaciones se suprimen y la salida de restauración o compilación silenciosa de dotnet se enruta a stderr, por lo que stdout permanece limpio. La salida de publicación nativa de AOT también va a stderr en cualquiera de las dos opciones.

Aplicabilidad de opciones: las opciones de diseño flexible o de identidad (--manifest, --output-appx-directory, --no-launch--with-alias, --unregister-on-exit, , , --clean) --executablesolo se aplican a las aplicaciones empaquetadas. Se rechazan con un error claro para las aplicaciones desempaquetadas (que no tienen ningún paquete MSIX). Las opciones de inicio y depuración (--args/--, --detach, --debug-output, --symbols, --json) funcionan en ambos.

ejemplos de modo Project:

# Build and run the project in the current directory (input defaults to ".")
winapp run

# Run a specific project
winapp run ./src/MyApp/MyApp.csproj

# Build and run from a solution (resolves the runnable app project, defines $(SolutionDir))
winapp run ./MyApp.sln

# Pick a startup project when the solution has more than one runnable app
winapp run ./MyApp.sln --project MyApp

# Release build for arm64
winapp run . -c Release --arch arm64

# Publish and run the Release configuration with Native AOT
winapp run . --aot -c Release

# Force an unpackaged run of a packaged project
winapp run . -p WindowsPackageType=None

# Run the existing build output without rebuilding, and capture crash diagnostics
winapp run . --no-build --debug-output

# Show winapp's build decision traces (dotnet build stays at minimal verbosity)
winapp run . --verbose

# Launch and detach (prints PID), forwarding args to the app
winapp run . --detach -- --my-flag value

Modo de archivo único (.NET aplicaciones basadas en archivos)

.NET 10 permite ejecutar un único .cs archivo sin archivo de proyecto, configurándolo con #: directivas en la parte superior. Apunta winapp run a ese archivo y compila la aplicación, genera un appxmanifest para él y lo inicia con la identidad del paquete , por lo que Windows.ApplicationModel.Package.Current funciona, la aplicación obtiene un AUMID real y una entrada de menú Inicio, y las API que simplemente requieren identidad (notificaciones de aplicación, ApplicationData, IA en el dispositivo).

Las integraciones de Shell, como controladores de protocolo, asociaciones de archivos, destinos de recurso compartido y tareas de inicio necesitan una entrada declarada <Extensions> , que el manifiesto generado no contiene. Para agregar uno, cree su propio manifiesto; consulte Traiga su propio manifiesto a continuación.

winapp run counter.cs

O ejecútelo con sin formato dotnet run ; vea Ejecutar con dotnet run lo siguiente.

No crea un manifiesto. Describa el paquete con #:property directivas en su lugar:

#:package Microsoft.UI.Reactor@0.1.0-preview.13
#:property OutputType=WinExe
#:property TargetFramework=net10.0-windows10.0.22621.0
#:property UseWinUI=true
#:property RuntimeIdentifier=win-x64

#:property WinAppPackageName=com.contoso.counter
#:property WinAppDisplayName=Contoso Counter
#:property WinAppDescription=Counts things, one click at a time
#:property Version=1.2.3

using static Microsoft.UI.Reactor.Factories;
ReactorApp.Run<MyApp>("Hello");

Propiedades del manifiesto. Todos son opcionales; cada uno retroceda a un valor predeterminado razonable:

Propiedad Conjuntos Predeterminado
WinAppPackageName Identity/@Name (la identidad del paquete) nombre de archivo, saneado en [-.A-Za-z0-9], además de un hash corto de la ruta de acceso del archivo (counter.cs → counter-a1b2c3d4)
WinAppDisplayName Nombre que se muestra en Inicio y configuración el nombre de archivo sin su extensión
WinAppPublisher Identity/@Publisher CN=<your Windows user name>. Un nombre sin sistema se ajusta como CN=<name>.
WinAppVersion Identity/@Version $(Version), normalizado (consulte a continuación)
WinAppDescription Descripción que se muestra durante la instalación y en Configuración el nombre para mostrar
WinAppCapabilities Funcionalidades para declarar, separadas por ; o , ninguno

Version. Una versión del paquete debe ser exactamente cuatro números, cada 0 a 65535. WinAppVersion (o, si no lo establece, la propiedad estándar Version ) se normaliza para ajustarse a: -preview/-rc El sufijo se quita y faltan componentes se rellenan con ceros, por lo que #:property Version=1.2.3-preview.4 se convierte 1.2.3.0 en y establece la versión del ensamblado y la versión del paquete juntas. Un valor que no se puede ajustar (un componente superior a 65535 o más de cuatro componentes) se rechaza con un error en lugar de cambiarse silenciosamente.

Capabilities

La aplicación ejecuta plena confianza con la identidad, que satisface las API que solo requieren una aplicación empaquetada. Sin embargo, algunas API están controladas en una funcionalidad declarada, independientemente de que las API de IA de Windows sean el caso común. (Las integraciones de Shell, como los controladores de protocolo y las asociaciones de archivos, son un tercer caso: las que necesitan entradas creadas <Extensions> , no una funcionalidad, por lo que usan su propio manifiesto para ellos).

#:property WinAppCapabilities=systemAIModels

Eso es todo PhiLice y las otras API del modelo en el dispositivo necesitan del manifiesto. Declare varios separandolos:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

winapp escribe cada uno en el elemento y el espacio de nombres XML que realmente requiere, declara ese espacio de nombres y genera MaxVersionTested cuando la funcionalidad necesita una más reciente. Esto importa más de lo que suena: las funcionalidades se distribuyen entre varios elementos diferentes, y la misma lista anterior se convierte en tres formas diferentes :

<systemai:Capability Name="systemAIModels" />
<Capability Name="internetClient" />
<DeviceCapability Name="microphone" />

Los nombres que winapp sabe están escritos para usted. Para cualquier otra cosa, el conjunto restringido crece a lo largo del tiempo, se califica usted mismo con el prefijo del espacio de nombres:

Prefijo Emite
rescap: <rescap:Capability> : funcionalidades restringidas
uap:, uap6:, , uap7:, uap11: <uap*:Capability>
systemai: <systemai:Capability>
device: <DeviceCapability>
app: <Capability> en el espacio de nombres predeterminado 
#:property WinAppCapabilities=rescap:broadFileSystemAccess

Un nombre sin reconocimiento no reconocido se rechaza con un error al asignar nombres a estos prefijos, en lugar de adivinarlos, una funcionalidad emitida en el espacio de nombres incorrecto genera un manifiesto Windows se niega a registrar o aceptar mientras no lo concede de forma silenciosa.

Traiga su propio manifiesto

Si necesita algo que no cubran las propiedades ( un controlador de protocolo, una asociación de archivos, un alias de ejecución), cree un manifiesto y winapp run lo usará textualmente en lugar de generar uno. Se recoge de, en orden:

  1. --manifest <path> en la línea de comandos.
  2. #:property WinAppManifestPath=<path> en el .cs archivo .
  3. Un manifiesto que se encuentra junto al .cs archivo, denominado <filename>.appxmanifest (por ejemplo counter.appxmanifest , junto a counter.cs).

Solo ese nombre por archivo se selecciona automáticamente. appxmanifest.xml O Package.appxmanifest en la misma carpeta se omite deliberadamente: varios .cs archivos pueden compartir una carpeta y adoptar un nombre compartido ejecutaría silenciosamente una aplicación bajo la identidad de otra. Para usar un manifiesto para varios archivos, asígnelo explícitamente con --manifest o WinAppManifestPath.

De lo contrario, se genera un Package.appxmanifest elemento en la salida de compilación, junto con los recursos de imagen predeterminados y se actualiza en cada ejecución.

Options. Cada opción en modo de carpeta funciona: --no-launch, , --detach--debug-output--clean--symbols--without-alias--args----with-alias--json--unregister-on-exit/, --executable--output-appx-directory-p/--property--manifest-c/--configuration--no-build--no-restorey .

Tip

Una aplicación de consola se imprime en el terminal de forma predeterminada. Una aplicación empaquetada iniciada a través de AUMID no tiene consola, por lo que una aplicación solo para consola se ejecutaría correctamente e imprimiría nada. Winapp evita que: una aplicación con OutputType=Exe se inicia a través de un alias de ejecución en su lugar, que hereda el stdin/stdout/stderr de este terminal. Sigue recibiendo la identidad del paquete y no tiene que solicitarla:

winapp run counter.cs

Pase --without-alias para forzar la activación de AUMID en su lugar: la aplicación se ejecuta sin una consola e imprime nada aquí. Una aplicación con ventanas (WinExe) muestra una ventana, por lo que mantiene la activación de AUMID; pase --with-alias si desea una en este terminal de todos modos. Para corregir la elección en el archivo en lugar de en cada línea de comandos, establezca la misma propiedad que .csproj usa:

#:property WinAppRunUseExecutionAlias=false

El alias winapp declara se denomina después del nombre de familia del paquete, con un winapp- prefijo , por lo que com.contoso.counter se publica mediante CN=You obtiene .winapp-com.contoso.counter_gspb8g6x97k2t.exe Esa parte final es el hash del publicador Windows deriva, por lo que dos aplicaciones que comparten un nombre bajo distintos publicadores siguen recibiendo alias diferentes. El prefijo mantiene claro el nombre de los comandos reales: una aplicación en python.cs obtiene un winapp-… alias, nunca python.exe. Si crea su propio manifiesto, el alias que declara se usa as-is y winapp no agrega nada.

Esto solo se aplica al alias. El propio registro se clave en el nombre del paquete, por lo que la ejecución de una segunda aplicación que declara lo mismo WinAppPackageName en otro publicador reemplaza el primer registro en lugar de sentarse junto a él. Asigne a cada aplicación su propio nombre si desea que ambos se registren a la vez.

winapp run imprime el alias que registró, por lo que no es necesario calcular el hash para encontrarlo.

El alias es un comando en la ruta de acceso que dura siempre que el paquete permanezca registrado. Si algún otro paquete ya posee el nombre, winapp lo dice. Cuando infiere el alias para usted se inicia a través de AUMID en su lugar, en lugar de iniciar la aplicación incorrecta; cuando se le pide explícitamente , con --with-alias o #:property WinAppRunUseExecutionAlias=true , se produce un error en lugar de hacer otra cosa de forma silenciosa.

No se aplican dos opciones en modo de proyecto, ya que una aplicación basada en archivos se configura a sí misma. Se rechazan con un mensaje que asigna un nombre a la directiva que se va a usar en su lugar:

Opción Use en su lugar
-f/--framework #:property TargetFramework=net10.0-windows10.0.22621.0
--project nothing: el .cs archivo es el proyecto

--arch y -r/--runtime funcionan como lo hacen en modo de proyecto. Cuando tampoco se pasa, winapp compila para la arquitectura de la máquina, que es lo que necesita una aplicación de SDK de Aplicaciones para Windows independiente, ya que sin él se compila AnyCPU y produce un error con WindowsAppSDKSelfContained requires a supported Windows architecture. Se #:property RuntimeIdentifier=win-arm64 respeta un elemento en el archivo; un elemento explícito --arch/--runtime lo invalida.

Ambos trabajos empaquetados y desempaquetados, detectados a partir del efectivo WindowsPackageType exactamente igual que en el modo de proyecto: el valor predeterminado registra un diseño flexible y lo inicia con identidad, mientras #:property WindowsPackageType=None compila la aplicación, instala la Aplicación de Windows Runtime coincidente e inicia .exe directamente. (Una aplicación empaquetada se inicia a través de su alias de ejecución o a través de la activación de AUMID, vea la nota de la consola anterior; esa opción es independiente de si está empaquetada). Las opciones de identidad (--no-launch, --with-alias, --without-alias, --clean, --unregister-on-exit, --manifest, ) --output-appx-directorysolo se aplican a las aplicaciones empaquetadas.

Ejecución con dotnet run

No tienes que escribir winapp en absoluto. Haga referencia al Microsoft.Windows.SDK.BuildTools.WinApp paquete desde el archivo y sin formato dotnet run le proporciona el mismo inicio empaquetado:

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

System.Console.WriteLine(Windows.ApplicationModel.Package.Current.Id.FamilyName);

dotnet run counter.cs

Los destinos de MSBuild del paquete redirigen la ejecución a winapp, que empaqueta, registra e inicia la aplicación que dotnet run acaba de compilar, no se vuelve a compilar. El control de manifiestos no cambia: winapp lo resuelve exactamente igual que para winapp run, por lo tanto #:property WinAppManifestPath=… , y al <filename>.appxmanifest lado .cs de ambos se respetan (vea Bring your own manifest), se sigue ignorando un directorio en todo Package.appxmanifest el directorio y, de lo contrario, se genera uno a partir de las #:property directivas y se actualiza cada ejecución.

Hay que mantener dos condiciones para que se produzca la redirección:

Directiva Por qué
#:package Microsoft.Windows.SDK.BuildTools.WinApp@* los destinos que realizan el envío de redireccionamiento en este paquete
#:property TargetFramework=net10.0-windows… Un archivo sin formato net10.0 se deja solo, por lo que se ejecuta sin empaquetar.

Agregar #:property WindowsPackageType=None también deja el archivo solo: dotnet run a continuación, ejecuta directamente .exe , sin identidad. Use winapp run para la ruta de acceso desempaquetada si desea instalar primero la Aplicación de Windows Runtime coincidente.

Establezca #:property EnableWinAppRunSupport=false esta opción para no participar en el redireccionamiento por completo y las WinAppRun* propiedades descritas en Configuración para dar forma al inicio, por ejemplo:

#:property WinAppRunUnregisterOnExit=true

Si dotnet run ejecuta la aplicación desempaquetada cuando se esperaba la identidad, pregunte por qué. Use dotnet build, no dotnet msbuild : solo dotnet build sintetiza el proyecto virtual mediante el que se compila una aplicación basada en archivos:

dotnet build counter.cs -t:WinAppRunSupportInfo

El modo de archivo único requiere el SDK de .NET 10.0.300 o posterior.

El registro sobrevive a la ejecución. winapp run counter.cs deja el paquete registrado después de que la aplicación salga, exactamente igual que el modo de carpeta y proyecto, por lo que LocalState sobrevive y vuelve a ejecutar el mismo archivo reutiliza la misma identidad en lugar de acumular registros. winapp dice que la primera vez que registra una aplicación y winapp unregister toma lo .cs siguiente:

# Remove the registration (resolves the same identity `winapp run` registered)
winapp unregister counter.cs

# Or remove it as soon as the app exits
winapp run counter.cs --unregister-on-exit

winapp unregister counter.cs no necesita ninguna ruta de acceso de manifiesto: evalúa los valores del #:property archivo de la misma manera run y quita solo un paquete registrado de la salida de compilación de ese archivo. Se rechaza una aplicación con el mismo nombre registrada desde una carpeta diferente a menos que pase --force. Si la ejecución usó una opción que da forma a la identidad o al diseño, pase la misma a unregister:

winapp run counter.cs -p WinAppPackageName=com.contoso.alt
winapp unregister counter.cs -p WinAppPackageName=com.contoso.alt

winapp run counter.cs -c Release --arch arm64
winapp unregister counter.cs -c Release --arch arm64

-p invalida las directivas propias del archivo, y al Directory.Build.props lado de la .cs clave WinAppPackageName puede desactivar $(Configuration) o $(RuntimeIdentifier) , por lo que cada uno de estos puede cambiar qué paquete se registra.

Una vez limpiada la salida temporal del SDK, winapp unregister counter.cs ya no puede confirmar que el registro procede de ese archivo y lo omitirá, use winapp unregister --prune para borrar los registros cuyos archivos se han ido o --force para quitar uno específico de todos modos. Si la ejecución usa --output-appx-directory, pase el mismo directorio para unregister que pueda reconocer el diseño.

Lo mismo se aplica a una ruta de acceso de salida personalizada: la propiedad se confirma desde el diseño estándar <root>\bin\<configuration> del SDK, por lo que una ejecución compilada con no puede coincidir con -p OutputPath=<somewhere-else> su archivo de origen. unregister omite en lugar de adivinar en un directorio más amplio: asigne un nombre al diseño con --output-appx-directoryo use --force.

Ejemplos de un solo archivo:

# Build and run a file-based app with package identity
winapp run counter.cs

# Register identity without launching (e.g. to attach Visual Studio)
winapp run counter.cs --no-launch

# Release build, detached, printing the PID as JSON
winapp run counter.cs -c Release --detach --json

# Capture OutputDebugString output and crash diagnostics
winapp run counter.cs --debug-output

# Forward arguments to the app
winapp run counter.cs -- --verbose --input data.json

# Wipe the app's LocalState and start fresh
winapp run counter.cs --clean

# Remove the package it registered
winapp unregister counter.cs

Nota:

La identidad predeterminada incluye un hash corto de la ruta de acceso del archivo , counter.cs se convierte en algo parecido counter-a1b2c3d4 , por lo que dos counter.cs archivos de carpetas diferentes son aplicaciones diferentes y mantienen su propia configuración y LocalState. El hash se deriva de la ruta de acceso, por lo que sobrevive a las ediciones y vuelve a ejecutarse y solo cambia si mueve el archivo. Establézcalo #:property WinAppPackageName=<name> para elegir una identidad estable; se normaliza con lo que Identity/@Name permite: los caracteres externos [-.A-Za-z0-9] se quitan, los nombres más cortos que 3 caracteres se rellenan con 1y el resultado se limita a 50 caracteres, por lo que My App se registra como MyApp. En cualquier caso, el menú Inicio y Configuración muestran WinAppDisplayName su (valor predeterminado: el nombre de archivo), no la identidad. La identidad siempre está en el ámbito de la cuenta de usuario, por lo que nunca entra en conflicto con otro usuario en el mismo equipo.

Propiedades de MSBuild (paquete NuGet):

Al usar el paquete NuGet de Microsoft.Windows.SDK.BuildTools.WinApp, dotnet run invoca automáticamente winapp run.

Todo lo escrito después dotnet run de pasarse a la aplicación, exactamente como sería sin el paquete. Configure el iniciador con las propiedades de MSBuild siguientes:

# Goes to your app. `--` is optional here, but required when the flag is also a
# `dotnet run` option (--configuration, --framework, --project, -c, -f, -r, ...),
# otherwise the SDK claims it and your app never sees it.
dotnet run --devtools
dotnet run -- --devtools
dotnet run -- --configuration Release

# Configures WinApp; --devtools still reaches your app
dotnet run -p:WinAppRunDetach=true --devtools

Las siguientes propiedades de MSBuild se pueden establecer en .csproj para controlar el comportamiento:

Propiedad Predeterminado Descripción
EnableWinAppRunSupport true Habilitación o deshabilitación de la funcionalidad de soporte técnico de ejecución
WinAppLaunchArgs (vacío) Argumentos para pasar a la aplicación al iniciar
WinAppRunUseExecutionAlias inferido de la aplicación Inicie a través del alias de ejecución en lugar de la activación de AUMID. A la izquierda, winapp lo deduce: una aplicación de consola usa un alias para que su salida llegue al terminal, una aplicación con ventanas usa AUMID. Establezca true o false para decidirlo usted mismo.
WinAppRunNoLaunch false Registrar solo la identidad sin iniciar
WinAppRunDebugOutput false Capturar OutputDebugString mensajes y excepciones de primera oportunidad. Solo un depurador puede asociarse a la vez (evita VS/VS Code). Use WinAppRunNoLaunch en su lugar para adjuntar un depurador diferente.
WinAppRunDetach false Vuelva inmediatamente después de iniciarse en lugar de esperar a que la aplicación salga. Imprime el PID.
WinAppRunUnregisterOnExit false Anulación del registro del paquete de desarrollo después de que se cierre la aplicación
WinAppRunClean false Quitar los datos de la aplicación del paquete existente (LocalState, settings) antes de volver a implementar
WinAppRunSymbols false Descargue símbolos del servidor de símbolos de Microsoft para obtener un análisis de bloqueo nativo más completo. Solo tiene un efecto con WinAppRunDebugOutput.
WinAppRunExecutable (vacío) Ruta de acceso ejecutable relativa a la carpeta build-output. Use cuando el manifiesto contiene $targetnametoken$ y la carpeta de salida tiene más de un .exe.
WinAppRunArgs (vacío) Argumentos sin formato anexados a la winapp run línea de comandos, para las opciones sin propiedad dedicada (por ejemplo --verbose, ). Anexado después de cada propiedad anterior.

Configuración mutuamente excluyente. WinAppRunNoLaunch y WinAppRunDetach cada uno describe un comportamiento de inicio diferente, por lo que entran en conflicto con las demás propiedades de inicio y entre sí. Al establecer un par en conflicto, se produce un error en la ejecución con --X and --Y cannot be used together:

Propiedad No se puede combinar con
WinAppRunNoLaunch WinAppRunDetach, , WinAppRunDebugOutput, WinAppRunUnregisterOnExit
WinAppRunDetach WinAppRunNoLaunch, , WinAppRunDebugOutput, WinAppRunUnregisterOnExit

WinAppRunUseExecutionAlias deliberadamente no está en esa lista, en ninguna dirección. false solicita la activación de AUMID, que no lanza y desasocia ya utiliza; true simplemente no se aplica cuando se establece ninguno de los dos, ya que un alias de ejecución necesita un proceso de ejecución con seguimiento. Por lo tanto, un proyecto que comprueba <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> que todavía se ejecuta limpiamente en dotnet run -p:WinAppRunDetach=true, iniciando a través de AUMID en lugar de con errores.

WinAppRunUseExecutionAlias, WinAppRunDebugOutputy WinAppRunUnregisterOnExit se pueden combinar entre sí. WinAppRunClean, WinAppRunSymbols, WinAppRunExecutabley WinAppLaunchArgs no tienen restricciones. WinAppRunArgs no agrega ninguna restricción propia, pero un modificador pasado por él se comprueba como cualquier otro, por lo que WinAppRunArgs="--detach" todavía entra en conflicto con WinAppRunNoLaunch.

<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

anulación del registro

Anule el registro de un paquete de desarrollo descargado localmente. Solo quita los paquetes registrados en modo de desarrollo (por ejemplo, a través winapp run de o create-debug-identity). Nunca se quitan los paquetes instalados por store o MSIX instalados.

winapp unregister [input] [options]

Argumentos:

  • input- Ruta de acceso a una aplicación basada en archivos .NET (un único .cs) cuyo paquete debe anularse. Su identidad se resuelve de la misma manera winapp run que la resuelve, desde un manifiesto creado si la aplicación tiene una, de lo contrario, desde sus #:property valores, por lo que no se necesita ninguna ruta de acceso de manifiesto. Omita usar --manifest o detectar automáticamente un manifiesto en el directorio actual. No se puede combinar con --manifest, que asigna un nombre diferente al paquete y se puede resolver en otro.

Opciones:

  • --manifest <path> - Ruta de acceso a Package.appxmanifest (valor predeterminado: detección automática desde el directorio actual)
  • --force - Solo para anular el registro local, omita la comprobación del directorio install-location y anule el registro incluso si el paquete se registró desde un árbol de proyecto diferente. Se rechaza con --on; las comprobaciones de propiedad de destino no se pueden omitir.
  • --on <target> - Quite el registro de desarrollo de winapp-owned coincidente de sandbox, no de esta máquina. Requiere un manifiesto y no admite --force. Consulte Limpieza de aplicaciones de espacio aislado.
  • --prune - Quite todos los registros en modo de desarrollo cuyos archivos se hayan ido. No se puede combinar con una entrada, , --manifest--property, --configuration, --arch, --runtimeo --output-appx-directory.
  • -p, --property <Name=Value> : propiedad de MSBuild que se usa al resolver la identidad de una .cs aplicación basada en archivos. Repetible. Pase las mismas propiedades que afectan a la identidad que se usan (por ejemplo -p WinAppPackageName=..., ), ya que una propiedad de línea de comandos invalida las directivas propias #:property del archivo. Solo se aplica a una .cs entrada.
  • -c, --configuration <name> : se usa la configuración de compilación al resolver la identidad de una .cs aplicación basada en archivos. Valor predeterminado: Debug. Pase la misma configuración que usó la ejecución: al Directory.Build.props lado de .cs puede establecer WinAppPackageName o WinAppManifestPath condicionalmente en $(Configuration). Solo se aplica a una .cs entrada.
  • --arch <x64|arm64|x86> - Arquitectura de destino que se usa al resolver la identidad de una .cs aplicación basada en archivos. Valor predeterminado: la arquitectura del proceso actual. Pase la misma arquitectura que usó la ejecución, ya que la identidad también se puede claver fuera $(RuntimeIdentifier)de . Solo se aplica a una .cs entrada.
  • -r, --runtime <rid>- Destino .NET identificador en tiempo de ejecución (por ejemplowin-x64, ) que se usa al resolver la identidad de una .cs aplicación basada en archivos. Solo se usa su arquitectura y invalida --arch. Solo se aplica a una .cs entrada.
  • --output-appx-directory <path> : el directorio de diseño de AppX desde el que se registró el paquete. Solo es necesario cuando se usa --output-appx-directoryla ejecución , ya que no hay nada en los registros del paquete que la opción de ejecución genera su diseño.
  • --json - Dar formato a la salida como JSON

Qué hace:

  • Determina el nombre del paquete: desde la .cs identidad resuelta del archivo o leyendo el manifiesto.
  • Busca paquetes y {name}{name}.debug (la variante de depuración se crea mediante create-debug-identity)
  • Comprueba que cada paquete se registró en modo de desarrollo (IsDevelopmentMode == true)
  • Comprueba que el paquete pertenece a la aplicación denominada (a menos --forceque ) — su ubicación de instalación debe estar en un directorio identificado: la .cs salida de compilación del archivo, el directorio del manifiesto, el directorio actual o un explícito --output-appx-directory. Se omite un paquete cuya ubicación de instalación no se puede resolver (se eliminaron sus archivos), ya que la identidad por sí sola no es prueba de propiedad: dos aplicaciones que establecen #:property WinAppPackageName=counter registrar la misma identidad desde carpetas diferentes. Use --prune para borrar los registros cuyos archivos han desaparecido.
  • Anula el registro de los paquetes coincidentes

Limpieza de registros fallidos (--prune):

Un registro sobrevive a sus archivos. Eliminar una salida de compilación, un árbol de proyecto o (para una aplicación basada en archivos) permite Windows limpiar %LOCALAPPDATA%\Tempy el paquete permanece registrado: Windows mantiene la identidad y su entrada de menú Inicio, pero la activación silenciosamente no hace nada. Estos se acumulan de forma invisible.

# List dev registrations whose files are gone, then confirm before removing
winapp unregister --prune

# Skip the prompt (required for non-interactive/CI use)
winapp unregister --prune --force

Solo se tienen en cuenta los registros en modo de desarrollo y cada uno se quita por su nombre de paquete completo, por lo que un paquete con el mismo nombre todavía instalado desde una ubicación activa no se modifica. La solicitud existe porque una ubicación de instalación que falta suele ser una carpeta eliminada, pero también describe un paquete registrado desde un recurso compartido de red desconectado o una unidad extraíble, revise la lista antes de confirmar.

Ejemplos:

# Unregister from current directory (auto-detects manifest)
winapp unregister

# Unregister a .NET file-based app by its source file
winapp unregister counter.cs

# Unregister with explicit manifest
winapp unregister --manifest ./Package.appxmanifest

# Force unregister even if registered from a different project tree
winapp unregister --force

# Remove every dev registration whose files are gone
winapp unregister --prune

# JSON output for scripting
winapp unregister --json

cert

Genere, inspeccione e instale certificados de desarrollo.

generar certificado

Genere certificados de desarrollo para la firma de paquetes.

winapp cert generate [options]

Opciones:

  • --manifest <Package.appxmanifest>- Extraiga el certificado publisher del manifiestoIdentity/@Publisher. Solo se requiere el publicador, por lo que un manifiesto parcialmente completo sigue funcionando. Si el manifiesto no tiene publicador utilizable, se produce un error en el comando en lugar de sustituir un valor predeterminado, por lo que el certificado nunca puede no coincider silenciosamente con el manifiesto.
  • --publisher <name>: Publisher para el certificado. Al generar un certificado, esta opción tiene prioridad sobre --manifest; se produce un error en un valor vacío explícitamente en lugar de usar el publicador de manifiestos. Acepta un nombre distintivo X.500 completo (por ejemplo, CN=Contoso, O=Contoso Ltd, C=US) o un nombre completo que se ajusta automáticamente como CN=<name>. Los componentes deben tener valores únicos y separados por comas; No se admiten RDN con varios valores (CN=Foo+OU=Bar) ni barras diagonales inversas porque el publicador de manifiestos MSIX no puede representarlos. Un nombre distintivo con formato incorrecto (por ejemplo CN= , o CN=A,,O=B) se rechaza con una salida distinta de cero y un error que asigna un nombre al problema, en lugar de generar un certificado que nunca pueda coincidir con el publicador del manifiesto.
  • --output <path> - Ruta de acceso del archivo de certificado de salida (admite rutas de acceso absolutas y relativas)
  • --password <password> - Contraseña de certificado (valor predeterminado: password, que se conoce públicamente; consulte salida JSON y seguridad)
  • --valid-days <valid-days> - Número de días que el certificado es válido (valor predeterminado: 365)
  • --install : instale el certificado en el almacén de máquinas locales después de la generación.
  • --if-exists <Error|Overwrite|Skip> - Establecer el comportamiento si el archivo de certificado ya existe (valor predeterminado: Error)
  • --export-cer- Exporte un .cer archivo (solo clave pública) junto con ..pfx Resulta útil para distribuir el certificado público por separado para la instalación de confianza.
  • --json - Dar formato a la salida como JSON para el consumo mediante programación. Los errores también se devuelven como JSON ({"error": "..."}).

Salida JSON:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "password": "password",
  "defaultPasswordIsPublic": true,
  "publisher": "Contoso",
  "subjectName": "CN=Contoso",
  "warnings": [
    "Protected with the default password ('password'), which is public. Treat this certificate as development-only: anyone who obtains the .pfx can sign as you. Pass --password to choose your own, and use a CA-issued certificate or Azure Trusted Signing to ship."
  ]
}

publisher es el nombre para mostrar y subjectName el nombre distintivo completo al que se emitió el certificado. defaultPasswordIsPublic siempre está presente. Cuando es true, .pfx el está protegido por una contraseña que cualquiera puede adivinar, por lo que el certificado solo debe firmar compilaciones que permanezcan en sus propias máquinas; compruébalo antes de que un script entrelaje el certificado a cualquier otra cosa. warnings lleva la misma divulgación que el texto y se omite cuando no hay nada que notificar. publicCertificatePath solo aparece con --export-cer.

información del certificado

Mostrar los detalles del certificado desde un archivo PFX o CER. Resulta útil para comprobar que un certificado coincide con el manifiesto antes de firmarlo.

winapp cert info <cert-path> [options]

Argumentos:

  • cert-path - Ruta de acceso al archivo de certificado (PFX o CER)

Opciones:

  • --password <password> - Contraseña para el archivo PFX, omitido para un CER público (valor predeterminado: "contraseña")
  • --json - Dar formato a la salida como JSON

instalación de certificado

Instale el certificado en el almacén de certificados del equipo.

winapp cert install <cert-path> [options]

Argumentos:

  • cert-path - Ruta de acceso al archivo de certificado que se va a instalar

Ejemplos:

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Generate certificate and export public key .cer file
winapp cert generate --publisher "CN=My Company" --export-cer

# Generate certificate with JSON output (for scripting)
winapp cert generate --publisher "CN=My Company" --json

# View certificate details
winapp cert info ./mycert.pfx

# View certificate details as JSON
winapp cert info ./mycert.pfx --json

# Install certificate to machine
winapp cert install ./mycert.pfx

firmar

Firma de paquetes y ejecutables MSIX con certificados.

winapp sign <file-path> <cert-path> [options]

Argumentos:

  • file-path - Ruta de acceso al paquete MSIX o ejecutable para firmar
  • cert-path - Ruta de acceso al certificado de firma (.pfx)

Opciones:

  • --password <password> - Contraseña de certificado (valor predeterminado: "contraseña")
  • --timestamp <url> - DIRECCIÓN URL del servidor de marca de tiempo RFC 3161

Ejemplos:

# Sign MSIX package
winapp sign MyApp.msix ./mycert.pfx

# Sign executable with a non-default certificate password
winapp sign ./bin/MyApp.exe ./mycert.pfx --password mypassword

az-sign

Firma de código de un archivo (paquete exe, MSIX o MSIX) mediante Firma de confianza de Azure: una identidad de firma administrada por la nube, por lo que ninguna clave privada (PFX) nunca reside en el equipo local.

winapp az-sign <file-path> [options]

Argumentos:

  • file-path - Ruta de acceso al archivo que se va a firmar (exe, msix o msixbundle)

Opciones:

  • --subscription, -s : Azure identificador de suscripción que se va a usar. Si no se proporciona y existen varias suscripciones, se le pedirá.
  • --resource-group, -r : grupo de recursos para restringir las cuentas de firma
  • --account - Nombre de la cuenta de firma. Debe usarse con --resource-group
  • --profile, -p : nombre del perfil de certificado. Debe usarse con --account
  • --metadata-file, -m : ruta de acceso a un existente metadata.json. Omite la detección de recursos y los avisos de selección de cuentas o perfiles y firma directamente. Una credencial de Azure no interactiva ya debe estar disponible; la CLI puede revertir de otro modo a un símbolo del sistema de inquilino interactivo o az login, pero la API de programación de npm siempre es no interactiva y produce un error en lugar de preguntar.

Autenticación:

az-signusa la cadena de credenciales estándar de Azure (DefaultAzureCredential). Para CI/CD, establezca AZURE_TENANT_ID, AZURE_CLIENT_IDy AZURE_CLIENT_SECRET (o use Acciones de GitHub OIDC/identidad administrada). También se respeta una sesión de CLI de Azure existente (az loginincluida la azure/login acción de GitHub) en cualquier entorno. Solo cuando no se encuentran credenciales y la sesión es interactiva se az-sign iniciará az login automáticamente.

Requisitos previos:

  • Una cuenta de firma de código Azure y un perfil de certificado (creado en el portal de Azure después de la validación de la identidad), además del rol Firmante de perfil de certificado de firma de código asignado a la identidad. Para obtener más instrucciones, visite Azure documentación de inicio rápido de firma de artefactos.
  • Un entorno de ejecución x64 de todo el equipo .NET 8 (o posterior) instalado. La biblioteca cliente de firma de Azure es un ensamblado administrado que signtool.exe se carga en un proceso independiente; el propio entorno de ejecución independiente de Winapp no lo satisface. Instálelo desde si se produce un error de https://dotnet.microsoft.com/download firma con un error de carga en tiempo de ejecución.
  • Microsoft Visual C++ Redistributable (x64). La biblioteca cliente de firma de Azure depende del entorno de ejecución de VC++ y, dado que winapp descarga el paquete NuGet sin procesar en lugar del instalador oficial de herramientas cliente, esta dependencia no se instala automáticamente. Una máquina limpia puede producir un error de carga incluso con .NET y SignTool presentes. Instale el archivo redistribuible x64 más reciente desde https://aka.ms/vs/17/release/vc_redist.x64.exe si se produce un error en la firma con , 0xc000007b"La aplicación no se pudo iniciar correctamente" o el error de dll que falta desde la biblioteca dlib.

CI con privilegios mínimos: La detección automática (enumerar suscripciones, grupos de recursos, cuentas y perfiles) necesita acceso de lectura en un ámbito primario. Para evitar todas las llamadas de lista de recopilación, pase los cuatro de --subscription, --resource-group--account, y --profile: az-sign valida la cuenta y el perfil con lecturas directas de recursos (get en cada recurso con nombre) en lugar de enumerar la colección primaria, por lo que una entidad de seguridad con ámbito solo para esa cuenta y perfil es suficiente. Si se omite cualquiera de ellas, se vuelve a introducir una llamada de lista ( por ejemplo, si se deja la --subscriptionaz-sign lista de las suscripciones a las que puede acceder la identidad), a la que puede no permitirse realizar una entidad de seguridad de ámbito limitado. Una entidad de seguridad con ámbito solo a un único perfil de certificado puede omitir la validación por completo pasando un pregenerado --metadata-file (que especifica directamente el punto de conexión y el perfil de la cuenta).

Ejemplos:

# Interactive — discover/select subscription, account, and profile
winapp az-sign ./app.msix

# Fully specified — no prompting (ideal for CI/CD)
winapp az-sign ./app.msix --subscription <sub-id> --resource-group <rg> --account <account> --profile <profile>

# Reuse an existing metadata.json (skips resource discovery and selection; authentication may still prompt)
winapp az-sign ./app.msix --metadata-file ./metadata.json

create-external-catalog

Genere un CodeIntegrityExternal.cat archivo de catálogo que contenga hashes de archivos ejecutables a partir de directorios especificados. Este catálogo se usa con la marca TrustedLaunch en manifiestos de paquete disperso MSIX (AllowExternalContent) para permitir la ejecución de archivos externos no incluidos en el propio paquete.

Esto es similar a cómo signtool.exe se crea AppxMetadata\CodeIntegrity.cat al firmar un paquete MSIX, pero genera un catálogo externo para su uso con empaquetado de ubicación dispersa o externa.

winapp create-external-catalog <input-folder> [options]

Argumentos:

  • input-folder - Uno o varios directorios que contienen archivos ejecutables que se van a procesar. Separar varios directorios con punto y coma (por ejemplo, "dir1;dir2")

Opciones:

  • --recursive, -r : incluir archivos de subdirectorios
  • --use-page-hashes - Incluir hashes de página al generar el catálogo (genera un catálogo mayor con datos hash por página)
  • --compute-flat-hashes - Incluir hashes de archivo plano al generar el catálogo
  • --if-exists <Error|Overwrite|Skip> - Comportamiento cuando el archivo de salida ya existe (valor predeterminado: Error)
  • --output, -o : ruta de acceso del archivo de catálogo de salida. Si no se especifica, CodeIntegrityExternal.cat se crea en el directorio actual. Si se especifica un directorio, se anexa el nombre de archivo predeterminado.

Qué hace:

  • Examina los directorios especificados para los archivos ejecutables (archivos binarios PE con secciones de código)
  • Genera un archivo de definición de catálogo (CDF) con hash de todos los ejecutables encontrados.
  • Usa Windows API cryptoCAT para generar el archivo de catálogo de .cat
  • Los archivos no ejecutables (por ejemplo, .txt, .dll sin secciones de código) se omiten automáticamente.

Ejemplos:

# Generate catalog for all executables in a directory
winapp create-external-catalog ./bin

# Include files in subdirectories
winapp create-external-catalog ./bin --recursive

# Specify a custom output path
winapp create-external-catalog ./bin --output ./dist/CodeIntegrityExternal.cat

# Overwrite existing catalog
winapp create-external-catalog ./bin --if-exists Overwrite

# Skip generation if catalog already exists
winapp create-external-catalog ./bin --if-exists Skip

# Include page hashes (for stricter code integrity validation)
winapp create-external-catalog ./bin --use-page-hashes

# Process multiple directories
winapp create-external-catalog "./bin;./lib" --recursive

# Combine multiple options
winapp create-external-catalog ./bin --recursive --use-page-hashes --compute-flat-hashes --output ./dist/CodeIntegrityExternal.cat --if-exists Overwrite

Cuándo usar:

Use este comando al compilar un paquete MSIX disperso que use TrustedLaunch para comprobar los ejecutables externos. El flujo de trabajo típico es:

  1. winapp manifest generate --template sparse : crear un manifiesto disperso con AllowExternalContent
  2. winapp create-external-catalog ./bin : genere el catálogo de integridad de código para los ejecutables de la aplicación.
  3. winapp pack — Empaquetar el manifiesto, los recursos y el catálogo en un MSIX

herramienta

Acceda a las herramientas de Windows SDK directamente. Usa herramientas disponibles en Microsoft.Windows. SDK. BuildTools

winapp tool <tool-name> [tool-arguments]

Herramientas disponibles:

  • makeappx - Creación y manipulación de paquetes de aplicaciones
  • signtool - Firmar archivos y comprobar firmas
  • mt - Herramienta de manifiesto para ensamblados en paralelo
  • Y otras herramientas del SDK de Windows de Microsoft.Windows. SDK. BuildTools

Ejemplos:

# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix

Comprobación de firmas

Las herramientas de compilación se descargan de NuGet y, a continuación, se ejecutan, por lo que winapp comprueba cada una de las Microsoft firma Authenticode válida inmediatamente antes de ejecutarla. El certificado debe denominar Microsoft Corporation como organización de firma. Esto se aplica a todos los comandos que se shelln en una herramienta del SDK, incluidos tool, packagey sign. No se ejecuta una herramienta que produce un error en la comprobación:

'mt.exe' is not validly signed by Microsoft, so it was not run (C:\...\mt.exe).

Un error aquí significa que el archivo en el disco no es lo que Microsoft publicado, con más frecuencia una descarga dañada o parcial. Elimine el paquete de la memoria caché de NuGet y vuelva a ejecutar el comando para que winapp vuelva a descargarlo.

a continuación, winapp mantiene abierta la herramienta mientras se ejecute, por lo que el archivo que ha comprobado es el archivo Windows se carga. Si no puede contener la herramienta en su lugar, tampoco se ejecuta:

'mt.exe' could not be held open for verification, so it was not run (C:\...\mt.exe).

Cierre lo que esté usando el archivo ( un examen antivirus o un editor abierto es la causa habitual) y vuelva a ejecutar el comando. Si la herramienta ha desaparecido en lugar de en uso, elimine el paquete de la caché de NuGet para que winapp vuelva a descargarlo.

store

Ejecute un comando de la CLI para desarrolladores de Microsoft Store. Este comando descargará la CLI para desarrolladores de Microsoft Store si aún no se ha descargado. Obtenga más información sobre la CLI para desarrolladores de Microsoft Store.

winapp store [args...]

Argumentos:

Qué hace:

  • Garantiza que la CLI de Microsoft Store Developer (msstore) se descarga y está disponible en el sistema.
  • Reenvía todos los argumentos a la msstore CLI.
  • Ejecuta el comando que muestra la salida directamente en el terminal.

Ejemplos:

# List all apps in your Microsoft Partner Center account
winapp store app list

# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>

get-winapp-path

Obtenga rutas de acceso a los componentes de Windows SDK instalados.

winapp get-winapp-path [options]

Lo que devuelve:

  • Rutas de acceso al .winapp directorio del área de trabajo
  • Directorios de instalación de paquetes
  • Ubicaciones de encabezado generadas

target

Ejecute comandos, copie archivos, inspeccione el estado o capture todo el escritorio invitado.

Cada verbo toma sandbox como primer argumento. Excepto para snapshot, estos comandos pueden preparar o iniciar el espacio aislado. Consulte Windows ejecución del espacio aislado para conocer los requisitos previos, los permisos, el ciclo de vida y la recuperación.

target exec

Ejecute un comando como usuario invitado.

winapp target exec <target> [--cwd <path>] [--json] -- <executable> [arguments...]
winapp target exec sandbox -- dotnet --info

Argumentos después -- de conservar sus límites. Los flujos estándar y el código de salida del proceso invitado se reenvieron; no es un terminal completo. --json da formato a errores de winapp en stderr sin cambiar el stdout del comando secundario. Use la estructura error.code para distinguir un error de destino del propio estado de salida de una aplicación.

También agrupa explícitamente WINAPP_UI_WORKFLOW_ID las llamadas a la interfaz de usuario invitada realizadas por el comando; consulte Coordinación de la interfaz de usuario del espacio aislado.

inserción de destino y extracción de destino

Copie un archivo o directorio en la dirección denominada por el verbo.

winapp target push <target> <host-source> <target-destination> [--json]
winapp target pull <target> <target-source> <host-destination> [--json]
winapp target push sandbox .\setup.ps1 Setup\setup.ps1
winapp target pull sandbox Results .\results

Las rutas de acceso de destino son relativas al área de trabajo administrada del destino; se rechazan las rutas de acceso de destino absolutas, rootadas y UNC. Un destino de archivo incluye su nombre de archivo. Consulte Ejecución de comandos y copia de archivos para el diseño de directorios, el control de vínculos y la ejecución de un script copiado.

instantánea de destino

Informar de la preparación, las implementaciones y las ventanas de invitado sin iniciar un espacio aislado.

winapp target snapshot <target> [--json]
winapp target snapshot sandbox

No vuelve a conectar un cliente ni repara un agente. Ningún espacio aislado en ejecución es un resultado correcto, no un error. Consulte Inspección del espacio aislado para interpretar los identificadores de proceso y preparación.

captura de pantalla de destino

Capture el escritorio invitado en su tamaño de píxel nativo como PNG de host, sin bordes de ventana de host o selector de aplicaciones. --json informa del origen de coordenadas de invitado.

winapp target screenshot <target> [-o <host-path>] [--json]
winapp target screenshot sandbox -o .\sandbox.png

Use ui screenshot --on sandbox -a <app> en su lugar para una ventana de la aplicación. Consulte Capturas de pantalla y grabaciones para conocer los requisitos del cliente, las limitaciones de foco y el control de salida.

registro de destino

Registre el escritorio invitado en H.264 MP4. Hospedar archivos de vídeo y fotogramas después de finalizar la grabación; JSON y el manifiesto de marco describen cualquier escalado o relleno.

winapp target record <target> [-o <host-path>] [--duration-sec <n>] [--fps <n>] [--max-edge <px>] [--frames] [--overwrite] [--json]
winapp target record sandbox -o .\sandbox.mp4 --duration-sec 20 --fps 15

Usa las opciones de duración, fotograma, sobrescritura y resultado de , pero captura el escritorio en lugar de ui recorduna aplicación. Se prefiere un positivo --duration-sec para el uso de la CLI desatendida; el asistente de npm requiere durationSec. Consulte Captura de espacio aislado para obtener pruebas parciales y errores de preparación de captura.

find-ui

Agente primero. find-ui se crea principalmente para los agentes de codificación de IA: permite que un agente extraiga el marcado real y compile WinUI desde las galerías de envío en lugar de inventarlo y --json haga que todos los resultados (y cada error) sean legibles por máquina. Funciona tan bien tipado a mano.

Busque ejemplos y controles winUI para ver un ejemplo de código en funcionamiento. Solo WinUI: el corpus es la Galería de WinUI 3 y el kit de herramientas de la comunidad de Windows (además de algunos patrones principales mantenidos), no cubre WPF, WinForms u otros marcos de interfaz de usuario. Una tercera fuente, el reactor de microsoft-ui-reactor ReactorGallery, es opcional: se excluye de una búsqueda normal y solo se busca cuando se pasa --source reactor (sus ejemplos declarativos de C#no pegan en una aplicación XAML estándar, por lo que solo se puede acceder a ella al compilar un proyecto reactor/MVU).

winapp find-ui "<query>" [options]

La galería, el kit de herramientas y reactor corpora se suministran dentro de la CLI, por lo que find-ui funciona sin acceso a la red, incluida una primera ejecución en un espacio aislado del agente o detrás de un proxy corporativo que bloquea raw.githubusercontent.com. Cuando GitHub es accesible, la CLI se actualiza desde ella y almacena en caché el resultado por usuario en <global .winapp>/cache/find-ui; el corpus integrado es solo un piso, nunca un techo. Los datos almacenados en caché se actualizan como máximo cada 24 horas o a petición con --refresh.

El corpus integrado se vuelve a capturar de GitHub cada vez que se compila una versión estable y se produce un error en una actualización que detiene la compilación de versión en lugar de enviar datos más antiguos de forma silenciosa; el baker captura a través de la misma ruta --refresh de acceso de código, por lo que un error significa que la actualización en vivo también se interrumpe y vale la pena investigar antes del envío. Una versión todavía se puede cortar con el corpus confirmado anteriormente, pero solo como invalidación explícita. Cuando los resultados se sirven desde la copia integrada de gallery/Toolkit/Reactor corpora, find-ui lo dice en stderr y --json la salida lleva "corpus": "embedded" (otros valores: "network" para una captura nueva, "cache" para la caché local). Una solicitud de solo núcleo ( --source coreo un --id conjunto que es todos los patrones principales) también informa "embedded" , ya que los patrones principales mantenidos se compilan en la CLI y nunca se capturan; no imprime ningún aviso de obsolescencia, ya que --refresh no puede cambiarlos. El corpus campo se notifica cada vez que se han servido los resultados; solo está ausente cuando no se puede cargar ningún corpus en absoluto.

Opciones:

  • --id <id> : captura el código (Gallery/Toolkit devuelve XAML o C#; Reactor es de solo C#) más notas de requisitos previos para uno o varios identificadores de escenario de una búsqueda anterior (por ejemplo, gallery-tabview-1). Repetible. Los identificadores no distinguen mayúsculas de minúsculas ; GALLERY-TABVIEW-1 resuelve lo mismo que gallery-tabview-1.
  • --list - Enumera todos los identificadores de ejemplo y control reconocibles en lugar de buscar (Galería + Kit de herramientas + núcleo; se excluye el origen del reactor opcional).
  • --source <gallery|toolkit|reactor|core> - Restringir los resultados de búsqueda a un único origen. (Solo búsqueda, no válida con --list/--id). Reactor es opt-in — se excluye de una búsqueda normal, por lo que --source reactor es la única manera de buscarlo.
  • --max <N> - Número máximo de controles coincidentes que se van a devolver (valor predeterminado: 3). Se aplica solo a la búsqueda; se omite con --list/--id.
  • --refresh- Omita la caché local y vuelva a capturar el corpus de WinUI de GitHub.
  • --json - Emitir JSON estructurado (descriptivo del agente). Para la búsqueda, cada coincidencia incluye source, control, score, descriptiony una scenarios matriz cuyas entradas contienen el valor por escenario id y header; para --id, código completo. En --jsoncada error , incluidos los errores de argumento/analizador, como un entero --max , se emite como un objeto plano {"error": "..."} en stdout con un código de salida distinto de cero, por lo que la salida permanece legible por la máquina.

Flujo de trabajo: busque de forma compacta el control correcto y sus identificadores de escenario y, a continuación, capture el código completo para obtener la mejor coincidencia con --id.

Ejemplos:

# Find a control by intent (compact results with scenario ids)
winapp find-ui "tabbed layout"

# Restrict to the Windows Community Toolkit
winapp find-ui "settings card" --source toolkit

# Restrict to Reactor (opt-in; C#-only declarative WinUI — Reactor projects only)
winapp find-ui "flex layout" --source reactor

# Fetch the full XAML + C# for a specific scenario
winapp find-ui --id gallery-tabview-1

# Agent-friendly structured output
winapp find-ui "color picker" --json

# Browse everything, or force a corpus refresh
winapp find-ui --list
winapp find-ui "navigation view" --refresh

Relacionado:find-ui busca ejemplos de WinUI; use find-api para buscar en la superficie de API (tipos, miembros, enumeraciones) que hace referencia a un proyecto y winapp ui search para buscar en el árbol de interfaz de usuario de una aplicación en ejecución .

find-api

Agente primero. find-api se crea principalmente para los agentes de codificación de IA: el código generado por motivos en la superficie de la API hace referencia a un proyecto en lugar del recuerdo del modelo, y --json además de códigos de salida que no son cero en símbolos que faltan permiten que un agente gate codegen en la respuesta. Funciona tan bien tipado a mano.

Busque e inspeccione la superficie de api de Windows/WinRT (tipos, miembros, enumeraciones, espacios de nombres) disponibles para un proyecto, resueltos a partir de sus metadatos a los que se hace .winmd/.dll referencia. Las búsquedas de formularios sin sistema; los sub verbos exploran en profundidad un tipo específico, un espacio de nombres o el propio índice.

winapp find-api "<query>" [options]
winapp find-api [command] [options]

El índice se compila a partir de los paquetes NuGet/SDK restaurados del proyecto (a través project.assets.jsonde ) en el primer uso y se actualiza automáticamente cuando se restaura el proyecto. Reside en la caché global .winapp (cache/find-api/) y se comparte entre proyectos. Restaure el proyecto primero (winapp restore o dotnet restore).

Cada coincidencia aparece en su espacio de nombres con el paquete que lo envía y un resumen de una línea de lo que hace, por lo que un resultado se puede usar sin una segunda members llamada:

[40] Microsoft.UI.Xaml.Media
    Class Microsoft.UI.Xaml.Media.AcrylicBrush  [Microsoft.WindowsAppSDK.WinUI 1.8.260224000]
        Paints an area with a semi-transparent material that uses multiple effects including blur and a noise texture.

Agregue --verbose para imprimir también el archivo de caché en disco que respalda cada espacio de nombres, lo que resulta útil al diagnosticar un índice obsoleto o inesperado.

La ejecución winapp find-api sin ninguna consulta imprime un breve resumen de uso y sale 0 : es una solicitud de ayuda, no una búsqueda que no encontró nada.

Ámbitos. Cada respuesta procede exactamente de un ámbito, notificado como scope en --json y como nota en la salida de texto:

  • project : el proyecto en el directorio actual (o --project / --project-dir). Trata el SDK de Windows, el SDK de Aplicaciones para Windows y los propios paquetes NuGet del proyecto. Los metadatos de SDK de Aplicaciones para Windows son la versión a la que hace referencia el proyecto: si la máquina tiene instalado un Aplicación de Windows Runtime más reciente, find-api advierte y lo deja fuera en lugar de confirmar los tipos en los que el proyecto no se puede compilar.
  • sdk: los metadatos de Windows de Windows en toda la máquina y SDK de Aplicaciones para Windows, se usan automáticamente cuando el directorio actual no contiene ningún proyecto y ninguna solución. Esto hace find-api que se pueda usar para explorar las API antes de que exista cualquier proyecto y no necesita acceso a la red. Deliberadamente no incluye paquetes NuGet de terceros, por lo que un tipo de (por ejemplo) community Toolkit no se encontrará en este ámbito.

Una consulta desde un directorio sin proyecto y el ámbito siempresdk responde a ninguna solución , nunca por el proyecto que se indizará en la caché compartida, por lo que los resultados nunca dependen del estado global no relacionado. Pase --project sdk para seleccionar el ámbito del SDK explícitamente desde dentro de un proyecto y winapp find-api refresh --project sdk volver a generarlo después de instalar un nuevo SDK de Windows.

Directorios de soluciones. Desde un directorio que contiene un .sln/.slnx archivo sin proyecto junto a él, los proyectos que la solución compila respuesta en lugar del sdk ámbito : se indexan a petición, por lo que se incluyen sus paquetes NuGet. Cuando la solución compila más de un proyecto indizado, la consulta los enumera y solicita en --project <name> lugar de seleccionar uno.

Comandos:

  • (desnudo)find-api "<query>" ["<query>"...] - Tipo de búsqueda y nombres de miembro, revierte a sus resúmenes documentados, agrupados por espacio de nombres
  • members <type> [<type>...] [--filter <text>] - Enumerar las propiedades, eventos y métodos de un tipo (miembros declarados con firmas, miembros heredados resumidos declarando el tipo)
  • check-property <type> <property> [<property>...] - Valide que existen propiedades en un tipo (sale distinto de cero si falta alguno). Se notifica una propiedad de solo lectura con ⚠️ y "solo lectura, no se puede asignar" en lugar de un sin formato ✅, por lo que una propiedad como ActualWidth no se equivoca por algo que se puede establecer. Los nombres de propiedad distinguen mayúsculas de minúsculas, ya que C# y XAML son: check-property Button background sale de distinto de cero y ofrece Background como una coincidencia cercana en lugar de notificar un nombre que realmente no se puede escribir.
  • enums <type> [<type>...] [--filter <text>] - Enumerar los valores de una enumeración (sale distinto de cero cuando el tipo no es una enumeración)
  • packages - Enumerar los paquetes de metadatos indexados, con recuentos de miembros o tipo de paquete
  • stats - Mostrar estadísticas de índice agregado (paquetes, espacios de nombres, tipos, miembros, .winmd archivos)
  • refresh [--scan] - Recompile el índice de un proyecto (--scan indexa todos los proyectos en el directorio). Con --project <name>, se produce un error en un nombre que coincida con ningún proyecto indizado único en lugar de indexar el directorio actual.

Batching.search, members, enumsy check-property aceptan varios temas en una invocación. Para un agente de inteligencia artificial, esta es la única palanca de costo más grande: el costo marginal de una búsqueda está dominado por el recorrido de ida y vuelta (cada llamada vuelve a enviar toda la conversación), no por el tamaño de la carga, por lo que una llamada que responde a diez preguntas es mucho más barata que diez llamadas.

  • Un único asunto devuelve exactamente la forma de carga que siempre tiene, tanto en texto --jsoncomo en .
  • Dos o más sujetos devuelven un sobre, { "count": N, "results": [ ... ] } en --json, con cada elemento siendo la carga normal de un solo sujeto; check-property agrega missingCount. La salida de texto representa cada asunto en secuencia en un encabezado de ámbito.
  • check-property batches propiedades en un tipo: el primer argumento es el tipo, cada argumento después de que sea una propiedad. En el modo por lotes, una propiedad que existe imprime una sola ✅ línea; solo se imprimen detalles completos casi incorrectos para los que no lo hacen.
  • Un lote se cierra 0 solo si cada asunto se resolvió y se encontró, por lo que un lote sigue siendo seguro para gatear codegen.

Clasificación de búsqueda. Una consulta que coincide exactamente con un nombre de tipo se clasifica por delante de coincidencias parciales y, cuando varios espacios de nombres comparten un nombre corto, solo los conflictos de nombres exactos se enumeran como ambiguos, una consulta como NavigationView notifica el puñado de espacios de nombres que definen ese tipo exacto en lugar de cada espacio de nombres que contiene un símbolo con nombre similar. La lista de ambigüedades obedece a y los resultados normales --maxse siguen imprimiendo debajo de ella.

Escriba names.members, check-property, y enums acepte un nombre corto (NavigationView) o un completo (Microsoft.UI.Xaml.Controls.NavigationView). Cuando un tipo moderno Microsoft.* comparte un nombre corto y su gemelo heredado Windows.* para UWP, el Microsoft.* tipo responde (es decir, la proyección que usa una aplicación de SDK de Aplicaciones para Windows) y siempre se muestra el nombre completo resuelto. Cualquier otra colisión sale de no cero y enumera los candidatos en lugar de adivinar.

Firmas de método. Se imprime una firma de la forma en que escribiría la llamada: un método al que llama en el tipo en lugar de en una instancia se muestra con static, y se muestra un parámetro by-reference con la palabra clave que realmente necesita : out, ino ref. Por lo tanto TryGetValue , lee Boolean TryGetValue(String key, out String value), que se compila como escrito.

Opciones:

  • --max <n> - Número máximo de resultados de búsqueda agrupados por espacios de nombres (valor predeterminado 5; solo búsqueda). También limita la lista de ambigüedades, por lo que una consulta corta que entra en conflicto entre muchos espacios de nombres permanece legible.
  • --filter <text>- Restringir una lista en members y : una subcadena sin distinción entre mayúsculas y enumsminúsculas en el nombre del miembro/valor. Se usa mejor en tipos con cientos de miembros. La mayoría de las enumeraciones son lo suficientemente pequeñas como para volcar en su totalidad (incluso Symbol, la más grande de WinUI en 197 valores), por lo que filtrarlas normalmente cuesta más de lo que ahorra una vez que se factoriza en una segunda estimación. Nunca vuelva a ejecutar el mismo comando con texto de filtro diferente: volcado una vez y léelo.
  • --all - En members, enumere la superficie completa: firmas completas para miembros heredados, además de estáticas de identificadores de propiedad de dependencia y descripciones por miembro, todas las cuales omite una lista sin filtrar (vea Tamaño de lista a continuación). --verbose implica; use --all cuando también desee --json, que no se puede combinar con --verbose.
  • --scan - Detectar e indexar de forma recursiva cada proyecto en el directorio (refresh solo)
  • --project <name>: Project consultar (coincide con el .csproj/.vcxproj nombre) o sdk para consultar el ámbito del SDK de Windows en toda la máquina
  • --project-dir <path>: Project directorio que se va a consultar (el valor predeterminado es el directorio actual). Una ruta de acceso que no existe es un error; nunca se responde silenciosamente desde el sdk ámbito.
  • --json - Emitir una carga legible por máquina en stdout (compatible con cada verbo). Las cargas de consulta identifican el índice que respondió a través scope de (project o sdk), projectNamey projectDir (ausente para el ámbito del SDK): los nombres de proyecto no son únicos entre directorios, por lo que projectDir es la identidad confiable. En --jsoncada error , incluidos los errores de argumento/analizador, como un entero --max , se emite como un objeto plano {"error": "..."} en stdout con un código de salida distinto de cero, por lo que la salida permanece legible por la máquina.

Ejemplos:

# Search
winapp find-api "acrylic brush"
winapp find-api NavigationView --max 10

# Inspect and validate
winapp find-api members Microsoft.UI.Xaml.Controls.NavigationView
winapp find-api check-property Button Background
winapp find-api enums Symbol

# Batch — one call instead of one per subject
winapp find-api check-property InfoBar Severity IsOpen Message Title
winapp find-api members InfoBar TeachingTip ContentDialog
winapp find-api enums InfoBarSeverity Visibility
winapp find-api "acrylic brush" "teaching tip" --max 5

# Narrow a large type instead of dumping it and grepping
winapp find-api members Button --filter background

# Full member surface: inherited signatures, dependency-property statics, descriptions
winapp find-api members Button --all

# Manage the index
winapp find-api refresh

# Explore the Windows SDK with no project at all (e.g. before scaffolding an app)
winapp find-api "acrylic brush"          # from an empty directory -> scope: sdk
winapp find-api members Button --project sdk

Cuando --filter se aplica, la salida sigue informando del total sin filtrar (totalValuesototalEvents//totalPropertiestotalMethods en --json), por lo que una vista estrecha nunca se equivoca para una API pequeña. Un filtro que no coincide con nada sale 0 y lo dice explícitamente, es decir, "nada coincide con el filtro", no "ningún tipo de este tipo".

Tamaño de la lista. Una lista sin members filtrar es la forma costosa: members Button cubre 288 miembros, de los cuales 280 se heredan de 6 tipos base. Una llamada sin filtrar es una consulta de orientación ("qué es este tipo, aproximadamente lo que puede hacer?"), por lo que responde a que y omite las partes de las que no se escribe nada:

  • Firmas de miembro heredadas : los miembros heredados se agrupan declarando el tipo y enumerados solo por nombre, por lo que la forma de la superficie heredada sigue siendo visible sin 280 firmas completas.
  • Statics () del identificador de propiedad de dependencia (BackgroundProperty): 28% de las propiedades típicas de un control WinUI. Existen para pasarse a GetValue/SetValue, no asignados.
  • Descripciones por miembro : la prosa XML-doc, aproximadamente 16% de la carga.
  • Campos implícitos en sus alrededores en --json: kind (implícito en la matriz contenedora/events/propertiesmethods), returnType (el token inicial de signature) y inherited cuando es false (implícito en ).declaringType

Lo que se omitió siempre se notifica (hiddenDependencyProperties, descriptionsOmitted, y en --jsonhint ; una línea "Omitted:" en texto) y los totales todavía describen todo el tipo. Tanto --filter como --all ver la superficie completa con firmas y descripciones completas, por lo que members Button --filter BackgroundProperty todavía encuentra el identificador y members Button --filter Click sigue devuelvendo Clickla firma heredada. Medido en samples/winui-app, esto toma members Button --json de 91,954 a 10,567 caracteres (-88,5%) mientras sale --filter y --all byte idéntico.

Cómo coincide una consulta. winapp find-api "language model" clasifica LanguageModel las coincidencias anteriores cuyas palabras están dispersas entre espacios de nombres y miembros, incluido fuera de un proyecto cuando se indexa el tipo. La búsqueda es léxica, no semántica: coincide con palabras de identificador completas en lugar de cualquier ejecución de letrasIImageLLMAdapterSession, por lo que llm busca pero no ScrollMode. Cuando una consulta no coincide con ningún nombre, se intenta en los resúmenes documentados de tipos y miembros, que es lo que permite "random-access stream" encontrar IRandomAccessStream. Las descripciones se clasifican debajo de cada coincidencia de nombre y solo se pueden buscar los paquetes; un paquete sin documentación XML no contribuye a texto de descripción.

Proyectos sin un archivo de proyecto de MSBuild. Una aplicación Electron (o cualquier otra aplicación no .NET controlada por winapp.yaml) no .csproj tiene y, por tanto, no project.assets.json. find-api lo indexa desde que .winapp/winmds.lock.jsonwinapp restore escribe, que registra lo mismo: cada paquete resuelto, su versión y los .winmd archivos que contribuye. Este proyecto se denomina después de su directorio y su índice queda obsoleto cuando se vuelve a escribir el archivo de bloqueo. Un directorio que contiene y .csprojwinapp.yaml se indexa a partir de .csproj, que es la descripción más precisa de lo que compila el proyecto.

Las respuestas negativas se califican cuando el índice está incompleto. Si no se pudieron leer los metadatos de un paquete, "ningún tipo de este tipo" y "ese paquete nunca se indizó" tienen un aspecto idéntico, y actuar en la primera cuando es realmente el segundo genera código en una API que se le ha dicho que no existe. Por lo tanto, cada respuesta negativa, incluida una search que devuelve cero resultados, lleva una nota de que el índice es parcial y apunta a winapp find-api refresh. Las respuestas positivas no se ven afectadas.

Nombres de tipo genéricos. Los metadatos almacenan tipos genéricos con un sufijo de arity (IAsyncOperation`1), que no es cómo los escribe nadie. members, enumsy check-property aceptan todos los formularios: IAsyncOperation, IAsyncOperation<StorageFile>y IAsyncOperation`1 todos se resuelven en el mismo tipo. Un nombre sin formato coincide con cualquier aridad; una aridad indicada (en cualquiera de las notaciones) debe coincidir, por lo que Holder<A, B> no se resolverá en un solo parámetro Holder<T>.

--json las cargas omiten los diagnósticos. Las rutas de acceso de archivo de caché solo aparecen en --verbose (salida de texto coincidente, donde ya estaban detallados) y las matrices de sugerencias vacías se omiten en lugar de serializarse como [].

Códigos de salida:search sin aciertos, check-property en una propiedad que falta y enums en un tipo de enumeración, todas las comprobaciones de CI y generación de código de puerta no cero no salen de cero. Una invocación por lotes sale de un valor distinto de cero si se produce un error en algún asunto. Una propiedad de solo lectura no es un error; existe, por lo que check-property0 sale y lo marca en la salida (writable: false en --json). Una init propiedad informa writable: false por el mismo motivo: se puede establecer en un inicializador de objeto y su firma indica { get; init; }, pero asignarla después no se compila.

Relacionado:find-api respuestas "¿Existe esta API y cuáles son sus miembros?"; use find-ui para buscar un ejemplo de WinUI en funcionamiento para un control .

node generate-bindings

(Disponible solo en el paquete NPM) Genere enlaces JS para las API de SDK de Aplicaciones para Windows. Los enlaces se declaran mediante un "winapp": { "jsBindings": {...} } espacio de nombres en y se escriben package.jsonen .winapp/bindings/ .

npx winapp node generate-bindings [options]

Opciones:

  • --verbose, -v : habilite la salida detallada por archivo codegen.
  • --quiet, -q : suprimir el progreso y la salida informativa

Qué hace:

  • Lee el winapp.jsBindings bloque de package.json y el winmds.lock.json escrito por el último winapp restorey, a continuación, emite enlaces con .js + .d.ts tipo en .winapp/bindings/
  • No modificapackage.json — es un regenerador pasivo. Agregar el winapp.jsBindings bloque y la @microsoft/dynwinrt dependencia en tiempo de ejecución se produce durante el momento en winapp init que se habilitan los enlaces JS; este comando produce un error rápido si el bloque está ausente.
  • Advierte (pero no escribe) si @microsoft/dynwinrt faltan las dependencias; ejecute npm install después de init agregarlo.

Nota:

Los enlaces son solo npm : requieren invocación a través npx winapp de (el @microsoft/winappcli paquete npm); la CLI de winget independiente no las expone. Ejecute winapp init de forma interactiva y opte por, o use winapp init . --use-defaults --add-js-bindings, antes de usar este comando para volver a generar enlaces. Si edita winapp.yaml, ejecute npx winapp restore para actualizar Windows dependencias antes de volver a generar.

Ejemplos:

# Regenerate JS bindings in the current project
npx winapp node generate-bindings

# Regenerate after editing winapp.jsBindings, with verbose output
npx winapp node generate-bindings --verbose

Consulte la guía de enlaces de JS para el flujo de trabajo de un extremo a otro y las winapp.jsBindings opciones de configuración.

node crear-complemento

(Disponible solo en el paquete NPM) Generar plantillas de complemento nativas de C++ o C# con Windows SDK e integración de SDK de Aplicaciones para Windows.

npx winapp node create-addon [options]

Opciones:

  • --name <name> - Nombre del complemento (valor predeterminado: "nativeWindowsAddon")
  • --template - Seleccione el tipo de complemento. Las opciones son cs o cpp (valor predeterminado: cpp)
  • --verbose - Habilitación de la salida detallada

Qué hace:

  • Crea un directorio addon con archivos de plantilla
  • Genera binding.gyp y addon.cc con ejemplos de SDK de Windows
  • Instala las dependencias de npm necesarias (nan, node-addon-api, node-gyp)
  • Agrega un script de compilación a package.json

Ejemplos:

# Generate addon with default name
npx winapp node create-addon

# Generate custom named addon
npx winapp node create-addon --name myWindowsAddon

node add-electron-debug-identity

(Disponible solo en el paquete NPM) Agregue la identidad de la aplicación al proceso de desarrollo de Electron mediante el empaquetado disperso. Requiere un Package.appxmanifest (cree uno con winapp init o winapp manifest generate si no tiene uno).

Importante

Hay un problema conocido con el empaquetado disperso de aplicaciones Electron que hace que la aplicación se bloquee al iniciar o no representar el contenido web. El problema se ha corregido en Windows, pero aún no se ha propagado a dispositivos Windows externos. Si ve este problema después de llamar a add-electron-debug-identity, puede deshabilitar el espacio aislado en la aplicación Electron con fines de depuración con la --no-sandbox marca . Este problema no afecta al empaquetado MSIX completo.

Para eliminar la identidad de depuración de Electron, use winapp node clear-electron-debug-identity.

npx winapp node add-electron-debug-identity [options]

Opciones:

Opción Descripción
--manifest <path> Ruta de acceso a Package.appxmanifest personalizado (valor predeterminado: Package.appxmanifest en el directorio actual)
--no-install No instale ni modifique las dependencias; configure solo la identidad de depuración de Electron
--keep-identity Mantenga la identidad del manifiesto tal cual, sin anexar .debug al nombre del paquete y al ID de la aplicación.
--verbose Habilitar salida detallada

Qué hace:

  • Registra la identidad de depuración para electron.exe proceso
  • Habilita la prueba de las API que requieren identidades en el desarrollo de Electron
  • Usa Package.appxmanifest existente para la configuración de identidad

Ejemplos:

# Add identity to Electron development process
npx winapp node add-electron-debug-identity

# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest

node limpiar-electron-debug-identity

(Disponible solo en el paquete NPM) Quite la identidad del paquete del proceso de depuración de Electron restaurando el electron.exe original de la copia de seguridad.

npx winapp node clear-electron-debug-identity [options]

Opciones:

Opción Descripción
--verbose Habilitar salida detallada

Qué hace:

  • Restaura electron.exe a partir de la copia de seguridad creada por add-electron-debug-identity
  • Quita los archivos de copia de seguridad después de la restauración.
  • Devuelve Electron a su estado original sin identidad de paquete

Ejemplos:

# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity

Opciones globales

Todos los comandos admiten estas opciones globales:

  • --verbose, -v : habilite la salida detallada para el registro detallado.
  • --quiet, -q : suprimir los mensajes de progreso
  • --help, -h : mostrar la ayuda del comando

Directorio de caché global

Winapp crea un directorio para almacenar en caché los archivos que se pueden compartir entre varios proyectos.

De forma predeterminada, winapp crea un directorio en $UserProfile/.winapp como directorio de caché global.

Para usar una ubicación diferente, establezca la variable de WINAPP_CLI_CACHE_DIRECTORY entorno.

En cmd:

REM Set a custom location for winapp's global cache
set WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

En PowerShell y pwsh:

# Set a custom location for winapp's global cache
$env:WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

Winapp creará este directorio automáticamente cuando ejecute comandos como init o restore.

Comprobaciones de actualización

La CLI de winapp comprueba periódicamente las nuevas versiones y muestra un aviso de una sola línea cuando hay disponible una actualización. Esta comprobación se ejecuta en segundo plano y no agrega ninguna latencia a los comandos.

Las comprobaciones de actualización se deshabilitan automáticamente en entornos de CI (Acciones de GitHub, Azure Pipelines, etc.).

Para deshabilitar manualmente las comprobaciones de actualización, establezca la WINAPP_CLI_UPDATE_CHECK variable de entorno en 0.

En cmd:

set WINAPP_CLI_UPDATE_CHECK=0

En PowerShell y pwsh:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Para que sea permanente:

[System.Environment]::SetEnvironmentVariable('WINAPP_CLI_UPDATE_CHECK', '0', 'User')

Identidad de flujo de trabajo de la interfaz de usuario

winapp ui los comandos que impulsan el escritorio físico siempre toman turnos cooperativos, por lo que dos flujos de trabajo que se ejecutan a la vez no pueden robar el foco del otro ni descartar los menús de los demás. Ese arbitraje no necesita ninguna configuración y no se puede desactivar.

Lo que es opcional es la continuidad. De forma predeterminada, cada comando es una toma única independiente que libera el escritorio en cuanto finaliza. Para mantener el escritorio en varios comandos, asígneles el mismo identificador de flujo de trabajo:

$env:WINAPP_UI_WORKFLOW_ID = [guid]::NewGuid().ToString()

Use el mismo valor para los procesos de cooperación (por ejemplo, una grabación y los clics que debe capturar) y valores diferentes para flujos de trabajo independientes. Cada comando sin un identificador es su propio flujo de trabajo único, incluso cuando se inician varios desde un shell, por lo que los hosts que inician un shell nuevo por comando deben insertar el mismo valor explícito en cada uno. El valor es opaco, nunca se trata como una credencial y solo se conserva como un hash SHA-256. Consulte Automatización de la interfaz de usuario → Coordinación de flujos de trabajo simultáneos de la interfaz de usuario.

ui

Inspeccione e interactúe con las interfaces de usuario de Windows aplicación en ejecución mediante Automatización de la interfaz de usuario (UIA).

winapp ui [command] [options]

Comandos:

  • status - Conexión a la aplicación y mostrar información
  • inspect - Ver árbol de elementos
  • search - Buscar elementos por selector
  • get-property - Leer las propiedades del elemento
  • get-text / get-value - Valor de lectura/texto del elemento (TextPattern, ValuePattern o Name)
  • screenshot - Captura de ventana/elemento como PNG (varias ventanas de un formato PNG compuesto etiquetado; vea ámbito de captura)
  • record- Grabar una región de ventana/elemento en un vídeo MP4 H.264 (Windows Captura de gráficos + Media Foundation)
  • invoke - Activar elemento (clic, alternar, expandir)
  • click - Elemento Click a través de la simulación del mouse (para los controles que no admiten la invocación)
  • hover - Mover el mouse al elemento para desencadenar información sobre herramientas, controles flotantes y estados de desplazamiento (permanencia predeterminada: 800 ms)
  • drag - Arrastre el mouse de un punto a otro, por selector de elementos o coordenadas de pantalla x,y (reordenar, cambiar el tamaño, los controles deslizantes, arrastrar y colocar)
  • touch- Insertar gestos táctiles sintéticos (pulsación, doble pulsación, pulsación larga, deslizar, deslizar, estirar) en un centro de elementos o coordenadas de pantalla x,y
  • pen - Inyección de entrada de lápiz sintético: pulsaciones y trazos de lápiz con el modo configurable de presión, inclinación y borrador
  • send-keys - Enviar entrada de teclado sintético (teclas con nombre, combos, vk=0xNN o texto literal) a una ventana
  • set-value - Establecer valor en el elemento editable (texto, número); recurre a LegacyIAccessible para controles de edición enriquecida put_accValue de solo TextPattern
  • focus - Mover el foco del teclado
  • scroll-into-view - Elemento Scroll visible
  • wait-for - Esperar estado del elemento
  • list-windows - Enumerar todas las ventanas de una aplicación
  • get-focused - Notificar el elemento centrado actualmente
  • yield - Liberar el turno de interfaz de usuario del flujo de trabajo actual; requiere WINAPP_UI_WORKFLOW_ID

Opciones:

  • -a, --app <app> - Aplicación de destino (nombre, título o PID)
  • -w, --window <hwnd> - Ventana de destino por HWND (estable)
  • --on <target> - Ejecute cualquier ui verbo en sandbox; los nombres, los IDENTIFICADORes y los identificadores de ventana hacen referencia al invitado. Las salidas se entregan al host. Consulte Automatización de la interfaz de usuario de espacio aislado para conocer los requisitos de configuración, coordinación de flujos de trabajo y cliente.

registro de la interfaz de usuario

Registre una ventana o región de elemento en un MP4 H.264.

# Record a window for 10 seconds at 15 fps
winapp ui record -a Calculator --duration-sec 10 --fps 15 -o demo.mp4

# Record until Ctrl+C, downscaled so the longest edge is 1280px
winapp ui record -a "My App" --duration-sec 0 --max-edge 1280 -o capture.mp4

# Record just one element's region
winapp ui record -a "My App" btn-save-1234 -o button.mp4

# Keep an agent-readable timeline alongside the MP4
winapp ui record -a Calculator --frames --duration-sec 10 --fps 10 -o evidence.mp4

Opciones de registro:

  • --duration-sec <n> - Duración de grabación en segundos. 0 registra hasta Ctrl+C (valor predeterminado 0).
  • --fps <n> - Fotogramas por segundo para capturar (valor predeterminado 15).
  • --max-edge <px> - Escalado inferior para que el borde más largo sea como máximo este muchos píxeles (0 = sin escala inferior).
  • --capture-screen - Captura desde la pantalla, por lo que se incluyen superposiciones o elementos emergentes (puede capturar ventanas de oclusión).
  • -o, --output <path> - Ruta de acceso de salida .mp4 (el valor predeterminado es recording-<timestamp>-<guid>.mp4).
  • --overwrite - Reemplazar las salidas de grabación existentes después de que finalice la nueva toma; Las salidas existentes se rechazan de forma predeterminada. Los conjuntos de fotogramas anteriores se conservan. Consulte Recuperación de salida de grabación.
  • --frames - Escribir JPEG con marca de tiempo, frames.ndjsony manifest.json en <output-name>.frames. Admite 1-30 fps y --max-edge 64-4096 (valor predeterminado 1280), con un límite de datos de fotogramas de 1 GiB.

Con --json, el resultado final incluye la ruta de acceso de salida, las dimensiones, el códec, el modo de captura, la cadencia, el motivo de detención, las advertencias opcionales frameArtifactsy .

Limitación conocida: la grabación de un elemento específico dentro de un elemento emergente que se representa en su propia ventana de nivel superior (control flotante WinUI/XAML, sugerencia de enseñanza, información sobre herramientas) puede capturar la ventana principal subyacente en su lugar. Registre toda la ventana o siga el flujo de trabajo de superposición de captura de pantalla para los elementos emergentes. Se realiza un seguimiento en #646.

Para obtener documentación completa, consulte docs/ui-automation.md.

  • Last updated on