WinPE: Debug Apps

Applies To: Windows 8, Windows 8.1, Windows Server 2012, Windows Server 2012 R2

You can use Windows Debuggers, such as Ntsd.exe, Cdb.exe, and Windbg.exe, and supporting tools to debug applications on Windows PE and to debug the Windows PE kernel. Debugging tools are included in the Windows 8 SDK. You must make the debugging tools available on the Windows PE computer by either copying them locally or using them from a share.

To debug Windows PE remotely, you may need to turn off the built-in firewall on the PC:

wpeutil disablefirewall

User-mode debugging

The easiest user-mode debugging method is to run a process server on the Windows PE computer, and connect to it by using a debugger on another computer. The process server is included with the debugging tools in the Windows 8 SDK.

To run a process server in user-mode

1. Copy the Windows Debugging Process Server tool: dbgsrv.exe, from the Windows 8 SDK debugging tools folder (example: C:\Program Files (x86)\Windows Kits\8.0\Debuggers\x64), to the Windows PE computer.

2. At the Windows PE command prompt, disable the firewall.

   wpeutil disablefirewall
   

3. Start the Windows Debugging Process Server, specifying a connection method to the PC, for example, a TCP port:

   dbgsrv.exe –t tcp:port=1234
   

   For more information, see Activating a Process Server (Windows Debuggers).

4. From the remote computer, use the process server to attach to or start processes on the Windows PE destination computer:

   windbg -premote tcp:server=Server, port=1234
   

   For more information, see Activating a Smart Client (Windows Debuggers).

It is also possible to run the debugger directly on the Windows PE computer. However, doing so requires setting up symbol and source paths after every reboot of the Windows PE computer. We recommend that you perform debugging from a computer running a full version of Windows, as described in this procedure.

The following debugging procedure is useful when you want to bypass startnet.cmd or setup.exe, and proceed directly to a command prompt for debugging purposes. This procedure bypasses all initialization, including setup, and runs no commands, such as Wpeinit.exe. This procedure must be performed online on an online operating system.

To enable user-mode debugging prior to any initialization

1. Delete the winpeshl.ini file, if it exists. If the winpeshl.ini file does not exist, then user-mode debugging can be accessed by default.

2. Hold down the Ctrl key during boot before the command prompt is shown. A command prompt appears.

3. Proceed with debugging.

Kernel-mode debugging

To debug in kernel-mode, you must enable kernel-mode debugging before the system is booted. The boot configuration file has a setting for kernel mode debugging, which is enabled by using the bcdedit.exe command-line tool to modify the Boot Configuration Data (BCD) store. Kernel debugging can only be performed by using bcdedit.exe. Bcdedit.exe is located in the \Windows\System32 directory of the Windows partition.

The default debugger settings are as follows:

----------------- 
identifier              {dbgsettings} 
debugtype               Serial 
debugport               1 
baudrate                115200

For creating ISOs for VM environments, enable the kernel with BCD entries before creating the ISO.

For information about how to modify the default BCD store (default.bcd), see How to Modify the BCD Store Using Bcdedit.

To enable kernel-mode debugging

1. Locate the BCD store, which is contained in a file named bcd. This file is located within the boot directory in the root of the media containing the Windows PE image.

2. At the command prompt, type the following bcdedit command to set the debug flag of the BCD store used to boot the image to debug on:

   bcdedit /store <path to winpe>/boot/bcd /set {default} debug on
   

   The {default} might need to be replaced by the unique identifier (UID) of the boot option for Windows PE.

   Alternatively, you can also enable kernel debugging by pressing F8 during boot and selecting the debug option.

For more information about command-line options that control debugging, see BCDEdit Command-Line Options.

See Also

Tasks

WinPE: Mount and Customize

Reference

Wpeutil Command-Line Options
Winpeshl.ini Reference

Other Resources

WinPE for Windows 8: Windows PE 5.0
BCDEdit Command-Line Options