Depuração com Identidade de Pacote

Muitas APIs do Windows (notificações push, tarefas em segundo plano, alvo de partilha, tarefas de arranque, e APIs de IA do Windows) exigem que a sua app tenha package identity. Durante o desenvolvimento, não quer construir um instalador MSIX completo sempre que testa — o winapp fornece dois comandos para atribuir a identidade da sua aplicação em tempo real.

Usar Visual Studio com um projeto de embalagem? Se já estiver a utilizar o Visual Studio para o seu projeto empacotado, provavelmente não precisa do winapp para debug. O Visual Studio já trata do registro de pacotes, identidade, ativação de AUMID, anexação do depurador e depuração do código de ativação — tudo mediante o F5. Também oferece Depurar → Outros Alvos de Depuração → Depurar Pacote de Aplicação Instalado para cenários avançados. Os fluxos de trabalho abaixo são mais úteis para utilizadores de VS Code, fluxos de trabalho baseados em terminais e frameworks que o VS não empacota nativamente (Rust, Flutter, Tauri, Electron, C++ simples).

Duas abordagens: winapp run vs create-debug-identity

Quando usar qual

Predefinição: winapp run

Usar winapp run para a maioria dos fluxos de trabalho de desenvolvimento. Simula uma instalação real do MSIX — a tua aplicação recebe a mesma identidade, capacidades e associações de ficheiros que teria em produção.

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

Utilize create-debug-identity quando:

• O teu exe é separado da tua saída de build — por exemplo, aplicações Electron onde electron.exe se encontra em node_modules/
• Precisas de depurar o código de arranque e não consegues anexar um depurador rápido o suficiente após o lançamento do AUMID
• Com alguns depuradores onde não se pode iniciar com AUMID e é necessário ter identidade no processo lançado — create-debug-identity regista o exe, por isso tem identidade independentemente de como foi iniciado
• Estás a testar especificamente o comportamento de pacotes esparsos (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

Cenários de depuração

Cenário A: Apenas operar com identidade

O fluxo de trabalho mais simples — construir, executar com identidade, concluído.

winapp run .\build\Debug

O Winapp regista a pasta como um pacote de layout solto e lança a aplicação. As APIs que exigem identidade funcionam imediatamente. Isto cobre a maioria dos cenários de desenvolvimento e testes.

Para aplicações de consola que precisam de stdin/stdout no terminal atual, adicione --with-alias:

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

Cenário B: Anexar um depurador a uma aplicação em execução

Inicia com winapp run, nota o PID, depois anexa o depurador do teu IDE.

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

Depois, no teu IDE:

• VS Code: Executar e Depurar → selecionar a configuração "Anexar" (ver configuração do IDE abaixo)
• WinDbg: windbg -p 12345

Limitação: Vai perder qualquer código que seja executado antes de te conectares. Para depuração de arranque, use o Cenário D (create-debug-identity).

Cenário C: Registe a identidade e depois inicia via AUMID ou alias a partir do teu IDE

Use --no-launch para registar o pacote, depois inicie a aplicação através do AUMID (reportado por run) ou alias de execução a partir do seu IDE.

Passo 1: Registe o pacote sem lançar:

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

Passo 2: Configura o teu IDE para lançar via AUMID ou pelo alias de execução (não diretamente pelo exe).

• Lançamento com AUMID: Use o comando start shell:AppsFolder\<AUMID>. winapp run gera o AUMID quando a aplicação está registada.
• Início com o alias: O alias deve ser definido no seu manifesto (Package.appxmanifest preferido, appxmanifest.xml também suportado).

Importante: Simplesmente lançar o exe na pasta de compilação não lhe dará identidade. A aplicação deve ser iniciada através da ativação AUMID ou do seu alias de execução. É assim que os pacotes de layout soltos funcionam – a identidade está ligada ao caminho de ativação, não ao ficheiro exe.

Cenário D: Iniciar a partir do seu IDE com identidade (depuração de arranque)

Esta é a melhor abordagem para depurar código de arranque com controlo total do IDE – o depurador do seu IDE controla o processo desde a primeira instrução, e o exe tem identidade independentemente de como for lançado.

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

Agora inicia o exe da forma que quiseres — a partir do terminal, do F5 do VS Code, de um script. O exe tem identidade porque Windows registou um pacote sparse apontando diretamente para ele.

Como difere de winapp run: Com create-debug-identity, a identidade está ligada ao próprio exe (via Add-AppxPackage -ExternalLocation). Com winapp run, a identidade está ligada ao pacote de layout flexível — o aplicativo deve ser iniciado através de AUMID ou de um apelido. Isto faz de create-debug-identity a melhor escolha quando você precisa que o seu IDE inicie e depure diretamente o arquivo exe.

Esta é também a melhor abordagem para aplicações Electron onde o caminho do exe difere do diretório de origem.

Cenário E: Captura de saída de depuração e diagnóstico de falhas

Capturar OutputDebugString mensagens e exceções de primeira ocorrência integradas. O ruído do framework (WinUI, COM, rastreios internos do DirectX) é filtrado da consola para que apenas apareçam as mensagens de depuração da aplicação. Tudo ainda está escrito no ficheiro de registo para investigação completa.

Se a aplicação crashar, um minidump é capturado e analisado automaticamente:

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

Em caso de falha, a saída inclui o tipo de exceção, a mensagem e o rastreamento de pilha com o ficheiro de origem e os números de linhas (resolvidos a partir dos PDBs no seu diretório de saída do build). As falhas geridas (.NET) são analisadas instantaneamente sem necessidade de ferramentas externas. Crashes nativos (C++/WinRT) mostram nomes e deslocamentos de módulos; adicionar --symbols para descarregar símbolos PDB para nomes completos de funções:

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

Importante: Isto designa o winapp como depurador. Windows só permite um depurador por processo, por isso não pode também anexar Visual Studio, VS Code ou WinDbg.

Configuração do IDE

Código VS

A extensão WinApp para VS Code fornece um tipo de depuração personalizadowinapp que inicia a sua aplicação com a identidade do pacote e anexa o depurador — tudo a partir de um único toque na tecla F5.

Depuração F5 com um único toque e identidade

Adicionar uma winapp configuração de lançamento a .vscode/launch.json:

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

Quando carregas em F5:

1. A extensão analisa o espaço de trabalho em busca de diretórios de saída de compilação contendo ficheiros .exe.
2. Selecionas a pasta de build para executar (ou defines inputFolder para saltar o prompt).
3. Ele lança a sua aplicação via winapp run para lhe dar identidade ao pacote.
4. Uma sessão de depuração secundária conecta-se ao processo em execução usando o depurador que especificou.

Depois de o depurador se conectar, obtém a experiência completa de depuração de VS Code — define pontos de interrupção clicando na caleira, percorre o código linha a linha (F10), entra nas funções (F11), inspeciona variáveis no painel de Variáveis e avalia expressões na Consola de Depuração. A aplicação corre com identidade de pacote em todo o processo, por isso as APIs dependentes da identidade comportam-se exatamente como se comportariam em produção.

Importante: O winapp tipo de depuração não constrói automaticamente o seu projeto. Depois de fazer alterações ao código, reconstrua antes de carregar em F5.

Automatizar builds com preLaunchTask

Para evitar esquecer de reconstruir, adicione um preLaunchTask que constrói o seu projeto antes de cada sessão de depuração:

1. Defina uma tarefa de build em .vscode/tasks.json (exemplo para .NET):

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

2. Refere-o no teu launch.json:

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

Propriedades de configuração

Depuradores suportados

Exemplo para um projeto em C++:

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

Depuração de início com Criar uma Identidade de Depuração

Se precisar de depurar o código de arranque a partir da primeira instrução, a abordagem de anexar com F5 pode perder as instruções iniciais. Em vez disso, use o comando WinApp: Create Debug Identity a partir da Paleta de Comandos (Ctrl+Shift+P) para registar um pacote esparso para o seu executável, depois lance-o com o seu depurador padrão:

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

Desde que create-debug-identity regista a identidade no próprio exe, a aplicação tem identidade independentemente da forma como é lançada — incluindo a partir de uma configuração padrão de lançamento do VS Code.

Anexar a um processo em execução

Se preferir lançar a partir winapp run do terminal e depois acoplar, use uma configuração padrão de união.

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

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

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

Limpeza

Quando você terminar os testes, execute WinApp: Unregister Package da Command Palette para remover pacotes sideloaded de desenvolvimento sem sair do VS Code.