Depuración con identidad de paquete

Muchas API de Windows (notificaciones push, tareas en segundo plano, destino de recurso compartido, tareas de inicio Windows API de IA) requieren que la aplicación tenga package identity. Durante el desarrollo, no quieres compilar un instalador MSIX completo cada vez que lo pruebes — winapp proporciona dos comandos para proporcionar la identidad de la aplicación al vuelo.

¿Usar Visual Studio con un proyecto de empaquetado? Si ya está utilizando Visual Studio para tu proyecto empaquetado, quizás no necesites winapp para la depuración. Visual Studio ya gestiona el registro de paquetes, la identidad, la activación de AUMID, la vinculación del depurador y la depuración de código de activación, todo a través de F5. También ofrece depuración → otros destinos de depuración → Depurar paquete de aplicaciones instalado para escenarios avanzados. Los flujos de trabajo siguientes son más útiles para los usuarios de VS Code, los flujos de trabajo basados en terminales y los marcos que VS no empaqueta de forma nativa (Rust, Flutter, Tauri, Electron, plain C++).

Dos enfoques: `winapp run` frente a `create-debug-identity`

	`winapp run`	`create-debug-identity`
Lo que registra	Paquete de diseño flexible completo (carpeta completa)	Paquete disperso (exe único)
Cómo se inicia la aplicación	Iniciado por winapp (alias de activación o ejecución de AUMID)	Inicie el exe usted mismo (línea de comandos, IDE, etc.)
Simula la instalación de MSIX	Sí: más cercano al comportamiento de producción	No: solo identidad dispersa
Los archivos permanecen en su lugar	Copiado en un directorio de diseño de AppX	Sí — exe permanece en su camino original
Ámbito de identidad	Contenido completo de la carpeta (exe, DLL, assets)	Archivo ejecutable único
Depurador descriptivo	Adjúntese al PID después de iniciar, o utilice `--no-launch` y luego inicie a través de un alias.	Iniciar directamente desde el depurador del IDE: el exe tiene identidad independientemente de cualquier otra variable.
Compatibilidad con aplicaciones de consola	`--with-alias` mantiene stdin/stdout en el terminal	Ejecutar exe directamente en el terminal
Mejor para	Mayoría de los marcos (.NET, C++, Rust, Flutter, Tauri)	Electron, o cuando necesita un control completo del depurador IDE (F5)

Cuándo usar qué

Opción predeterminada: `winapp run`

Se usa winapp run para la mayoría de los flujos de trabajo de desarrollo. Simula una instalación de MSIX real: la aplicación obtiene la misma identidad, funcionalidades y asociaciones de archivos que tendría en producción.

# Build your app, then:
winapp run .\build\output

Utilice `create-debug-identity` si:

Tu exe es independiente de la salida de tu compilación, por ejemplo, las aplicaciones de Electron donde electron.exe se encuentra node_modules/
Debe depurar el código de inicio y no puede conectar un depurador con suficiente rapidez después del inicio de AUMID.
Con algunos depuradores en los que no se puede iniciar con AUMID y se necesita que el proceso iniciado tenga identidad, create-debug-identity registra el exe para que tenga identidad sin importar cómo se inicie.
Está probando el comportamiento disperso del paquete específicamente (AllowExternalContent, TrustedLaunch)

# Register identity for an exe, then launch it however you want:
winapp create-debug-identity .\bin\Debug\myapp.exe
.\bin\Debug\myapp.exe   # or F5 in your IDE

Escenarios de depuración

Escenario A: Simplemente ejecutar con identidad

El flujo de trabajo más sencillo: compilar, ejecutar con identidad, hecho.

winapp run .\build\Debug

Winapp registra la carpeta como un paquete de diseño flexible e inicia la aplicación. Las API que requieren identidad funcionan inmediatamente. Esto abarca la mayoría de los escenarios de desarrollo y pruebas.

Para las aplicaciones de consola que necesitan stdin/stdout en el terminal actual, agregue --with-alias:

winapp run .\build\Debug --with-alias

Escenario B: Adjuntar un depurador a una aplicación en ejecución

Inicie con winapp run, anote el PID y, a continuación, adjunte el depurador del IDE.

winapp run .\build\Debug
# Output: Process ID: 12345

A continuación, en tu IDE:

VS Code: ejecutar y depurar → seleccionar la configuración "Adjuntar" (consulte la configuración del IDE a continuación)
WinDbg: windbg -p 12345

Limitación: Se perderá cualquier código que se ejecute antes de adjuntarlo. Para la depuración del arranque, use el escenario D (create-debug-identity).

Escenario C: Registrar identidad y, a continuación, iniciar a través de AUMID o alias desde el IDE

Use --no-launch para registrar el paquete y, a continuación, inicie la aplicación a través de su AUMID (notificado por run) o alias de ejecución desde el IDE.

Paso 1: Registre el paquete sin iniciar:

winapp run .\build\Debug --no-launch

Paso 2: Configure el IDE para que se inicie a través del AUMID o el alias de ejecución (no el exe directamente).

Iniciar con AUMID: use el comando start shell:AppsFolder\<AUMID>. winapp run genera el AUMID cuando se registra la aplicación.
Iniciar con el alias: el alias debe definirse en el manifiesto (Package.appxmanifest preferido, appxmanifest.xml también compatible).

Importante: Simplemente iniciar el archivo exe en la carpeta de compilación no le dará identidad. La aplicación debe iniciarse a través de la activación de AUMID o su alias de ejecución. Este es el funcionamiento de los paquetes de diseño flexible: la identidad está vinculada a la ruta de activación, no al archivo exe.

Escenario D: Lanzamiento desde el IDE con configuración de identidad (depuración en el arranque)

Este es el mejor enfoque para depurar código de inicio con control IDE completo : el depurador del IDE controla el proceso desde la primera instrucción y el exe tiene identidad independientemente de cómo se inicie.

winapp create-debug-identity .\build\Debug\myapp.exe

Ahora inicie el archivo exe de la manera que quiera desde el terminal, desde el F5 de VS Code, desde un script. El exe tiene identidad porque Windows registró un paquete sparse apuntando directamente a él.

Cómo difiere de winapp run: con create-debug-identity, la identidad está vinculada al propio exe (a través de Add-AppxPackage -ExternalLocation). Con winapp run, la identidad está vinculada al paquete de diseño flexible; la aplicación debe iniciarse a través de AUMID o un alias. Esto hace create-debug-identity la mejor opción cuando necesita que el IDE inicie y depure el exe directamente.

Este es también el mejor enfoque para las aplicaciones Electron donde la ruta de acceso del ejecutable difiere del directorio de origen.

Escenario E: Captura de salida de depuración y diagnósticos de bloqueo

Capture OutputDebugString mensajes y excepciones de primera oportunidad en línea. El ruido del framework (WinUI, COM, seguimientos internos de DirectX) se filtra en la consola, por lo que solo aparecen los mensajes de depuración de tu aplicación. Todo continúa registrado en el fichero de registro para llevar a cabo una investigación exhaustiva.

Si la aplicación se bloquea, se captura y analiza automáticamente un minivolcado:

winapp run .\build\Debug --debug-output

En caso de falla, la salida incluye el tipo de excepción, el mensaje y el seguimiento de pila con el nombre del archivo fuente y números de línea (resueltos desde archivos PDB en la carpeta de salida de compilación). Los fallos administrados (.NET) se analizan de inmediato sin necesidad de herramientas externas. Los fallos nativos (C++/WinRT) muestran los nombres y desplazamientos de los módulos; agregue --symbols para descargar símbolos de PDB y obtener los nombres completos de las funciones.

winapp run .\build\Debug --debug-output --symbols

Importante: Esto asocia winapp como depurador. Windows solo permite un depurador por proceso, por lo que no puedes conectar Visual Studio, VS Code o WinDbg.

Configuración del IDE

VS Code

La extensión WinApp VS Code proporciona un tipo de depuración personalizadowinapp que inicia la aplicación con la identidad del paquete y adjunta el depurador, todo ello desde una sola tecla F5.

Depuración F5 con un solo toque, con identidad

Agregue una winapp configuración de inicio a .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "winapp",
            "request": "launch",
            "name": "WinApp: Launch and Attach"
        }
    ]
}

Al presionar F5:

La extensión examina el área de trabajo para ver los directorios de salida de compilación que contienen .exe archivos.
Seleccione la carpeta de compilación para ejecutar (o establezca inputFolder para omitir el mensaje).
Inicia tu aplicación a través de winapp run para concederle la identidad del paquete.
Una sesión de depuración secundaria se conecta al proceso en ejecución mediante el depurador especificado.

Una vez que el depurador se conecta, obtiene la experiencia completa de depuración de VS Code: establezca puntos de interrupción haciendo clic en el margen, recorra el código línea a línea (F10), adéntrese en las funciones (F11), inspeccione las variables en el panel Variables y evalúe las expresiones en la Consola de Depuración. La aplicación se ejecuta con la identidad del paquete a lo largo de todo, por lo que las API dependientes de la identidad se comportan exactamente como lo harían en producción.

Importante: El winapp tipo de depuración no compila automáticamente tu proyecto. Después de realizar cambios en el código, recompila antes de presionar F5.

Automatización de compilaciones con `preLaunchTask`

Para evitar olvidar la recompilación, agregue un preLaunchTask que compile el proyecto antes de cada sesión de depuración:

Defina una tarea de compilación en .vscode/tasks.json (por ejemplo, .NET):

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": ["build", "${workspaceFolder}"],
            "problemMatcher": "$msCompile"
        }
    ]
}

Haga referencia a él en launch.json:

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch and Attach",
    "preLaunchTask": "build"
}

Propiedades de configuración

Propiedad	Tipo	Predeterminado	Description
`inputFolder`	string		Ruta de acceso a la carpeta de salida de compilación que contiene los archivos binarios de la aplicación (por ejemplo, `${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621`). Si no se establece, se le pedirá que seleccione una carpeta.
`manifest`	string		Ruta de acceso a un archivo de manifiesto de AppX (por ejemplo, `AppxManifest.xml`, `Package.appxmanifest`o `appxmanifest.xml`). Si no se establece, la CLI detecta automáticamente desde la carpeta de entrada o el directorio actual.
`debuggerType`	string	`coreclr`	Depurador subyacente que se va a usar (`coreclr`, `cppvsdbg`o `node`).
`workingDirectory`	string	carpeta del área de trabajo	Directorio de trabajo de la aplicación.
`args`	string		Argumentos de línea de comandos que se van a pasar a la aplicación.
`outputAppxDirectory`	string		Directorio de salida del paquete de diseño flexible. El valor predeterminado es una carpeta `AppX` dentro de la carpeta de entrada.
`port`	número	`9229`	(`node` solo) Puerto utilizado para el servidor de escucha Node.js `--inspect` y la conexión de adjuntar. Anule cuando el puerto predeterminado ya está en uso.

Depuradores soportados

`debuggerType`	Language	Extensión necesaria
`coreclr` (valor predeterminado)	C# /.NET	Kit de desarrollo de C#
`cppvsdbg`	C/C++	C/C++
`node`	Node.js / Electron	Integrado

Ejemplo de un proyecto de C++:

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch C++ App",
    "debuggerType": "cppvsdbg"
}

Depuración de inicio con Creación de una identidad de depuración

Si necesita depurar el código de inicio desde la primera instrucción, el método de conexión F5 puede ignorar el código inicial. En su lugar, use el comando WinApp: Crear identidad de depuración desde la paleta de comandos (Ctrl+Shift+P) para registrar un paquete disperso para el archivo ejecutable y, a continuación, iniciarlo con el depurador estándar:

{
    "name": "Launch (with identity)",
    "type": "coreclr",
    "request": "launch",
    "program": "${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621/myapp.exe"
}

Dado que create-debug-identity registra la identidad en el propio archivo ejecutable (exe), la aplicación mantiene su identidad independientemente de cómo se inicie, incluso desde una configuración de lanzamiento típica de VS Code.

Asociación a un proceso en ejecución

Si prefiere iniciar con winapp run desde el terminal y, a continuación, adjuntar, use una configuración de asociación estándar:

{
    "name": "Attach to Process",
    "type": "coreclr",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

Para C++/Rust, use "type": "cppvsdbg" (MSVC) o "type": "lldb" (LLDB):

{
    "name": "Attach (C++)",
    "type": "cppvsdbg",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

Limpieza

Cuando haya terminado de probar, ejecute WinApp: Anular el registro del paquete desde la paleta de comandos para eliminar los paquetes de desarrollo cargados lateralmente sin salir de VS Code.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-05-12