Depurar um aplicativo UWP usando WinDbg

Artigo
05/28/2024

Você pode depurar o aplicativo UWP (Plataforma Universal do Windows) usando o WinDbg. Esta abordagem geralmente será usada para cenários avançados, nos quais não é possível concluir a tarefa de depuração usando o depurador interno do Visual Studio. Para obter mais informações sobre como depurar no Visual Studio, confira Depurar no Visual Studio.

Anexar a um aplicativo UWP

Anexar ao processo UWP é o mesmo que anexar a um processo de modo de usuário. Por exemplo, no WinDbg, você pode anexar a um processo em execução escolhendo Anexar a um processo no menu Arquivo ou pressionando F6. Para obter mais informações, confira Depurar um processo de modo de usuário usando o WinDbg.

Um aplicativo UWP não será suspenso da mesma forma que quando não estiver sendo depurado. Para suspender/retomar explicitamente um aplicativo UWP, você poderá usar os comandos .suspendpackage e .resumepackage (detalhes abaixo). Para obter informações gerais sobre o PLM (Gerenciamento do Ciclo de Vida do Processo) usado por aplicativos UWP, confira Ciclo de vida do aplicativo e Iniciar, retomar e tarefas em segundo plano.

Iniciar e depurar um aplicativo UWP

Os parâmetros de linha de comando -plmPackage e -plmApp instruem o depurador a iniciar um aplicativo no depurador.

windbg.exe -plmPackage <PLMPackageName> -plmApp <ApplicationId> [<parameters>]

Como vários aplicativos podem estar contidos em um único pacote, os parâmetros <PLMPackage> e <ApplicationId> são obrigatórios. Este é um resumo dos parâmetros.

Parâmetro	Descrição
<PLMPackageName>	O nome do pacote de aplicativos. Use o comando .querypackages para listar todos os aplicativos UWP. Não forneça um caminho para o local do pacote, forneça apenas o nome do pacote.
<ApplicationId>	O ApplicationId está localizado no arquivo de manifesto do aplicativo e pode ser exibido usando o comando .querypackage ou .querypackages, conforme discutido neste tópico. Para obter mais informações sobre o arquivo de manifesto do aplicativo, confira Manifesto do pacote de aplicativos.
[<parâmetros>]	Parâmetros opcionais passados para o aplicativo. Nem todos os aplicativos usam ou exigem parâmetros.

Exemplo de HelloWorld

Para demonstrar a depuração UWP, este tópico usa o exemplo HelloWorld descrito em Criar um aplicativo "Olá, Mundo" (XAML).

Para criar um aplicativo de teste viável, só é necessário concluir até a etapa três do laboratório.

Localizar o nome completo do pacote e AppId

Use o comando .querypackages para localizar o nome completo do pacote e o AppId. Digite .querypackages e se as teclas CRTL+F para pesquisar na saída o nome do aplicativo, como HelloWorld. Quando a entrada for localizada usando CTRL+F, ela mostrará o nome completo do pacote (por exemplo, e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8) e o AppId de App.

Exemplo:

0:000>  .querypackages 
...
Package Full Name: e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8
Package Display Name: HelloWorld
Version: 1.0.0.0
Processor Architecture: x86
Publisher: CN=user1
Publisher Display Name: user1
Install Folder: c:\users\user1\documents\visual studio 2015\Projects\HelloWorld\HelloWorld\bin\x86\Release\AppX
Package State: Unknown
AppId: App
...

Exibir o nome do pacote base no manifesto

Para solução de problemas, convém exibir o nome do pacote base no Visual Studio.

Para localizar o nome do pacote base no Visual Studio, clique no arquivo ApplicationManifest.xml no explorador de projetos. O nome do pacote base será exibido na guia de empacotamento como "Nome do pacote". Por padrão, o nome do pacote será um GUID; por exemplo, e24caf14-8483-4743-b80c-ca46c28c75df.

Para usar o bloco de notas para localizar o nome do pacote base, abra o arquivo ApplicationManifest.xml e localize a marcação Nome da Identidade.

  <Identity
    Name="e24caf14-8483-4743-b80c-ca46c28c75df"
    Publisher="CN= User1"
    Version="1.0.0.0" />

Localizar a ID do aplicativo no manifesto

Para localizar a ID do Aplicativo no arquivo de manifesto de um aplicativo UWP instalado, procure a entrada ID do Aplicativo.

Por exemplo, para o aplicativo hello world, a ID do Aplicativo é App.

<Application Id="App"
      Executable="$targetnametoken$.exe"
      EntryPoint="HelloWorld.App">

Exemplo de linha de comando WinDbg

Este é um exemplo de linha de comando ao carregar o aplicativo HelloWorld no depurador usando o nome completo do pacote e o AppId.

windbg.exe -plmPackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 -plmApp App

Iniciar uma tarefa em segundo plano no depurador

Uma tarefa em segundo plano pode ser explicitamente iniciada no depurador a partir da linha de comando usando o TaskId. Para fazer isso, use os parâmetros de linha de comando -plmPackage e -plmBgTaskId:

windbg.exe -plmPackage <PLMPackageName> -plmBgTaskId <BackgroundTaskId>

Parâmetro

Descrição

O nome do pacote de aplicativos. Use o comando .querypackages para listar todos os aplicativos UWP. Não forneça um caminho para o local do pacote, forneça apenas o nome do pacote.

O parâmetro BackgroundTaskId pode ser localizado usando o comando .querypackages, conforme descrito abaixo.

Para obter mais informações sobre o arquivo de manifesto do aplicativo, confira Manifesto do pacote de aplicativos.

Este é um exemplo de carregamento do código SDKSamples.BackgroundTask no depurador.

windbg.exe -plmPackage Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x64__8wekyb3d8bbwe -plmBgTaskId {ee4438ee-22db-4cdd-85e4-8ad8a1063523}

Você pode experimentar o código de exemplo da Tarefa em segundo plano para se familiarizar com a depuração UWP. Ele pode ser baixado em Exemplo de tarefa em segundo plano.

Use o comando .querypackages para localizar o parâmetro BackgroundTaskId. Use CTRL-F para localizar o aplicativo e, em seguida, localize o campo ID da Tarefa em Segundo Plano. A tarefa em segundo plano deve estar em execução para exibir o nome da tarefa em segundo plano e a ID da tarefa associada.

0:000> .querypackages
...
Package Full Name: Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x86__8wekyb3d8bbwe
Package Display Name: BackgroundTask C++ sample
Version: 1.0.0.0
Processor Architecture: x86
Publisher: CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US
Publisher Display Name: Microsoft Corporation
Install Folder: C:\Users\user1\Documents\Visual Studio 2015\Projects\Background_task_sample\C++\Debug\BackgroundTask.Windows\AppX
Package State: Running
AppId: BackgroundTask.App
Background Task Name: SampleBackgroundTask
Background Task Id: {ee4438ee-22db-4cdd-85e4-8ad8a1063523}
...

Se você souber o nome completo do pacote, poderá usar .querypackage para exibir o campo ID da Tarefa em Segundo Plano.

Você também pode localizar o parâmetro BackgroundTaskId usando a opção enumerateBgTasks do PLMDebug. Para obter mais informações sobre o utilitário PMLDebug, confira PLMDebug.

C:\Program Files\Debugging Tools for Windows (x64)>PLMDebug /enumerateBgTasks Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x64__8wekyb3d8bbwe
Package full name is Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x64__8wekyb3d8bbwe.
Background Tasks:
SampleBackgroundTask : {C05806B1-9647-4765-9A0F-97182CEA5AAD}

SUCCEEDED

Depurar um processo UWP remotamente usando um Servidor de Processo (DbgSrv)

Todos os comandos -plm* funcionam corretamente com dbgsrv. Para depurar usando dbgsrv, use a opção -premote com a cadeia de conexão para dbgsrv:

windbg.exe -premote npipe:pipe=fdsa,server=localhost -plmPackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 -plmApp App

Para obter mais informações sobre as opções -premote, confira Servidores de Processo (Modo de Usuário) e Exemplos de Servidor de Processo.

Resumo dos comandos do aplicativo UWP

Esta seção fornece um resumo dos comandos do depurador de aplicativo UWP.

Coletar informações do pacote

.querypackage

O .querypackage exibe o estado de um aplicativo UWP. Por exemplo, se o aplicativo estiver em execução, poderá estar no estado Ativo.

.querypackage <PLMPackageName>

Exemplo:

0:000> .querypackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8
Package Full Name: e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8
Package Display Name: HelloWorld
Version: 1.0.0.0
Processor Architecture: x86
Publisher: CN=user1
Publisher Display Name: user1
Install Folder: c:\users\user1\documents\visual studio 2015\Projects\HelloWorld\HelloWorld\bin\x86\Release\AppX
Package State: Running
AppId: App
Executable: HelloWorld.exe

.querypackages

O comando .querypackages lista todos os aplicativos UWP instalados e seu estado atual.

.querypackages

Exemplo:

0:000> .querypackages
...
Package Full Name: Microsoft.MicrosoftSolitaireCollection_3.9.5250.0_x64__8wekyb3d8bbwe
Package Display Name: Microsoft Solitaire Collection
Version: 3.9.5250.0
Processor Architecture: x64
Publisher: CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US
Publisher Display Name: Microsoft Studios
Install Folder: C:\Program Files\WindowsApps\Microsoft.MicrosoftSolitaireCollection_3.9.5250.0_x64__8wekyb3d8bbwe
Package State: Unknown
AppId: App

Package Full Name: e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8
Package Display Name: HelloWorld
Version: 1.0.0.0
Processor Architecture: x86
Publisher: CN=user1
Publisher Display Name: user1
Install Folder: c:\users\user1\documents\visual studio 2015\Projects\HelloWorld\HelloWorld\bin\x86\Release\AppX
Package State: Running
AppId: App
Executable: HelloWorld.exe

Package Full Name: Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x86__8wekyb3d8bbwe
Package Display Name: BackgroundTask C++ sample
Version: 1.0.0.0
Processor Architecture: x86
Publisher: CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US
Publisher Display Name: Microsoft Corporation
Install Folder: C:\Users\user1\Documents\Visual Studio 2015\Projects\Background_task_sample\C++\Debug\BackgroundTask.Windows\AppX
Package State: Unknown
AppId: BackgroundTask.App

...

Iniciar um aplicativo para depuração

.createpackageapp

O comando .createpackageapp habilita a depuração e inicia um aplicativo UWP.

.createpackageapp <PLMPackageName> <ApplicationId> [<parameters>]

Esta tabela lista os parâmetros para .createpackageapp.

Parâmetro	Descrição
<PLMPackageName>	O nome do pacote de aplicativos. Use o comando .querypackages para listar todos os aplicativos UWP. Não forneça um caminho para o local do pacote, forneça apenas o nome do pacote.
<ApplicationId>	O ApplicationId pode ser localizado usando .querypackage ou .querypackages, conforme discutido anteriormente neste tópico. Para obter mais informações sobre o arquivo de manifesto do aplicativo, confira Manifesto do pacote de aplicativos.
[<parâmetros>]	Parâmetros opcionais que são passados para o aplicativo. Nem todos os aplicativos exigem ou usam esses parâmetros opcionais.

Exemplo:

.createpackageapp e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 App

Habilitar e desabilitar o uso de comandos de depuração

.enablepackagedebug

O comando .enablepackagedebug habilita a depuração do aplicativo UWP. Você deve usar .enablepackagedebug antes de chamar qualquer uma das funções de suspender, retomar ou encerrar.

O comando .createpackageapp também habilita a depuração do aplicativo.

.enablepackagedebug <PLMPackageName>

Exemplo:

.enablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

.disablepackagedebug

O comando .disablepackagedebug desabilita a depuração do aplicativo UWP.

.disablepackagedebug <PLMPackageName>

Exemplo:

.disablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

Iniciar e parar os aplicativos

Observe que suspender, retomar e encerrar afetam todos os aplicativos atualmente em execução no pacote.

.suspendpackage

O comando .suspendpackage suspende um aplicativo UWP.

.suspendpackage <PLMPackageName>

Exemplo:

0:024> .suspendpackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

.resumepackage

O comando .resumepackage retoma um aplicativo UWP.

.resumepackage <PLMPackageName>

Exemplo:

.resumepackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

.terminatepackageapp

O comando .terminatepackageapp encerra todos os aplicativos UWP no pacote.

.terminatepackageapp <PLMPackageName>

Exemplo:

.terminatepackageapp e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

Tarefas em segundo plano

.activatepackagebgtask

O comando .activatepackagebgtask habilita a depuração e inicia uma tarefa em segundo plano do UWP.

 .activatepackagebgtask <PLMPackageName> <bgTaskId>

Exemplo:

.activatepackagebgtask Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x64__8wekyb3d8bbwe {C05806B1-9647-4765-9A0F-97182CEA5AAD}

Exemplos de uso

Anexar um depurador quando o aplicativo for iniciado

Suponha que você tenha um aplicativo chamado de HelloWorld que esteja em um pacote nomeado e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8. Verifique se o pacote está instalado exibindo os nomes completos e os estados de execução de todos os pacotes instalados. Em uma janela do Prompt de Comando, digite o comando a seguir. Você pode usar CTRL+F para pesquisar a saída do comando para o nome do aplicativo HelloWorld.

.querypackages 
...

Package Full Name: e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8
Package Display Name: HelloWorld
Version: 1.0.0.0
Processor Architecture: x86
Publisher: CN=user1
Publisher Display Name: user1
Install Folder: c:\users\user1\documents\visual studio 2015\Projects\HelloWorld\HelloWorld\bin\x86\Release\AppX
Package State: Unknown
AppId: App

...

Use .createpackageapp para iniciar e anexar ao aplicativo. O comando .createpackageapp também habilita a depuração do aplicativo.

.createpackageapp e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 App

Quando você tiver concluído a depuração, reduza a contagem de referência de depuração do pacote usando o comando .disablepackagedebug.

.disablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

Anexar um depurador a um aplicativo que já está em execução

Suponha que você queira anexar o WinDbg a MyApp, que já está em execução. No WinDbg, no menu Arquivo, escolha Anexar a um Processo. Anote a ID do processo para MyApp. Digamos que a ID do processo seja 4816. Incremente a contagem de referência de depuração para o pacote que contém MyApp.

.enablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

No WinDbg, na caixa de diálogo Anexar ao Processo, selecione o processo 4816 e clique em OK. O WinDbg será anexado ao MyApp.

Quando você tiver concluído a depuração, reduza a contagem de referência de depuração do pacote usando o comando .disablepackagedebug.

.disablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

Suspender e retomar manualmente o aplicativo

Siga estas etapas para suspender e retomar manualmente o aplicativo. Primeiro, incremente a contagem de referência de depuração para o pacote que contém o aplicativo.

.enablepackagedebug  e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

Suspenda o pacote. O manipulador de suspensão do aplicativo é chamado, o que pode ser útil para a depuração.

.suspendpackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

Quando terminar a depuração, retome o pacote.

.resumepackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

Por fim, reduza a contagem de referência de depuração do pacote.

.disablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8

Compartilhar via

Depurar um aplicativo UWP usando WinDbg

Anexar a um aplicativo UWP

Iniciar e depurar um aplicativo UWP

Iniciar uma tarefa em segundo plano no depurador

Depurar um processo UWP remotamente usando um Servidor de Processo (DbgSrv)

Resumo dos comandos do aplicativo UWP

Exemplos de uso

Consulte também

Comentários

Recursos adicionais