Debugging a UWP app using WinDbg
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 |
| <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. |
| <BackgroundTaskId> | 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