Building Windows Services using Topshelf

Hello again 🙂
Visibly this is going to be my first technical post here. I hope you’ll find it useful.

Windows Services

Recently I came up with a need to create an application, which executes some tasks in the background based on file system’s events. “That’s easy”, one would say. “Build Windows Service app”, he would add. Sure, that was also my first idea.

I think that’s very common that we want to create an application without any GUI, which purpose is just to do something in the background. Moreover we’d like it to be independent from the user running it – we want it to be running all the time, without having to manually launch it – especially when the application is running on customer’s environment, where we can’t be logged in all the time running the application.

Here comes the service – long-running executable with no user interface, which runs in its own Windows session. Such application can be:

  • executed by any user created in the system (e.g. with specific security policies assigned),
  • started automatically when the system launches,
  • automatically restarted in case of errors,
  • at any time started, paused, stopped or restarted.

Even if you’ve never developed any service applications, you are using many of them – check your services.msc to see the list of services currently running in your system.


Visual Studio 2015 provides a template to create Windows Service application and probably I could finish my post here. However, I would like to share with you an even easier way of building services: to do it with Topshelf – a very lightweight open-source library, which purpose it to make services development, debugging and deployment painless. Topshelf allows the developer to focus on service’s functionality, instead of wasting time interacting with .NET Framework’s build-in services support. There is also no more need to install your service using InstallUtil or learn how to attach your Visual Studio debugger to running service to detect issues.

Using Topshelf it’s enough to create console application, add one service class with public Start and Stop methods, configure service’s startup parameters (its name, display name, description etc.) and you’re ready to go. Below we’ll see how to do it.

Creating Windows Service application

After creating console application in Visual Studio, add Topshelf to the project by installing it from Nuget:

Topshelf - Nuget

Adding service class

Then, create service class, which is responsible for executing your service’s logic:

class FileWatcherService
   public bool Start()
      // Initialize your service application here
      return true;

   public bool Stop()
      // Executed when the service is stopped
      // Dispose your objects here etc.
      return true;

Both of those methods return boolean to indicate that starting/stopping of the service completed successfully.

Adding service configuration

Now we only need to configure the service’s parameters. Topshelf provides HostFactory class which contains Run method, to which we can pass fluently-created set of settings:

  • service class instance,
  • methods to be executed while the service is started/stopped/paused/continued,
  • service’s name, display name, description,
  • start/stop timeouts,
  • startup type (automatic, manual, automatic delayed),
  • and many more.

The set-up code should be put in the Main method of Program.cs. In our case, the simplest configuration could look as follows:

static void Main(string[] args)
    HostFactory.Run(serviceConfig =>
        serviceConfig.Service<FileWatcherService>(serviceInstance =>
            serviceInstance.ConstructUsing(() => new FileWatcherService());
            serviceInstance.WhenStarted(execute => execute.Start());
            serviceInstance.WhenStopped(execute => execute.Stop());

        serviceConfig.SetDisplayName("File Watcher Service");
        serviceConfig.SetDescription("Service monitoring local folders for file system events");


Debugging the service

Ease of implementation and configuration of the service application isn’t the only benefit of using Topshelf. Our application has been created as a console app, so it can be simply run and debugged by using F5 button. No more need to attach debugger to the service itself 🙂

Installing the service

Topshelf also adds some “shell layer” to our application. To install executable file (which is the output of our console application) into Windows Service Control Manager (SCM) to be running as a “real” Windows Service, it’s enough to open the command line, navigate to the folder where the .exe file is present and install it passing install as .exe’s parameter (e.g.: FileWatcherService.exe install). After executing it, we can see our service created by looking into services.msc:

Installed service

It’s similarly easy to uninstall the service.

Not only Windows

The official Topshelf’s project’s page says:

Topshelf works with Mono, making it possible to deploy services to Linux. The service installation features are currently Windows only, but others are working on creating native host environment support so that installation and management features are available as well.

So it’s the next great benefit of Topshelf to use applications built with it on Linux.


If you want to check what’s more that Topshelf can do, you can visit project’s official page, check it’s GitHub repository or watch this very good Pluralsight course.


Summing up, I found Topshelf very handy in developing service applications. One of the major pros of using it is ease of installation – it may become very important in the production environment, especially when dealing with any kind of distributed environment. Moreover, debugging the service as a console application makes fixing bugs quick and comfortable. I recommend everyone to use it in case of a need to write any service application.

.NET full stack web developer & digital nomad
0 0 votes
Article Rating
Notify of
Inline Feedbacks
View all comments