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.

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.

Detección automática de proyectos .NET:

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)

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

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.

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)

winapp pack <input-folder> [options]

Argumentos:

• input-folder - Directorio que contiene los archivos de aplicación que se van a empaquetar

Opciones:

• --output <filename> - Nombre de archivo MSIX de salida (valor predeterminado: <name>_<version>_<arch>.msix, revertir a <name>_<version>.msix, <name>_<arch>.msixo cuando no se puede determinar la versión o <name>.msix el arco)
• --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>: nombre de Publisher para la generación de certificados
• --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 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

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

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

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 CN (valor predeterminado: CN=< usuario actual>)
• --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.

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

Argumentos:

• input-folder - Directorio que contiene la aplicación que se va a ejecutar (obligatorio)

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

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:

<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>: nombre de Publisher para el certificado
• --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

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

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.

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)
• 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)
• set-value - Establecer el valor en el elemento editable (texto, número)
• 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)

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