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 conviene compilar un instalador MSIX completo cada vez que se realice una prueba; winapp proporciona dos comandos para indicar la identidad de la aplicación sobre la marcha.

¿Usar Visual Studio con un proyecto de empaquetado? Si ya está utilizando Visual Studio para un proyecto empaquetado, es probable que no necesite 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 mediante 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

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:

• El exe es independiente de la salida de la compilación; por ejemplo, las aplicaciones de Electron donde reside electron.exe en 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: Ejecución simple 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 de inicio, se debe usar 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 identidad (depuración de inicio)

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 la salida de depuración y diagnóstico de bloqueo

Capture OutputDebugString mensajes y excepciones de primera oportunidad en línea. El ruido del marco (WinUI, COM, seguimientos internos de DirectX) se filtra desde la consola, por lo que solo aparecen los mensajes de depuración de la 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 bloqueo, la salida incluye el tipo de excepción, el mensaje y el seguimiento de pila con el archivo de origen y los números de línea (resueltos desde PDB en la carpeta de salida de la compilación). Los fallos administrados (.NET) se analizan de inmediato sin necesidad de herramientas externas. Los bloqueos nativos (C++/WinRT) muestran los nombres de módulo y los desplazamientos; agregue --symbols para descargar símbolos de PDB y obtener nombres de función completos.

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.

Análisis de excepciones almacenadas de WinUI

La mayoría de los bloqueos de WinUI comienzan dentro de un controlador de eventos de XAML y se manifiestan como una excepción almacenada (0xC000027B) que se vuelve a generar más tarde desde el distribuidor, por lo que la pila habitual ya no apunta a la causa real. Cuando la aplicación bloqueada carga Microsoft.UI.Xaml.dll, winapp ejecuta automáticamente una pasada adicional de evaluación que decodifica la excepción almacenada y la cadena de distribución nativa de XAML (Microsoft.UI.Xaml → CXcpDispatcher → CoreMessagingXP → host de CLR). El resultado se añade al registro de depuración. No se requiere ningún indicador: se habilita automáticamente para los volcados de WinUI. Agregue --symbols para obtener nombres de función totalmente resueltos en la cadena de distribución.

Para que esto funcione, winapp captura el volcado de memoria con el registro de la excepción almacenada de terminación (y sus parámetros, que apuntan a la matriz de excepciones permitidas) al tiempo que mantiene el contexto del subproceso de primera oportunidad, por lo que el análisis administrado estándar todavía recupera el marco de usuario original y la pasada de evaluación puede localizar la excepción almacenada.

Esta pasada aloja DbgEng con la extensión de JavaScript WinDbg del equipo de WinUI. El motor de depuración procede de NuGet; JsProvider.dll (el host de JavaScript, no publicado en NuGet) se obtiene la primera vez que se usa desde la descarga oficial de WinDbg. Ambos están fijados a una versión y se verifican antes de cargarse mediante hashes de contenido SHA-512, además de una comprobación de la firma Authenticode de Microsoft en JsProvider.dll y cualquier fallo de verificación omite la evaluación de prioridades en lugar de cargar código no verificado. Todo se almacena en caché en el directorio global de winapp, por lo que las ejecuciones posteriores están sin conexión.

Si el entorno bloquea esas descargas, instale herramientas de depuración para Windows (a través del SDK de Windows) o establezca en WINAPP_DBGTOOLS_DIR un directorio del depurador que contenga dbgeng.dll y JsProvider.dll. Cuando se establece WINAPP_DBGTOOLS_DIR, tiene carácter autoritativo —solo se consulta ese directorio— y, si está incompleto, el registro indica el componente que falta.

Cuando el triaje tiene éxito, la consola muestra un resultado en una sola línea (el código/mensaje de error de la excepción almacenada). Cuando no se puede ejecutar, la consola lo dice, el registro explica por qué y el análisis administrado o nativo estándar se sigue ejecutando.

El pase de evaluación de prioridades se ejecuta en un proceso secundario de corta duración, ya que el proceso principal de winapp ya ha cargado el sistema dbghelp.dll y el dbgeng.dll moderno no se puede enlazar junto a él. La descodificación de las estructuras de excepciones almacenadas también necesita símbolos del SO (combase.dll), que --symbols descarga del servidor público de símbolos de Microsoft; en las compilaciones cuyos símbolos no se publican allí, la evaluación de prioridades sigue identificando la excepción almacenada, pero no puede expandirla por completo.

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. Instálelo desde Visual Studio Marketplace; su origen y seguimiento de problemas se encuentra en el repositorio microsoft/WinAppVSCE.

Depuración con identidad con una sola pulsación de F5

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:

1. La extensión examina el área de trabajo para ver los directorios de salida de compilación que contienen .exe archivos.
2. Seleccione la carpeta de compilación para ejecutar (o establezca inputFolder para omitir el mensaje).
3. Inicia tu aplicación a través de winapp run para concederle la identidad del paquete.
4. 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 el 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:

1. 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"
           }
       ]
   }
   

2. Haga referencia a él en launch.json:

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

Propiedades de configuración

Depuradores admitidos

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, es posible que el método de asociación con F5 omita parte del 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 registro del paquete desde la paleta de comandos para eliminar los paquetes de desarrollo cargados lateralmente sin salir de VS Code.