Building and Debugging Windows Services with Topshelf

Windows Services made simple with Topshelf

What is Topshelf?

Topshelf is an open source Windows Service framework for the .NET platform that simplifies the way you develop, install and debug your Windows Services.

Debugging Windows Services isn’t easy to setup, and most likely, you will be implementing an ad-hoc solution for debugging them.

Ideally, what I want is to load up the project, hit F5 and I have the service running that I’m able to debug.

Windows Service running as a console application in debug

… and that is when Topshelf comes in.


  • Visual Studio
  • .NET Framework
  • Knowledge of C#

We will start off with the AwesomeService code base found here.

AwesomeService.Core is where you will have all of your IOC and the entry point of the application. The AppRunner.cs has two function, start, for construction and stop, for destruction of the application.

The AwesomeService.WindowsService project is just an ordinary console application that starts the app runner and blocks until the app runner stops (at the moment it will not stop until you kill the window).

Lets add the Topshelf nuget package from the package explorer to the AwesomeService.WindowsService project.

or you can run the following through package manager console

Install-Package Topshelf

Now lets change our Program.cs file

Hit F5, and there you have it, our windows application running as a console app (you may need to add the application settings, see config below).

The HostFactory.Run is how we start up our windows service configuration.

We first define what the service entry point is; which in our case is the AppRunner class. We then define what code we run when the service starts (our start() function) and what code to execute when the application stops (our stop() function).

Then we set the service information (line 14–16), we load from the App.config

Installing the windows service

We have our windows service running as a console application in debug mode. But how do we install it as a windows service?

Open a command prompt at AwesomeService\AwesomeService.WindowsService\bin\Debug

Note: You must open your command prompt as Administrator

We can now execute the following

AwesomeService.WindowsService.exe install

and that’s all! Now go and start Windows Services and see your application installed there

If you would like your service to start automatically, you can set the following configuration within Program.cs


For a full list of configuration options, checkout the official documentation.

To uninstall the service, you follow similar instructions to how you have installed it but run the following command.

AwesomeService.WindowsService.exe uninstall

Voila! The service is no longer installed.

What if I wanted to start the service as a different user?

You can run the following command

AwesomeService.WindowsService.exe install -username [your_user] -password [your_password]

This comes really handy especially if you have different environments and you want to run the service logged in as a specific user.

It is also great with automated deployment as you can create a service installation task which executes these commands whilst getting the variables from your Automated Release pipeline.

Checkout the full source here.