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: directorio actual)
• --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-unittest Validado con el paquete instalado en tiempo de ejecución; ejecute winapp new --list para ver todo. Valor predeterminado: winui (aplicación 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:

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:

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). 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.

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

# 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 [options]

Opciones:

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

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.

Ejemplos:

# Restore from winapp.yaml in current directory
winapp restore

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 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 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 - 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
• --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.

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

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 cualquier DN X.500 válido; Los nombres sin sistema operativo 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:

• packaged - Manifiesto estándar de aplicación empaquetada
• sparse - Manifiesto de aplicación con empaquetado de ubicación dispersa o externa

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.

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 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 los dos 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.

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), un .csproj proyecto, una .sln/.slnx solución o un directorio que contiene 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 paquete de diseño flexible (valor predeterminado: AppX dentro del directorio de la carpeta de entrada)
• --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. Requiere un uap5:ExecutionAlias elemento en el manifiesto (use winapp manifest add-alias para agregar uno). No se puede combinar con --no-launch. No se puede combinar con --json.
• --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. Imprime el PID en stdout (o en JSON con --json). 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.

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).

Project opciones en modo (omitido en modo de carpeta):

• -c, --configuration <name> - Configuración de compilación. Valor predeterminado: Debug.
• --arch <x64|arm64|x86> - Arquitectura de destino. Valor predeterminado: la arquitectura del proceso actual. Determina tanto el RID de compilación como la arquitectura del entorno de ejecución de Aplicación de Windows que se instala.
• -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.
• -f, --framework <tfm> - Moniker de la plataforma de destino para proyectos de varios destinos (por ejemplo, net10.0-windows10.0.26100.0).
• --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).
• --no-build - Omita la compilación y ejecute la salida de compilación existente (sigue evaluando las propiedades de salida).
• --no-restore - Omita la restauración del proyecto antes de compilar.
• -p, --property <Name=Value> - Propiedad de MSBuild, reenviada tanto a la compilación como a la evaluación de propiedades. Repetible (por ejemplo, -p WindowsPackageType=None).

Resultado y detalle de la compilación: el proyecto se compila en dos pasos, un dotnet build cuya salida transmite en vivo a la consola, seguida de un paso rápido de evaluación de propiedades. winapp imprime la invocación exacta dotnet build … antes de la salida y transmite advertencias incluso en una compilación correcta. Detalle:

En --json o --quiet la invocación y la salida de compilación, vaya a stderr para que stdout permanezca puro JSON/limpio.

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

# 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

Propiedades de MSBuild (paquete NuGet):

Al usar el paquete NuGet de Microsoft.Windows.SDK.BuildTools.WinApp, dotnet run invoca automáticamente winapp run. Las siguientes propiedades de MSBuild se pueden establecer en .csproj para controlar el comportamiento:

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:

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 [options]

Opciones:

• --manifest <path> - Ruta de acceso a Package.appxmanifest (valor predeterminado: detección automática desde el directorio actual)
• --force : omita la comprobación del directorio install-location y anule el registro incluso si el paquete se registró desde un árbol de proyecto diferente.
• --json - Dar formato a la salida como JSON

Qué hace:

• Lee el nombre del paquete del 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 la ubicación de instalación del paquete está en el árbol de directorios actual (a menos --forceque )
• Anula el registro de los paquetes coincidentes

Ejemplos:

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

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

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

# 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> - Extracción de información del publicador de Package.appxmanifest
• --publisher <name>: Publisher para el certificado. 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>
• --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: "contraseña")
• --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": "..."}).

información del certificado

Mostrar los detalles del certificado desde un archivo PFX. 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)

Opciones:

• --password <password> - Contraseña para el archivo PFX (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> [options]

Argumentos:

• file-path - Ruta de acceso al paquete MSIX o ejecutable para firmar

Opciones:

• --cert <path> - Ruta de acceso al certificado de firma
• --cert-password <password> - Contraseña de certificado (valor predeterminado: "contraseña")

Ejemplos:

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

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-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

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:

• args... : argumentos para pasar directamente a la msstore CLI. Consulte la documentación de la CLI de MSStore para ver los comandos y las opciones disponibles.

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

find-ui

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]

El corpus se captura de GitHub en el primer uso y se almacena en caché por usuario en <global .winapp>/cache/find-ui, por lo que la primera ejecución requiere acceso a la red. Las ejecuciones posteriores se sirven desde la caché local (se actualizan como máximo cada 7 días o a petición con --refresh).

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

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.

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).

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

Opciones:

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:

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')

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 - Capturar ventana/elemento como PNG (captura automáticamente cuadros de diálogo por separado)
• 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

Opciones:

• -a, --app <app> - Aplicación de destino (nombre, título o PID)
• -w, --window <hwnd> - Ventana de destino por HWND (estable)

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 demo.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).
• --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 use ui screenshot --capture-screen para los elementos emergentes. Se realiza un seguimiento en #646.

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