Depurando um aplicativo UWP usando WinDbg

Você pode depurar Plataforma Universal do Windows aplicativo (UWP) usando WinDbg. Essa abordagem normalmente seria usada para cenários avançados, em que não é possível concluir a tarefa de depuração usando o depurador interno do Visual Studio. Para obter mais informações sobre a depuração no Visual Studio, consulte Depuração 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, consulte Depurando um processo de User-Mode usando o WinDbg.

Um aplicativo UWP não será suspenso da mesma maneira que quando não estiver sendo depurado. Para suspender/retomar explicitamente um aplicativo UWP, você pode 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, consulte Ciclo de vida do aplicativo e Iniciando, retomando e tarefas em segundo plano.

Iniciando e depurando 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 necessá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, consulte Manifesto do pacote do aplicativo.

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

Localizando o Nome completo do pacote e AppId

Use o comando .querypackages para localizar o nome completo do pacote e o AppId. Digite .querypackages e, em seguida, CRTL+F do usuário para pesquisar na saída o nome do aplicativo, como HelloWorld. Quando a entrada estiver 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 a AppId do 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
...

Exibindo o nome do pacote base no 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 gerenciador 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 Nome da Identidade .

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

Localizando 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">

Linha de comando winDbg de exemplo

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

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

Iniciando uma tarefa em segundo plano no depurador

Uma tarefa em segundo plano pode ser iniciada explicitamente no depurador da linha de comando usando a 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
<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.

<BackgroundTaskId>

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

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

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 de tarefa em segundo plano para se familiarizar com a depuração da UWP. Ele pode ser baixado em Exemplo de tarefa em segundo plano.

Use o comando .querypackages para localizar BackgroundTaskId. Use CTRL-F para localizar o aplicativo e 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 BackgroundTaskId usando a opção enumerateBgTasks do PLMDebug. Para obter mais informações sobre a utiltidade PMLDebug, consulte 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

Depurando 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 o 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, consulte 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 aplicativos UWP

Coletando informações do pacote

.querypackage

O .querypackage exibe o estado de um aplicativo UWP. Por exemplo, se o aplicativo estiver em execução, ele 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

...

Iniciando 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 estar localizado usando .querypackage ou .querypackages, conforme discutido anteriormente neste tópico.

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

[<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 para o aplicativo UWP. Você deve usar .enablepackagedebug antes de chamar qualquer uma das funções de suspensão, retomada ou término.

Observe que 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 para o aplicativo UWP.

.disablepackagedebug <PLMPackageName>

Exemplo:

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

Iniciando e parando aplicativos

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

.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 da 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 HelloWorld que esteja em um pacote chamado 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, insira o comando a seguir. Você pode usar CTRL+F para pesquisar na saída do comando 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 terminar de depurar, decremente a contagem de referência de depuração para o 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 ao MyApp, que já está em execução. No WinDbg, no menu Arquivo , escolha Anexar a um Processo. Observe 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 terminar de depurar, decremente a contagem de referência de depuração para o pacote usando o comando .disablepackagedebug.

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

Suspender e retomar manualmente seu aplicativo

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

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

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

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

Quando terminar de depurar, retome o pacote.

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

Por fim, decremente a contagem de referência de depuração para o pacote.

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

Confira também