|
Version: 1.0.2
Updated: 01.08.2006
Introduction
How to use StartDbg to debug a service
How to use StartDbg to debug out-of-process COM servers
Log file
How StartDbg works
Supported operating systems
Limitations
Download
Reporting bugs
StartDbg is a small tool that simplifies debugging of the startup code of services and COM server applications,
even if they are running under non-administrative user accounts. In brief, it suspends
the service or the COM server process for a predefined period of time, and allows us to attach debugger
to the process while it is suspended. For additional information about the motivation behind creating this tool,
take a look at this article.
Here are the steps necessary to debug a service with the help of StartDbg:
1. Consider modifying the default startup timeout for services in the system.
Here you can find detailed information about it.
2. Ensure that the service is built and properly registered.
3. Insert the full path to StartDbg into ImagePath setting of the service.
The path to the executable file that should be used to start the service is stored in the following
Registry entry:
HKLM\SYSTEM\CurrentControlSet\Services\<ServiceName>
ImagePath = REG_SZ
For example:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MyService
ImagePath = "c:\myapps\myservice.exe"
This entry should be modified to contain the full path to StartDbg executable (startdbg.exe) at the beginning.
For example:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MyService
ImagePath = "c:\startdbg\startdbg.exe c:\myapps\myservice.exe"
4. Specify the timeout during which the service should be kept suspended by StartDbg.
In startdbg.ini file (in the same directory with startdbg.exe) specify WaitAttach setting (in seconds).
[Settings]
WaitAttach=120
For example, if you set WaitAttach to 120, you will have 120 seconds since the service's startup to attach
the debugger, set breakpoints and let the service continue.
5. Start the service.
The recommended way to start the service is to use "net start MyService" command (Service applet is not
recommended because it introduces additional and often unwanted timeouts during the service startup).
After you have started the service, it will be suspended by StartDbg for the number of seconds specified
in startdbg.ini file (WaitAttach setting).
6. Attach debugger to the service.
Now you can attach debugger to the service process and set breakpoints. For your convenience, StartDbg will
print the process id of the service process to the debug output, which you can capture with a tool like
DebugView. You can use this process id
to identify the process your service is running in, if necessary.
When StartDbg resumes the service after the timeout has elapsed, it prints a notification message to
the debug output. If you have previously attached debugger to the service and set breakpoints, they
should be hit soon.
Note that you do not have to attach debugger to the service process to let it continue. If you do not want
to attach debugger to the service, StartDbg will still automatically resume the service process after
the timeout specified in startdbg.ini has elapsed. The service will continue running normally.
The steps required to debug a COM server are the same as when debugging a service,
with the following differences.
In step 3, instead of ImagePath setting, use the Registry entry that specifies the path
to the COM server executable:
HKEY_CLASSES_ROOT\CLSID\{YourCLSID}\LocalServer32
(Default) = REG_SZ
In step 5, use the client application to start the COM server.
For troubleshooting purposes, StartDbg prints detailed log of its actions into the file specified in startdbg.ini:
[Settings]
LogFile=c:\startdbg\startdbg.log
Make sure that the user account your service is running under has enough privileges to write to this file.
This article contains the list of actions performed by StartDbg
in order to start, suspend and then resume the service or the COM server process.
You can also download and explore StartDbg sources.
StartDbg works on Windows NT 4.0, Windows 2000, Windows XP and Windows Server 2003.
StartDbg does not allow to debug the code executed by entry points of DLLs implicitly linked with the service
or COM server executable. If you need to debug their entry points, consider using
NTSD/WinDbg remote debugging approach.
Download StartDbg (35 Kb)
Download source code (13 Kb)
Contact the developer to report a bug in StartDbg.
|
