Home > Architecture, dotnet 4, Dotnet 4.5, Service Oriented Architecture > Getting Started with TopShelf

Getting Started with TopShelf

I am a huge fan and follower of open source project and there have been so many great open source projects which tend to solve our complex problem with such an ease. In fact I love the way open source is becoming main stream and even Microsoft has come to the party. However I have notice not every .net developer is across it at least in Canberra.

Today I am going to talk about an underrated open source project called TopShelf which in my opinion deserve a lot of more recognition in the community and decided to blog about it

So TopShelf is a windows service framework which allows to build windows services with out the pain of what .net/visual studio provides. The project is hosted at Github and can be found here.

In fact if you remember in April of this year I blogged “NServiceBus: The Magic of Generic Host” and showed you how NService Bus installs your handler as a windows service, but the real magic behing Generic host is TopShelf and Enterprise Service Bus like NServiceBus and Mass Transit both use TopShelf internally to install handlers as windows service.

Lets get stated and write some code to use TopShelf. Create a new console application and type the following NuGet Command.

PM> Install-Package TopShelf

NuGet will install ‘TopShelf 3.1.0’. Lets create an interface which will encapsulate the windows service start and stop method and TopShelf itself requires a start method and stop method


public interface IService
    void Start();
    void Stop();

For a real life example lets pretend we are writing an Email service which polls database every 10 seconds and based on some domain logic processes and sends the email. I am not going to go into the details of polling and threading etc and this is just a demo code for the Email Service.


public class EmailService : IService
    public void Start()
        Console.WriteLine("Starting Service ...");

    public void Stop()
        Console.WriteLine("Stopping the service ...");

Now in our main program we just have to wireup the TopShelf Host factory.


class Program
    static void Main(string[] args)
        HostFactory.Run(x =>                                 
            x.Service<IService>(s =>                        
                s.ConstructUsing(name => new EmailService());   
                s.WhenStarted(tc => tc.Start());             
                s.WhenStopped(tc => tc.Stop());              

            x.SetDescription("Email Service to send emails 
                              and proudly hosted by TopShelf"); 
            x.SetDisplayName("Email Service to send emails");                       



and that’s it there are no other moving parts or special type of projects or files to include. There are many other useful settings like under which account the windows service should run and on what other services it depends on etc can be easily configured using the fluent apis.The best thing about TopShelf is that as part of your development and debugging you can run it as a normal console application and when you are ready you can just install it as a windows service.

Lets look into installing it as windows service. Launch command prompt as Administrator

and type the following command :-

Topshelf will install the service and will output the following result and which means you have successfully installed your application as a windows service.

Now to verify it open up windows services snap in MMC and you will see your service installed properly with the service name and description. Remember that the display name and description can be anything you want however the windows service name cannot have any spaces as you can see in the above code.

Now you can go ahead and start the windows service. To uninstall it’s again the name of your executable with uninstall option.So for our demo app it will be

TopShelfDemo.exe uninstall

That’s it folks and have a happy coding new year !!!

  1. April 4, 2014 at 3:43 pm

    I was trying to find out how to install this as a service but couldn’t find anything on the official TopShelf docs. Found this post during a net search and it worked for me. Although I’ve created and installed Windows Services before I wasn’t sure exactly the steps to take. Simple in the end. Thank you Prashant.

    • April 27, 2014 at 8:34 am

      Thanks Thomas I am glad my post helped you and I hope to continue writing interesting and useful stuff.

  1. November 29, 2013 at 7:21 am

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: