Debugging the OnStart method of a Windows Service
Who said that it was too difficult to debug the OnStart method of a Windows
service? Too many do. Some developers write messages to the event log. Others
copy code from the OnStart method to a console application. Some do
not even attempt to debug the method. There is a very simple mechanism to
debug OnStart if you understand the Windows service architecture.
Windows Service Architecture
Every Windows service must be executed within a process, also known as an
executable. A single process may "theoretically" execute many Windows services.
If the process fails, all services will fail. A pictorial view of the
architecture may be found online.
Here are the basic points to remember:
-
All Windows services must execute within a process.
-
The process must be started before a debugger can be attached to it.
-
The process starts when the first service is started.
-
The process ends when the last service is stopped.
Windows Service Installation
Installation of services takes place in two stages. The first stage involves
installing the process in which the services will run. During this stage, the
process is configured to run under a specific account. This account may be a
user account, local system account, or a service account. The
ServiceProcessInstaller is the class that takes care of this task.
The second stage involves installing the individual services in the Services
Control Manager. During this stage, a service's display name, service name,
description, and dependencies are configured. A service's display name is
the user-friendly name that is accepted by tools such as the Visual Studio .NET
Server Explorer and the Windows 2000 Services MMC snap-in. The service name is
the short-hand name for the service. The description is self-explanatory and
dependencies are other services that the service expects to be started before
it can be started.
Warning: The ServiceName
property of your ServiceBase derived class must match the ServiceName
property of the associated ServiceInstaller class.
Debugging ServiceBase.OnStart
First of all, to debug a service requires attaching to the process in which the
service runs. The problem with debugging the OnStart method of the
ServiceBase derived class is that this method is typically called as soon as
the service is started. There would be no way to start the service (to start
the process), attach a debugger to the process, and then receive a breakpoint
hit at the OnStart method in so little time. However, this is only true if only
one service resides in the process, which is almost always the
case since most developers will use the New Service Project Wizard's
defaults. The easiest thing to do is to add another service to your
project that will serve as a debugger helper service. The debugger helper
service should never require debugging its own OnStart method. After
configuring the services and installers, you are ready to install and debug the
services.
Note: To install or uninstall
services (and their process), you must use the installutil.exe utility that is
found in the .NET Framework installation folder:
\ Winnt \ Microsoft.NET \ Framework \ [version] \
i.e. InstallUtil -i WindowsService.exe
After successfully installing your services and your service process, debugging
the OnStart method of your main service then requires 4 steps:
-
Start the debugger helper service.
-
Set a break point in the OnStart method of the main service.
-
Attach the debugger to the process that runs the services. (Note: Make sure
that "Show System Processes is checked if the service runs under the local
system account."
-
Start the main service. Your OnStart method should now receive a break point
hit.
Download the following service project to test
this for yourself:
Maybe the next version of the .NET Framework SDK will contain a Debuggable
Service Project Template. We know ours will !
Back to Tips and Tricks