Debugging a UWP app using WinDbg

Artikkeli
12/15/2021

You can debug Universal Windows Platform (UWP) app using WinDbg. This approach would typically be used for advanced scenarios, where it is not possible to complete the debugging task using the built in Visual Studio debugger. For more information about debugging in Visual Studio, see Debugging in Visual Studio.

Attaching to a UWP app

Attaching to UWP process is the same as attaching to a user mode process. For example, in WinDbg you can attach to a running process by choosing Attach to a Process from the File menu or by pressing F6. For more information, see Debugging a User-Mode Process Using WinDbg.

A UWP app will not be suspended in the same ways that it does when not being debugged. To explicitly suspend/resume a UWP app, you can use the .suspendpackage and .resumepackage commands (details below). For general information on Process Lifecycle Management (PLM) used by UWP apps, see App lifecycle and Launching, resuming, and background tasks.

Launching and debugging a UWP app

The -plmPackage and -plmApp command line parameters instruct the debugger to launch an app under the debugger.

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

Since multiple apps can be contained within a single package, both <PLMPackage> and <ApplicationId> parameters are required. This is a summary of the parameters.

Parameter	Description
<PLMPackageName>	The name of the application package. Use the .querypackages command to lists all UWP applications. Do not provide a path to the location of the package, provide just the package name.
<ApplicationId>	The ApplicationId is located in the application manifest file and can be viewed using the .querypackage or .querypackages command as discussed in this topic. For more information about the application manifest file, see App package manifest.
[<parameters>]	Optional parameters passed to the App. Not all apps use or require parameters.

HelloWorld Sample

To demonstrate UWP debugging, this topic uses the HelloWorld example described in Create a "Hello, world" app (XAML).

To create a workable test app, it is only necessary to complete up to step three of the lab.

Locating the Full Package Name and AppId

Use the .querypackages command to locate the full package name and the AppId. Type .querypackages and then use CTRL+F to search the output for the application name, such as HelloWorld. When the entry is located using CTRL+F, it will show the package full name, for example 00001111-aaaa-2222-bbbb-3333cccc4444_1.0.0.0_x86__97ghe447vaan8 and the AppId of App.

Example:

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

Viewing the Base Package Name in the in the Manifest

For troubleshooting, you may want to view the base package name in Visual Studio.

To locate the base package name in Visual Studio, click on the ApplicationManifest.xml file in project explorer. The base package name will be displayed under the packaging tab as "Package name". By default, the package name will be a GUID, for example 00001111-aaaa-2222-bbbb-3333cccc4444.

To use notepad to locate the base package name, open the ApplicationManifest.xml file and locate the Identity Name tag.

  <Identity
    Name="00001111-aaaa-2222-bbbb-3333cccc4444"
    Publisher="CN= User1"
    Version="1.0.0.0" />

Locating the Application Id in the Manifest

To locate the Application Id in the manifest file for an installed UWP app, look for the Application Id entry.

For example, for the hello world app the Application ID is App.

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

Example WinDbg Command Line

This is an example command line loading the HelloWorld app under the debugger using the full package name and AppId.

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

Launching a background task under the debugger

A background task can be explicitly launched under the debugger from the command line using the TaskId. To do this, use the -plmPackage and -plmBgTaskId command line parameters:

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

Parameter

Description

The name of the application package. Use the .querypackages command to lists all UWP applications. Do not provide a path to the location of the package, provide just the package name.

The BackgroundTaskId can be located using the .querypackages command as described below.

For more information about the application manifest file, see App package manifest.

This is an example of loading the SDKSamples.BackgroundTask code under the debugger.

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

You can experiment with the Background task sample code to become familiar with UWP debugging. It can be downloaded at Background task sample.

Use the .querypackages command to locate the BackgroundTaskId. Use CTRL-F to locate the app and then locate the Background Task Id field. The background task must be running to display the associated background task name and task 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}
...

If you know the full package name you can use .querypackage to display the Background Task Id field.

You can also locate the BackgroundTaskId by using the enumerateBgTasks option of the PLMDebug. For more information about the PMLDebug utility, see 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

Debugging a UWP process remotely using a Process Server (DbgSrv)

All of the -plm* commands work correctly with dbgsrv. To debug using dbgsrv, use the -premote switch with the connection string for dbgsrv:

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

For more information about the -premote options, see Process Servers (User Mode) and Process Server Examples.

Summary of UWP app commands

This section provides a summary of UWP app debugger commands

Gathering Package Information

.querypackage

The .querypackage displays the state of a UWP application. For example, if the app is running, it can be in the Active state.

.querypackage <PLMPackageName>

Example:

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

The .querypackages command lists all the installed UWP applications and their current state.

.querypackages

Example:

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

...

Launching an app for Debugging

.createpackageapp

The .createpackageapp command enables debugging and launches a UWP application.

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

This table lists the parameters for .createpackageapp.

Parameter	Description
<PLMPackageName>	The name of the application package. Use the .querypackages command to lists all UWP applications. Do not provide a path to the location of the package, provide just the package name.
<ApplicationId>	The ApplicationId can be located using .querypackage or .querypackages as discussed earlier in this topic. For more information about the application manifest file, see App package manifest.
[<parameters>]	Optional parameters that are passed to the application. Not all applications require or use these optional parameters.

Example:

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

Enabling and Disabling Use of Debug Commands

.enablepackagedebug

The .enablepackagedebug command enables debugging for UWP application. You must use .enablepackagedebug before you call any of the suspend, resume, or terminate functions.

Note that the .createpackageapp command also enables debugging of the app.

.enablepackagedebug <PLMPackageName>

Example:

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

.disablepackagedebug

The .disablepackagedebug command disables debugging for UWP application.

.disablepackagedebug <PLMPackageName>

Example:

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

Starting and Stopping apps

Note that suspend, resume, and terminate affect all currently running apps in the package.

.suspendpackage

The .suspendpackage command, suspends a UWP application.

.suspendpackage <PLMPackageName>

Example:

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

.resumepackage

The .resumepackage command resumes a UWP application.

.resumepackage <PLMPackageName>

Example:

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

.terminatepackageapp

The .terminatepackageapp command terminates the all of the UWP applications in the package.

.terminatepackageapp <PLMPackageName>

Example:

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

Background Tasks

.activatepackagebgtask

The .activatepackagebgtask command enables debugging and launches a UWP background task.

 .activatepackagebgtask <PLMPackageName> <bgTaskId>

Example:

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

Usage Examples

Attach a debugger when your app is launched

Suppose you have an app named HelloWorld that is in a package named 00001111-aaaa-2222-bbbb-3333cccc4444_1.0.0.0_x86__97ghe447vaan8. Verify that your package is installed by displaying the full names and running states all installed packages. In a Command Prompt window, enter the following command. You can use CTRL+F to search the command output for the app name of 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 to launch and attach to the app. The .createpackageapp command also enables debugging of the app.

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

When you have finished debugging, decrement the debug reference count for the package using the .disablepackagedebug command.

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

Attach a debugger to an app that is already running

Suppose you want to attach WinDbg to MyApp, which is already running. In WinDbg, on the File menu, choose Attach to a Process. Note the process ID for MyApp. Let's say the process ID is 4816. Increment the debug reference count for the package that contains MyApp.

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

In WinDbg, in the Attach to Process dialog box, select process 4816, and click OK. WinDbg will attach to MyApp.

When you have finished debugging, decrement the debug reference count for the package using the .disablepackagedebug command.

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

Manually suspend and resume your app

Follow these steps to manually suspend and resume your app. First, increment the debug reference count for the package that contains your app.

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

Suspend the package. Your app's suspend handler is called, which can be helpful for debugging.

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

When you have finished debugging, resume the package.

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

Finally, decrement the debug reference count for the package.

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

Jaa

Debugging a UWP app using WinDbg

Attaching to a UWP app

Launching and debugging a UWP app

Launching a background task under the debugger

Debugging a UWP process remotely using a Process Server (DbgSrv)

Summary of UWP app commands

Usage Examples

See also

Palaute

Lisäresursseja