Bouwen & software

Introduction

Recently I was checking out an open source project called Topshelf (RC2).  It’s a small framework that allows you to easily create stable windows services.

The steps below will guide you into creating your own first Topshelf service.

Writing our service code

One of the great thing about Topshelf is that you don’t need to create a windows service application but a console application. Why this is great, you will notice when we execute the code for the first time.

• Start your VisualStudio an create a new console application
• Download the Topshelf library
• Reference all the downloaded files in your console app
• Create a new class named MyTopshelfService, containing the code below

using System;
using System.IO;
using System.Timers;
using log4net;
using log4net.Config;

namespace MyTopshelfTest
{
	public class MyTopshelfService
	{
		readonly Timer timer;
		private ILog logger;

		public MyTopshelfService()
		{
			XmlConfigurator.Configure(new FileInfo(AppDomain.CurrentDomain.SetupInformation.ConfigurationFile));
			logger = LogManager.GetLogger(typeof(MyTopshelfService));

			timer = new Timer(3000)
			        	{
			        		AutoReset = true
			        	};
			timer.Elapsed += ExecuteCode;
		}

		private void ExecuteCode(object sender, ElapsedEventArgs e)
		{
			logger.Info("Timer elapsed");
		}

		public void Start()
		{
			logger.Info("Service started");
			timer.Start();
		}

		public void Stop()
		{
			logger.Info("Service stopped");
			timer.Stop();
		}
	}
}

Hosting the service in Topshelf

Now that we have a class for Topshelf to host, we can setup Topshelf to actually host our service. To do that we will add configuration code in Program.cs.

using System.IO;
using log4net.Config;
using Topshelf;
using Topshelf.Configuration.Dsl;

namespace MyTopshelfTest
{
	class Program
	{
		static void Main(string[] args)
		{
			// Configure log4net, reading the TopshelfLog4net.config file
			XmlConfigurator.ConfigureAndWatch(new FileInfo(".\\TopshelfLog4net.config"));

			// Creating a configuration for Topshelf
			var cfg = RunnerConfigurator.New(x =>
                 		{
                 			// hooking up our MyTopshelfService class
							x.ConfigureServiceInIsolation<MyTopshelfService>(s =>
                         		{
									s.Named("MyTopshelf");
									// telling Topshelf how to create our service class
                         			s.HowToBuildService(name => new MyTopshelfService());
									// telling Topshelf what method to call to start the service
                         			s.WhenStarted(tc => tc.Start());
									// telling Topshelf what method to call to stop the service
                         			s.WhenStopped(tc => tc.Stop());
                         		});
							// run the service as a local system user
                 			x.RunAsLocalSystem();

							// configure the service not to work unless MSMQ and MSDTC are running (can be seen in services.msc in the tab Dependencies)
							x.DependencyOnMsmq();
							x.DependsOn("MSDTC");

							// set the name and description that will be shown in services.msc
							x.SetDescription("Runs a sample service");
							x.SetDisplayName("My Top shelf service");

							// set the name of your service
							x.SetServiceName("TopShelfService");
                 		});

			Runner.Host(cfg, args);
		}
	}
}

Configuring log4net

We’re almost ready to start our service for the first time. All we need now is config for log4net. For that we will add two config files. An app.config file and a TopshelfLog4net.config file. The app.config looks like this:

<configuration>
	<configSections>
		<section
			name="log4net"
			type="log4net.Config.Log4NetConfigurationSectionHandler, log4net"
			/>
	</configSections>

	<log4net>
		<appender name="FileLogger" type="log4net.Appender.FileAppender">
			<file value="log.txt" />
			<appendToFile value="false" />
			<layout type="log4net.Layout.PatternLayout">
				<conversionPattern value="%message%newline" />
			</layout>
		</appender>
		<appender name="ConsoleLogger" type="log4net.Appender.ConsoleAppender">
			<layout type="log4net.Layout.PatternLayout">
				<conversionPattern value="I say: %message%newline" />
			</layout>
		</appender>

		<root>
			<level value="INFO" />
			<appender-ref ref="ConsoleLogger" />
		</root>

		<logger name="MyTopshelfTest.MyTopshelfService">
			<level value="INFO"/>
			<appender-ref ref="FileLogger"/>
		</logger>
	</log4net>
</configuration>

The TopshelfLog4net.config looks like this (don’t forget to change the properties of this file so that it is copied to your output folder on build):

<log4net>
	<appender name="ConsoleLogger" type="log4net.Appender.ConsoleAppender">
		<layout type="log4net.Layout.PatternLayout">
			<conversionPattern value="Topshelf says: %message%newline" />
		</layout>
	</appender>

	<root>
		<level value="INFO" />
		<appender-ref ref="ConsoleLogger" />
	</root>
</log4net>

Debugging with VisualStudio

In the top of this post I mentioned that the great thing about Topshelf is that you can create a console application. This means you can now debug your application straight from VisualStudio. Simply press F5 and your service will run. The result of running the project is the following output:

Topshelf says: Starting Host
Topshelf says: BeforeStart complete
Topshelf says: Starting subordinate service 'MyTopshelf'
I say: Service started
Topshelf says: BeforeStart complete
Topshelf says: The service is running, press Control+C to exit.
I say: Timer elapsed
I say: Timer elapsed
Topshelf says: Control+C detected, exiting.
Topshelf says: Stopping the service
Topshelf says: Stopping sub service 'MyTopshelf'
I say: Service stopped
Topshelf says: AfterStop complete
^C


Installing the service

Ok so it runs as a console application and you can do that from within VisualStudio. Big deal; every console application can do that. I wanted a service, not a console application.
This is how we install our project as a service.

• Open a command prompt and navigate to the output folder of your project
• Type in:
  
MyTopshelfTest.exe service install

• Run Services.msc
• Notice that our service is installed, the dependencies are set, the name is ok, …

Uninstalling the service

It should be as simple as running this from the cmd prompt:

MyTopshelfTest.exe service uninstall

However that did not do the trick. I found an issue report and patch in the Topshelf project that fixed the problem. Simply download the source. Apply the patch. Build the project and you’re done.

Running multiple instances

Simple:

MyTopshelfTest.exe service install /instance:NewInstanceName

You can now install as many instances of the same service on one server.

What about unhandled exceptions

There is nothing as painful as a service that encounters an unhandled exception and stops running. Topshelf takes care of that for you. To test it, modify the method ExecuteCode in MyTopshelfService to the following:

private void ExecuteCode(object sender, ElapsedEventArgs e)
{
	logger.Info("Timer elapsed");
	throw new Exception();
}

Run your service from the command prompt. Notice that you will get output and that the timer and service keeps on running.

Conclusion

Is Topshelf the greatest tool ever built and will it dramatically change the amount of effort needed to build a windows service? The answer is no.  Would I use and recommend using Topshelf? Absolutely.

Why use Topshelf?

• It is easier to debug then windows services
• It is a lot stabler then some of the services I have seen
• It beats writing this code yourself
• It contains a simple install/uninstall
• It contains a simple install/uninstall for multiple instances
• It’s derived from the service hoster of Mass Transit

Why not to use Topshelf?

• At the time of writing this post it is still a release candidate
• You have to apply a patch and rebuild Topshelf for the uninstaller to work
• A lot of great blog posts have aged information, which leads me to believe the project is still undergoing major changes