使用 WinDbg 调试 UWP 应用

项目
05/27/2024

可以使用 WinDbg 调试通用 Windows 平台 (UWP) 应用。这种方法通常用于无法使用 Visual Studio 内置调试器完成调试任务的高级方案。有关在 Visual Studio 中进行调试模式的详细信息，请参阅在 Visual Studio 中进行调试。

附加到 UWP 应用

附加到 UWP 进程与附加到用户模式进程相同。例如，在 WinDbg 中，可以选择从文件附加到进程菜单或按 F6 键来附加到正在运行的进程。有关详细信息，请参阅使用 WinDbg 调试用户模式进程。

UWP 应用不会以与未调试时相同的方式暂停。要显式挂起/恢复 UWP 应用，则可以使用 .suspendpackage 和 .resumepackage 命令（详情如下）。有关 UWP 应用使用的进程生命周期管理 (PLM) 的一般信息，请参阅应用生命周期和启动、恢复和后台任务。

启动和调试 UWP 应用

-plmPackage 和 -plmApp 命令行参数指示调试器在调试器下启动一个应用。

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

由于单个包中可以包含多个应用，因此需要使用 <PLMPackage> 和 <ApplicationId> 两个参数。这是参数的摘要。

参数	描述
<PLMPackageName>	应用程序包的名称。使用 .querypackages 命令列出所有 UWP 应用程序。不要提供包位置的路径，只提供包名称。
<ApplicationId>	ApplicationId 位于应用程序清单文件中，可使用 .querypackage 或 .querypackages 命令查看，如本主题所述。有关应用程序清单文件的详细信息，请参阅应用程序包清单。
[<参数>]	传递给应用的可选参数。并非所有应用都使用或需要参数。

HelloWorld 示例

为了演示 UWP 调试，本主题将使用创建一个“Hello, world”应用 (XAML) 中描述的 HelloWorld 示例。

要创建一个可行的测试应用，只需完成实验室的第三步。

查找完整包名称和 AppId

使用 .querypackages 命令查找完整的包名称和 AppId。键入 .querypackages，然后使用 CRTL+F 在输出中搜索应用程序名称，如 HelloWorld。使用 CTRL+F 查找条目时，将显示包全名，例如 e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 和 App 的 AppId。

示例：

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

在清单中查看基本包名称

要进行故障排除，可能需要在 Visual Studio 中查看基础包名称。

要在 Visual Studio 中查找基本包名称，请单击项目资源管理器中的 ApplicationManifest.xml 文件。基本包名称将显示在打包选项卡下并显示为“包名称”。默认情况下，包名称为 GUID，例如 e24caf14-8483-4743-b80c-ca46c28c75df。

要使用记事本查找基本包名称，请打开 ApplicationManifest.xml 文件并找到 Identity Name 标记。

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

在清单中查找应用 ID

要在已安装的 UWP 应用的清单文件中查找应用程序 ID，请查找应用程序 ID 条目。

例如，hello world 应用的应用程序 ID 是 App。

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

WinDbg 命令行示例

这是一个使用完整包名称和 AppId 在调试器下加载 HelloWorld 应用的命令行示例。

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

在调试器下启动后台任务

后台任务可以通过命令行使用 TaskId 在调试器下显式启动。为此，请使用 -plmPackage 和 -plmBgTaskId 命令行参数：

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

参数

描述

应用程序包的名称。使用 .querypackages 命令列出所有 UWP 应用程序。不要提供包位置的路径，只提供包名称。

可使用 .querypackages 命令来查找 BackgroundTaskId，如下所述。

有关应用程序清单文件的详细信息，请参阅应用程序包清单。

这是一个在调试器下加载 SDKSamples.BackgroundTask 代码的示例。

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

可以尝试使用背景任务示例代码来熟悉 UWP 调试。它可在背景任务示例中下载。

使用 .querypackages 命令来查找 BackgroundTaskId。使用 CTRL-F 查找应用，然后找到后台任务 ID 字段。后台任务必须正在运行，才能显示相关的后台任务名称和任务 ID。

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}
...

如果知道包全名，就可以使用 .querypackage 来显示后台任务 ID 字段。

还可以使用 PLMDebug 的 enumerateBgTasks 选项来查找 BackgroundTaskId。有关 PMLDebug 实用工具的详细信息，请参阅 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

使用进程服务器 (DbgSrv) 远程调试 UWP 进程

所有 -plm* 命令都能与 dbgsrv 正常使用。要使用 dbgsrv 进行调试，请使用 -premote 开关和 dbgsrv 的连接字符串：

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

有关 -premote 选项的详细信息，请参阅进程服务器（用户模式）和进程服务器示例。

UWP 应用命令摘要

本部分概述了 UWP 应用调试器命令

收集包信息

.querypackage

.querypackage 显示 UWP 应用程序的状态。例如，如果应用正在运行，它可以处于活动状态。

.querypackage <PLMPackageName>

示例：

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

.querypackages 命令会列出所有已安装的 UWP 应用程序及其当前状态。

.querypackages

示例：

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

...

启动用于调试的应用

.createpackageapp

.createpackageapp 命令可启用调试并启动 UWP 应用程序。

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

此表列出了 .createpackageapp 的参数。

参数	描述
<PLMPackageName>	应用程序包的名称。使用 .querypackages 命令列出所有 UWP 应用程序。不要提供包位置的路径，只提供包名称。
<ApplicationId>	如本主题前面所述，可使用 .querypackage 或 .querypackages 来查找 ApplicationId。有关应用程序清单文件的详细信息，请参阅应用程序包清单。
[<参数>]	传递给应用程序的可选参数。并非所有应用程序都需要或使用这些可选参数。

示例：

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

启用和禁用调试命令的使用

.enablepackagedebug

使用 .enablepackagedebug 命令可以调试 UWP 应用程序。在调用任何挂起、恢复或终止函数之前，必须使用 .enablepackagedebug。

请注意，.createpackageapp 命令还可以调试应用程序。

.enablepackagedebug <PLMPackageName>

示例：

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

.disablepackagedebug

.disablepackagedebug 命令会禁用 UWP 应用程序的调试。

.disablepackagedebug <PLMPackageName>

示例：

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

启动和停止应用

请注意，挂起、恢复和终止会影响包中当前运行的所有应用。

.suspendpackage

.suspendpackage 命令可挂起 UWP 应用程序。

.suspendpackage <PLMPackageName>

示例：

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

.resumepackage

.resumepackage 命令可恢复 UWP 应用程序。

.resumepackage <PLMPackageName>

示例：

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

.terminatepackageapp

.terminatepackageapp 命令可终止包中的所有 UWP 应用程序。

.terminatepackageapp <PLMPackageName>

示例：

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

后台任务

.activatepackagebgtask

.activatepackagebgtask 命令可启用调试并启动 UWP 后台任务。

 .activatepackagebgtask <PLMPackageName> <bgTaskId>

示例：

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

用法示例

启动应用时附加调试器

假设有一个名为 HelloWorld 的应用，它位于一个名为 e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 的包中。通过显示所有已安装软件包的全名和运行状态来验证软件包是否已安装。在命令提示符窗口中输入以下命令。可以使用 CTRL+F 在命令输出中搜索应用名称 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

...

使用 .createpackageapp 启动并附加到应用。 .createpackageapp 命令还可以调试应用。

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

调试结束后，使用 .disablepackagedebug 命令递减包的调试引用计数。

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

将调试器附加到正在运行的应用

假设要将 WinDbg 附加到已在运行的 MyApp。在 WinDbg 的文件菜单中，选择附加到进程。记下 MyApp 的进程 ID。假设进程 ID 为 4816。递增包含 MyApp 的包的调试引用计数。

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

在 WinDbg 的附加到进程对话框中，选择进程 4816，然后单击“确定”。 WinDbg 将附加到 MyApp。

调试结束后，使用 .disablepackagedebug 命令递减包的调试引用计数。

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

手动暂停和恢复应用

按照以下步骤手动暂停和恢复应用。首先，递增包含应用的包调试引用计数。

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

挂起包。应用的挂起处理程序会被调用，这对于调试非常有用。

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

调试完成后，继续运行包。

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

最后，递减包的调试引用计数。

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

通过