SUMMARY
This step-by-step article describes how to debug a Windows service by using the WinDbg debugger (windbg.exe). To debug a Windows service, you can attach the WinDbg debugger to the process that hosts the service after the service starts, or you can configure the service to start with the WinDbg debugger attached so that you can troubleshoot service-startup-related problems. This article describes both these methods.
Requirements
This article assumes that you are familiar with the following topics:• | Windows Services |
• | WinDbg Debugger |
Attach the WinDbg debugger to a service after the service starts
This method is similar to the method that you can use to attach a debugger to a process and then debug a process.Use the process ID of the process that hosts the service that you want to debug
1. | To determine the process ID (PID) of the process that hosts the service that you want to debug, use one of the following methods.
| ||||||||||||||||||
2. | At a command prompt, change the directory path to reflect the location of the windbg.exe file on your computer. Note If a command prompt is not open, follow steps a and b of Method 1. The windbg.exe file is typically located in the following directory: C:/Program Files/Debugging Tools for Windows. | ||||||||||||||||||
3. | At the command prompt, type windbg –p ProcessID /g to attach the WinDbg debugger to the process that hosts the service that you want to debug. Note ProcessID is a placeholder for the process ID of the process that hosts the service that you want to debug. |
Use the image name of the process that hosts the service that you want to debug
You can use this method only if there is exactly one running instance of the process that hosts the service that you want to run. To do this, follow these steps:1. | Click Start, and then click Run. The Run dialog box appears. |
2. | In the Open box, type cmd , and then click OK to open a command prompt. |
3. | At the command prompt, change the directory path to reflect the location of the windbg.exe file on your computer. Note The windbg.exe file is typically located in the following directory: C:/Program Files/Debugging Tools for Windows. |
4. | At the command prompt, type windbg –pn ImageName /g to attach the WinDbg debugger to the process that hosts the service that you want to debug. Note ImageName is a placeholder for the image name of the process that hosts the service that you want to debug. The "-pn" command-line option specifies that the ImageName command-line argument is the image name of a process. |
Start the WinDbg debugger and attach to the process that hosts the service that you want to debug
1. | Start Windows Explorer. |
2. | Locate the windbg.exe file on your computer. Note The windbg.exe file is typically located in the following directory: C:/Program Files/Debugging Tools for Windows |
3. | Run the windbg.exe file together with the /g command-line switch to start the WinDbg debugger. The /g command-line switch allows the tracked process to continue after the break point is set. |
4. | On the File menu, click Attach to a Process to display the Attach to Process dialog box. |
5. | Click to select the node that corresponds to the process that hosts the service that you want to debug, and then click OK. |
6. | In the dialog box that appears, click Yes to save base workspace information. Notice that you can now debug the disassembled code of your service. |
Configure a service to start with the WinDbg debugger attached
You can use this method to debug services if you want to troubleshoot service-startup-related problems.1. | Configure the "Image File Execution" options. To do this, use one of the following methods:
| ||||||||||||||||||||||||||||||||||||||||
2. | For the debugger window to appear on your desktop, and to interact with the debugger, make your service interactive. If you do not make your service interactive, the debugger will start but you cannot see it and you cannot issue commands. To make your service interactive, use one of the following methods:
| ||||||||||||||||||||||||||||||||||||||||
3. | When a service starts, the service communicates to the Service Control Manager how long the service must have to start (the time-out period for the service). If the Service Control Manager does not receive a "service started" notice from the service within this time-out period, the Service Control Manager terminates the process that hosts the service. This time-out period is typically less than 30 seconds. If you do not adjust this time-out period, the Service Control Manager ends the process and the attached debugger while you are trying to debug. To adjust this time-out period, follow these steps:
| ||||||||||||||||||||||||||||||||||||||||
4. | Start your Windows service. To do this, follow these steps:
|
Troubleshooting
Before you try to debug a service across a network, make sure that the symbols and the source files that the service uses are accessible from the computer where the service will run. To do this, use one of the following methods:• | Grant at least read-access permissions to everyone for the folder on your computer that contains the symbols and the source files that the service uses. |
• | Copy these symbols and source files that the service uses to the computer where the service will run. |