Edit

Share via


PLMDebug

PLMDebug.exe is a tool that enables you to use the Windows debugger to debug Windows app, which run under Process Lifecycle Management (PLM). With PLMDebug, you can take manual control of suspending, resuming, and terminating a Windows app.

Tip  With Windows 10, version 1607 or later, you can use the UWP commands, such as .createpackageapp to debug UWP apps. For more information see Debugging a UWP app using WinDbg.

Where to get PLMDebug

PLMDebug.exe is included in Debugging Tools for Windows.

plmdebug /query [Package]
plmdebug /enableDebug Package [DebuggerCommandLine]
plmdebug /terminate Package
plmdebug /forceterminate Package
plmdebug /cleanterminate Package
plmdebug /suspend Package
plmdebug /resume Package
plmdebug /disableDebug Package
plmdebug /enumerateBgTasks Package
plmdebug /activateBgTask "{TaskID}"

Parameters

Package
The full name of a package or the ID of a running process.

DebuggerCommandLine
A command line to open a debugger. The command line must include the full path to the debugger. If the path has blank spaces, it must be enclosed in quotes. The command line can also include arguments. Here are some examples:

"C:\Program Files (x86)\Windows Kits\8.0\Debuggers\x64\WinDbg.exe"

"\"C:\Program Files\Debugging Tools for Windows (x64)\WinDbg.exe\" -server npipe:pipe=test"

/query [Package]
Displays the running state for an installed package. If Package is not specified, this command displays the running states for all installed packages.

/enableDebug Package [DebuggerCommandLine]
Increments the debug reference count for a package. The package is exempt from PLM policy if it has a non-zero debug reference count. Each call to /enableDebug must be paired with a call to /disableDebug. If you specify DebuggerCommandLine, the debugger will attach when any app from the package is launched.

/terminate Package
Terminates a package.

/forceTerminate Package
Forces termination of a package.

/cleanTerminate Package
Suspends and then terminates a package.

/suspend Package
Suspends a package.

/resume Package
Resumes a package.

/disableDebug Package
Decrements the debug reference count for a package.

/enumerateBgTasks Package
Enumerate background task ids for a package.

/activateBgTask "{TaskId}"
Activates a background task. Note that not all background tasks can be activated using PLMDebug. The TaskID must be wrapped in braces and quotation marks. For example:

plmdebug.exe /activatebgtask "{29421c11-1e1a-47a4-9121-949ce9e25456}"

Remarks

You must call plmdebug /enableDebug before you call any of the suspend, resume, or terminate functions.

The PLMDebug tool calls the methods of the IPackageDebugSettings interface. This interface enables you to take manual control of the process lifecycle management for your apps. Through this interface (and as a result, through this tool), you can suspend, resume, and terminate your Windows app. Note that the methods of the IPackageDebugSettings interface apply to an entire package. Suspend, resume, and terminate affect all currently running apps in the package.

Examples

Example 1

Attach a debugger when your app is launched

Suppose you have an app named MyApp that is in a package named MyApp_1.0.0.0_x64__tnq5r49etfg3c. 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.

plmdebug /query

Package full name: 1daa103b-74e1-426d-8193-b6bc7ed66fed_1.0.0.0_x86__tnq5r49etfg3c
Package state: Terminated

Package full name: 41fb5f27-7b60-4f5e-8459-803673131dd9_1.0.0.0_x86__tnq5r49etfg3c
Package state: Suspended
...
Package full name: MyApp_1.0.0.0_x64__tnq5r49etfg3c
Package state: Terminated
...

Increment the debug reference count for your package, and specify that you want WinDbg to attach when your app is launched.

plmdebug /enableDebug MyApp_1.0.0.0_x64__tnq5r49etfg3c "C:\Program Files (x86)\Windows Kits\8.0\Debuggers\x64\WinDbg.exe"

When you launch your app, WinDbg will attach and break in.

When you have finished debugging, detach the debugger. Then decrement the debug reference count for your package.

plmdebug /disableDebug MyApp_1.0.0.0_x64__tnq5r49etfg3c

Example 2

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.

plmdebug /enableDebug 4816

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

When you have finished debugging MyApp, detach the debugger. Then decrement the debug reference count for the package.

plmdebug /disableDebug 4816

Example 3

Manually suspend and resume your app

Suppose you want to manually suspend and resume your app. First, increment the debug reference count for the package that contains your app.

plmdebug /enableDebug MyApp_1.0.0.0_x64__tnq5r49etfg3c

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

plmdebug /suspend MyApp_1.0.0.0_x64__tnq5r49etfg3c

When you have finished debugging, resume the package.

plmdebug /resume MyApp_1.0.0.0_x64__tnq5r49etfg3c

Finally, decrement the debug reference count for the package.

plmdebug /disableDebug MyApp_1.0.0.0_x64__tnq5r49etfg3c

Example 4

Manually activate a background task

To manually activate a background task for debugging you can query for the list of background task registered and then activate it through plmdebug.

First query the set of background tasks registered:

plmdebug /enumeratebgtasks MyApp_1.0.0.0_x64__tnq5r49etfg3c

Package full name is MyApp_1.0.0.0_x64__tnq5r49etfg3c.
Background Tasks:
SampleTask : {50DB0363-D722-4E23-A18F-1EF49B226CC3}

If you want to guarantee that the task activates, enable debug mode first. For example, opportunistic tasks like TimeTrigger-activated tasks will not activate while the system is in battery saver. Enabling debug mode on the package will ensure the system ignores the policies that would prevent activation otherwise.

plmdebug /enabledebug MyApp_1.0.0.0_x64__tnq5r49etfg3c

Then activate the desired task using its registration GUID, that you enumerated.

plmdebug /activatebgtask "{50DB0363-D722-4E23-A18F-1EF49B226CC3}"

See also

How to trigger suspend, resume, and background events while debugging UWP apps in Visual Studio

Tools Included in Debugging Tools for Windows