How To Create a C# Windows Service Application

Tweet

Today, I wrote a Windows service application.  Because part of my day job is teaching C# and .NET, I was inspired to write a "how to" document.  The Walkthrough: Creating a Windows Service Application in the Component Designer article found on MSDN is quite helpful, if you know your way around C# and .NET.  Anyone who doesn't understand C# and .NET enough to make short work of the document arguably has no business writing a service; but, we all have to learn sometime.

UPDATED 29 MAY 2012 - Revised several areas for clarity and simplification, and updated formatting.

Things You Should Know About Services

What Is a Service?

Services are applications that continually run behind the scenes. They have no user interface, and don't need a user to be logged in to run. They just run.

Why Use a Service?

All applications programmers encounter situations where something needs continuous monitoring, housekeeping, or something needs to happen automatically, when certain conditions or situations arise.  For example, connecting a device such as a Pocket PC, Zune HD, iPad, Windows Phone, etc., cause their respective applications to automatically launch and begin synchronizing data.

These programs automatically launch, because a service is running in the background that watches for these specific types of devices to be connected.  When the connection is detected, the service launches an application.  Services can be very simple, such as these, or very complex, such as MS SQL Server and Symantec Anti-Virus.

Services Throw No Exceptions*

(*This is a play on physics, not a fact.)
The worst that happens when a desktop or Web application throws an unhandled exception, the user is presented with a cryptic MessageBox or "yellow screen of death", respectively.  When a service throws an unhandled exception, the service stops.  That is bad.

Because services have no user interface, messages and errors are typically written to the system log.  You may choose to get more detailed information about exceptions, by making the scope of your Try blocks more granular.

Timely Startup

When starting a service, the operating system waits for the successful completion of a synchronous call to the service's OnStart event handler.  If the service doesn't report back in a "timely manner" (30 seconds), the operating system assumes it is non-responsive and kills the process.  Therefore, the OnStart and OnContinue handlers must either perform quick operations, or initiate an asynchronous process.  You can use the Threading namespace, a BackgroundWorker object, or the Async/Await keywords (currently available only through a Community Technology Preview (CTP) release).

Debugging is Different

As when writing a library, you can't simply run the application in debug mode.  You'll need to create some unit tests.  If absolutely necessary, you can always load it up with writes to a log file, to see where bugs pop up.  However, the log file approach is cumbersome, requires extra code, and doesn't catch many problems.

How to Create a Service Using C# and Visual Studio

Creating a service is very simple.  Getting that service to install on a machine is the more complicated part.  This section describes the parts of service code.  You can skip down to the installation configuration part, if you wish.

Create a Service Project

This is easy, and is the same process in Visual Studio versions 2005, 2008, and 2010.  This demonstration uses Visual Studio 2010.

1. Launch Visual Studio
2. Create a new project
3. Select Visual C# > Windows > Windows Service
4. Name your project
5. Click the OK button

The project is created, including a Service1.cs class.  You'll notice the tree icon in Solution Explorer is that of a component, and not of a class.  The Service1.cs file is automatically opened in design mode; because, it is a component.  All of the requisite references are in place, too.

Service Properties

The very first thing to do is set the properties of the service. This is done in the service design mode, that should now be displayed.  The most important thing to set is the Name property.  Be sure the service name is descriptive, unique, brief, and not ambiguous.  You may use spaces in the service name -- in fact, please do use spaces!

Other properties are available, including whether the service handles various service events, such as Stop, Pause, Continue, Shutdown, etc.  When set to true, these basically subscribe handler methods in your service to the operating system service events.

Anatomy of Service Code

Press the F7 key, to view Service1.cs in code view.  Note the following features:

• The System.Diagnostics namespace is declared for use, to expose the EventLog class
• The System.ServiceProcess namespace is declared in a using statement
• The Service1 class inherits System.ServiceProcess.ServiceBase
• Override template code for the OnStart event handler is in place
• Override template code for the OnStop event handler is in place

This is all that is required for us to get started on a service!  As you probably guessed, the ServiceProcess namespace contains everything related to creating and managing services.  The OnStart and OnStop handlers are also self-explanatory -- they are called when our service is started or stopped.

Writing Useful Event Logs

Services are incapable of dealing with unhandled exceptions.  A desktop client application displays the exception message in a MessageBox, and Web applications display it in a "yellow screen of death."  Services run unattended, and have no user interface.  They simply stop, when an unhandled exception is encountered.

Therefore, it is necessary to use Try-Catch blocks, and then write the details to the machine's event log.  Let's instantiate an EventLog object, and create a class to write exceptions to the log.  To make our job of logging easier, the System.ServiceProcess.ServiceBase type, which our class inherits, provides an EventLog object for us.  This EventLog instance is configured with the service name, and defaults to the Application log of the local machine.

Classes other than this default service class will likely exist in your service project.  To ensure consistency and efficiency, the service's EventLog may be exposed to other classes via constructor arguments.  This conveniently aligns with constructor dependency injection, used for unit testing.  The service's EventLog instance can not be exposed via static property; because, ServiceBase.EventLog is a property, and properties are attached to instances.  Instantiating the service class, simply to access its EventLog property should be discouraged.

Event ID Management

A critically important attribute of event logs in the event identifier (event ID).  These values must remain consistent, throughout the lifetime of the service.  Never use the same event id for another purpose.  Event IDs may only be deprecated, or, simply not used in newer versions of the application.  So, how do we easily manage these important event ids?

You generally have two options: create global constants, or use an enumerator.  I prefer the enumerator approach; because, it neatly groups all values together, works very well with intellisense, avoids complications associated with ghost const values in referencing modules, and are conveniently typecast to and from Int32.  Unless you have all logic in this single service class, place the enumeration in the namespace, instead of inside the service class, for proper visibility to other classes.

internal enum Service1EventIds
{
    Initialization_GeneralFailure = 100,
    Initialization_WatcherDir_NotExist = 101,
    Initialization_WatcherDir_NoAccess = 102,
    Initialization_WatcherDir_OtherError = 103,
    Start_GeneralFailure = 200,
    Start_InitializationFailure = 201,
    Stop_GeneralFailure = 300
}

The Devil is In the (Lack of) Details

The greatest disservice you may do to system administrators, and, ultimately, to yourself, is to provide little to no detail in event logs.  This is easily remedied, by providing debug information in the entry.

WARNING: Before choosing to write debug information in your event log, be sure to consult your security professional, to determine if doing so poses a security risk.  Don't needlessly expose the inner workings of your service.  Providing a switch for writing debug data may be an option.

1. Created a new, static class file, named EventLogExtensions.cs
2. Create an EventLog extension method, that writes exception details to the log

namespace WindowsService1
{
  public static class EventLogExtensions
  {
    public static void WriteEntry(this EventLog log, 
      string message, 
      EventLogEntryType type, 
      int eventID, 
      Exception ex)
    {
      if (String.IsNullOrWhiteSpace(message))
        throw new ArgumentException("message is null or empty.", "message");
      if (ex == null)
        throw new ArgumentNullException("ex", "ex is null.");
 
      string seperator = new String('-', 50);
      StringBuilder builder = new StringBuilder(message);
 
      // Write each of the inner exception messages.
      Exception parentException = ex;
      bool isInnerException = false;
      do
      {
        builder.AppendLine();
        builder.AppendLine(seperator);
        if (isInnerException)
          builder.Append("INNER ");
        builder.AppendLine("EXCEPTION DETAILS");
        builder.AppendLine();
        builder.Append("EXCEPTION TYPE:\t");
        builder.AppendLine(parentException.GetType().ToString());
        builder.AppendLine();
        builder.Append("EXCEPTION MESSAGE:\t");
        builder.AppendLine(parentException.Message);
        builder.AppendLine();
        builder.AppendLine("STACK TRACE:");
        builder.AppendLine(parentException.StackTrace);
        if (parentException.InnerException != null)
        {
          parentException = parentException.InnerException;
          isInnerException = true;
        }
      }
      while (parentException != null);
 
      log.WriteEntry(builder.ToString(), EventLogEntryType.Error, eventID);
    }
  }
}

Now, we are able to catch exceptions and handle them in an unattended environment, from any class and method.  The following code in an example of how to implement our EventLogManager class:

protected override void OnStart(string[] args)
{      
  try
  {
    throw new Exception("Test parent exception", new Exception("Test inner exception"));  
  }
  catch (Exception ex)
  {
    EventLog.WriteEntry(
      "Service failed to start.",
        EventLogEntryType.Error,
        (int)Service1EventIds.Start_InitializationFailure,
        ex);
  }
}

Set Assembly Values

Take a moment to enter information in the assembly attributes.  This is important; because, this information is visible to the end user.  You want to provide as much information as possible, to tell users what your application does, and to help them locate your files through search interfaces.

If you haven't done this before, it is a habit you must quickly adopt.  In the Solution Explorer window, expand the Properties node of the Windows Service project.  Open the AssemblyInfo.cs file child node.  Here's an example of what I entered in this demo code:

using System.Reflection;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
 
// General Information about an assembly is controlled through the following 
// set of attributes. Change these attribute values to modify the information
// associated with an assembly.
[assembly: AssemblyTitle("Windows Demo Service")]
[assembly: AssemblyDescription("This is a demonstration service.  It doesn't do anything useful, and may be uninstalled.")]
[assembly: AssemblyConfiguration("")]
[assembly: AssemblyCompany("The Curly Brace")]
[assembly: AssemblyProduct("Windows Demo Service")]
[assembly: AssemblyCopyright("OPEN SOURCE - Copyright © The Curly Brace 2010-2012")]
[assembly: AssemblyTrademark("")]
[assembly: AssemblyCulture("")]
 
// Setting ComVisible to false makes the types in this assembly not visible 
// to COM components.  If you need to access a type in this assembly from 
// COM, set the ComVisible attribute to true on that type.
[assembly: ComVisible(false)]
 
// The following GUID is for the ID of the typelib if this project is exposed to COM
[assembly: Guid("46733559-4d11-4804-8409-08747ee49221")]
 
// Version information for an assembly consists of the following four values:
//
//      Major Version
//      Minor Version 
//      Build Number
//      Revision
//
// You can specify all the values or you can default the Build and Revision Numbers 
// by using the '*' as shown below:
// [assembly: AssemblyVersion("1.0.*")]
[assembly: AssemblyVersion("1.0.0.0")]
[assembly: AssemblyFileVersion("1.0.0.0")]

How to Create a Service Installer Using C# and Visual Studio

After adding functional code to the service, and creating unit tests (you are creating your tests, right?), the service is ready for deployment.  However, we can't simply create a setup project, to install a service.  A setup project only install the binary files to the machine, and does nothing to install a service.

Therefore, the burden of installing the service falls on the service project.  The System.Configuration.Install namespace contains objects that expose code to the setup project.  This code is executed when the setup runs.

Please note this process uses Visual Studio 2010, which may vary slightly in versions 2008, 2012 and newer. Let's get going, instead of talking about details, here.

Add a Project Installer

The first step is to create a project installer.  This is the code that registers the service(s) included in this application with the host operating system.  This part is easy, if you know where to look.

1. Open Service1.cs in design mode
2. Make the Properties window visible (press F4)
3. Ensure the ServiceName property is set to a unique name
4. Ensure other properties are correctly set (i.e. CanPauseAndContinue, etc.)
5. Click the Add Installer hyperlink, located near the bottom of the Properties window -- a ProjectInstaller.cs file is created and opened in design mode
6. In the ProjectInstaller design space, rename the serviceInstaller1 object, to include the name of the class.  For example, my example code renames the object to Service1Installer.

If you have multiple service classes in your project, repeat the steps above, for each service class.

Wow, that was easy!  We're already half way done with configuring the ProjectInstaller class.  Let's take a closer look at the ProjectInstaller design area:

• serviceProcessInstaller1 -- This is the service process installer, which acts as an installer for the individual ServiceInstaller objects
• Service1Installer -- This provides details specific to the Service1 service, which are used to create the service on the host machine

Press the F7 key, to view the code-behind.  You'll see that the class is decorated with a RunInstaller attribute.  This tells the compiler that the contents of the class are to be included in setup project code execution.

Also, note the class inherits System.Configuration.Install.Installer, which provides many InstallEventHandler methods, such as BeforeInstall, AfterInstall, BeforeRollback, Committed, etc.

Configure Properties

We're half way done with configuring the project installer.  To finish, we must configure the service installer objects.

• For each ServiceInstaller object in the ProjectInstaller...
  1. Select the ServiceInstaller object
  2. Press F4, if the properties window is not already visible
  3. Enter a description for the Description property
  4. Enter a user-friendly name for the service for the DisplayName property
  5. Change the StartType property, if necessary
  6. Check all other properties, to ensure they are correctly set

The ProjectInstaller now contains all information needed to properly register the services on the host machine.  Now, we're ready to write some actions, to help the setup project install the services.

Create Installation Actions

During installation of the application, we should to perform some custom actions, including:

1. Stop existing service (you may be replacing an older version, or repairing the installation)
2. Create EventLog event source, if it is missing
3. Optionally, start the newly-installed service

Create a new class in the Windows Service project (not in the Setup project), named InstallActions.cs.  Add the following code:

using System;
using System.ComponentModel;
using System.Configuration.Install;
using System.Diagnostics;
using System.ServiceProcess;
 
[RunInstaller(true)]
public class InstallActions : Installer
{
  ServiceController controller;
 
  public InstallActions()
    : base()
  {
    this.AfterInstall += new InstallEventHandler(InstallActions_AfterInstall);
    this.BeforeInstall += new InstallEventHandler(InstallActions_BeforeInstall);
    this.BeforeUninstall += new InstallEventHandler(InstallActions_BeforeUninstall);
  }
 
  void InstallActions_BeforeInstall(object sender, InstallEventArgs e)
  {
    // Before installation, stop existing service.
    SetServiceStatus(false);
 
    // Before installation, create EventLog source, if it is missing.
    if (!EventLog.SourceExists("DemoService1"))
    {
      EventLogInstaller eventLogInstaller = new EventLogInstaller() 
      { Source = "DemoService1" };
      Installers.Add(eventLogInstaller);
    }
  }
 
  void InstallActions_AfterInstall(object sender, InstallEventArgs e)
  {
    // Automatically starting the service after installation is optional.
    SetServiceStatus(true);
  }
 
  void InstallActions_BeforeUninstall(object sender, InstallEventArgs e)
  {
    // Before uninstalling, stop existing service.
    SetServiceStatus(false);
  }
 
  //Starts and stops the specified service.
  void SetServiceStatus(bool startService)
  {
    ServiceControllerStatus setStatus = 
      startService ? ServiceControllerStatus.Running : ServiceControllerStatus.Stopped;
 
    try
    {
      controller = new ServiceController("Service1");
      if (controller != null && controller.Status != setStatus)
      {
        if (startService)
          controller.Start();
        else
          controller.Stop();
        controller.WaitForStatus(setStatus, new TimeSpan(0, 0, 30));
      }
    }
    catch {
      // TODO
    }
  }
}

Let's examine parts of this code, to understand what is going on.

• Note the class is decorated with the [RunInstaller(true)] attribute, and inherits System.Configuration.Install.Installer.  This is necessary, because we want this code to be included as part of an installation process.  This also exposes installation process events, such as BeforeInstall, AfterInstall, Committed, etc.
   
• public InstallActions() : base() This is the class constructor.  It is important to call the base class, which is done by adding " : base()" after the constructor name.  The constructor subscribes handler methods to some installation events.
   
• void SetServiceStatus(bool startService) I created this method, to easily start and stop services.  It can easily be modified to accept a service name as an input parameter, or simply iterate through several service names in a collection.
   
• void InstallActions_BeforeInstall This method is called before installation begins.  This is where we ensure all services defined in the ProjectInstaller class are stopped before proceeding with installation.  If a service is still running, the installation will fail, on account of the service assembly being in use, and unable to be replaced with the new file.
   

• void InstallActions_AfterInstall

  This is called after installation.  That is, after files are copied, registry keys are modified, etc., but before the installation is committed.  This is when we want to create the event log source(s), using an EventLogInstaller object.  We do this after installation, to ensure files and registry keys are successfully created -- we don't want to create event log sources that may not be used.
   

• void InstallActions_Committed

  This is called after all installations, including the EventLogInstaller, are successful and complete.  The installation is finished, and no more installations may take place.  This is when we want to start the newly installed services.
   

• void InstallActions_BeforeUninstall

  As with installing a service, we want to ensure the service is stopped before uninstalling its assembly, otherwise the file system locks the file, and the uninstall fails.

We now have code that executes when the setup project runs.  All we need to do now is to create a setup project, and tell it this assembly contains classes decorated with RunInstaller.

Create a Setup Project

I'm no deployment expert, so I'm not picky about my setup and deployment project types.  I don't mind using the good old Visual Studio Installer Setup Project.

1. Right-click the solution node (topmost node), in the Solution Explorer window -- the context menu appears
2. In the context menu, select Add > New Project -- the Add New Project dialog appears
3. Select project type (this is the Visual Studio 2010 hierarchy): Other Project Types > Setup and Deployment > Visual Studio Installer
4. In the center window pane, select Setup Project
5. Name the setup project
6. Click the OK button -- the Add New Project dialog closes and the setup project's File System view opens.

Setup projects behave differently than other file types in the Solution Explorer.  A setup project consists of a single .vdproj file.  You can't open a setup project, like you can open other files.  Instead, differnt views of the project data are made available.  If you are unfamiliar with Setup projects, I recommend taking some time to learn about them.

Setup Project Configuration

1. Add the Service Project output to the application folder -- this identifies the files that are to be copied to the host file system
1. If the File System view is not already visible...
1. Right-click the setup project in the Solution Explorer window -- the context menu appears
2. In the context menu, select View > File System -- the File System view appears
2. In the left window pane, select the Application Folder tree node -- the right window pane displays an empty list of files
3. Right click in the empty space of the right window pane -- the context menu appears
4. In the context menu, select Add > Project Output... -- the Add Project Output Group dialog appears
5. In the dialog, select the WindowsService1 project, in the Project drop-down box, near the top of the window
6. Select the Primary Output option, in the list box, below the Project drop-down box
7. Select (Active) in the Configuration drop-down box (this tells the setup project to use the compiled files from the active configuration (debug, release, etc.))
8. Click the OK button -- the dialog window closes, and an item appears in the right window pane of the File System view

2. Add custom actions
1. Right-click the setup project in the Solution Explorer window -- the context menu appears
2. In the context menu, select View > Custom Actions -- the Custom Actions view appears, containing four items in the tree node:
• Install
• Commit
• Rollback
• Uninstall
3. Add custom actions to the Install action

1. Right click the Install tree node, in the Custom Actions view -- the context menu appears
2. In the context menu, select Add Custom Action... -- the Select Item in Project dialog appears
3. Double-click the Application Folder item in the list box -- the contents of the File System view Application Folder appears in the list box
4. Select the Primary output from WindowsService1 (Active) item in the list box (this tells the setup project to look for classes in the output assemblies, decorated with the [RunInstall()] attribute)
5. Click the OK button -- the dialog closes, and a child node named Primary output from WindowsService1 (Active) appears below the Install node in the Custom Actions view tree
4. Add custom actions to the Commit action by repeating step 3, but using the Commit tree node instead of the Install node
5. Add custom actions to the Uninstall action by repeating step 3, but using the Uninstall tree node instead of the Install node

3. Configure the setup project properties -- many of these properties appear in the Programs and Features or Add and Remove Programs control panel, providing information about the program to the user (this is important stuff!)
   TIP: If you are not sure what the property does, just look at the description pane at the bottom of the properties window (you may need to resize the information pane with the mouse, to make it visible).

1. Select the setup project in the Solution Explorer window
2. If the Properties window is not already visible, press the F4 key -- the Properties window appears
3. Enter information in relevant properties --  I recommend setting values for the following for this demo (you want to set as many as possible for real, production releases!):
• Author
• Description
• Keywords -- these are used by search utilities, to help users locate your application
• Manufacturer
• ProductName
• RemovePreviousVersions -- you want to do this for most services
• TargetPlatform
• Title -- this is what appears in the title area of the setup wizard

The setup project is now configured, and we are ready for deployment!

Test the Setup Project

Ok, let's compile, fire it up, and see what happens!

1. I suggest selecting the Release configuration
2. Click menu items: Build > Rebuild Solution -- all projects in the solution are rebuilt; however, this does not cause the setup project to be compiled!
3. Right-click the setup project node, in the Solution Explorer window -- the context menu appears
4. In the context menu, select Rebuild -- the setup project is compiled

Use a Virtual Machine for Testing

The setup project is ready to be executed.  If you want to execute the setup project on your development workstation (not recommended), simply right-click the setup project in the Solution Explorer window, and then select Install in the context menu.

I recommend testing installers on a virtual machine that has virtual the disk image rollback feature enabled.  This feature allows you to choose to commit or roll back changes made to the virtual hard drive, since booting the virtual machine.  Some virtual machine environments, such as VM Ware, allow you to roll back changes without shutting down the virtual machine, by simply rebooting the virtual machine.

I'm going to use Microsoft Virtual PC; because, it's free and easy to use.  Before booting the virtual machine, I enabled the Undo Disks feature, so I can revert back to the machine's previous state.

Notice the service setup wizard displays information from the setup project properties.

To demonstrate that the service is running, I left the exception throwing code in the OnStart event handler of Service1, to write an entry to the system event log.  After installation, I launched the Event Viewer and found the following events:

Event Type:     Information
Event Source:   MsiInstaller
Event Category: None
Event ID:       11707
Date:           12/22/2010
Time:           3:52:44 PM
User:           VIRTUALXP-36130\XPMUser
Computer:       VIRTUALXP-36130
Description:
Product: Curly Brace Demo Services -- Installation completed successfully.
[ SNIP ]


Event Type:     Information
Event Source:   Service1
Event Category: None
Event ID:       1234
Date:           12/22/2010
Time:           3:57:52 PM
User:           XPMUser
Computer:       VIRTUALXP-36130
Description:
Service failed to initialize.

--------------------------------------------------
EXCEPTION DETAILS

EXCEPTION TYPE: System.Exception

EXCEPTION MESSAGE:  Test parent exception

STACK TRACE:
(Removed for blog formatting)
--------------------------------------------------
INNER EXCEPTION DETAILS

EXCEPTION TYPE: System.Exception

EXCEPTION MESSAGE:  Test inner exception

STACK TRACE:
(Removed for blog formatting)

The Add or Remove Programs control panel displays the service application details:

The service also appears in the Services control panel, just like any other service: