Introduction

Topshelf wraps the Windows Service plumbing so a normal .NET executable can be installed and run as a service with a few commands. The usual workflow is to configure the host in code, build the executable, and then run that executable with commands such as install, start, and uninstall from an elevated command prompt.

Configure the service host in code

A minimal Topshelf application looks like this:

1using Topshelf;
2
3HostFactory.Run(config =>
4{
5    config.Service<Worker>(s =>
6    {
7        s.ConstructUsing(() => new Worker());
8        s.WhenStarted(w => w.Start());
9        s.WhenStopped(w => w.Stop());
10    });
11
12    config.RunAsLocalSystem();
13    config.SetServiceName("SampleWorker");
14    config.SetDisplayName("Sample Worker Service");
15    config.SetDescription("Processes background jobs.");
16});

And the worker can be a simple class:

1public class Worker
2{
3    public void Start() { }
4    public void Stop() { }
5}

Topshelf takes care of bridging this lifecycle to the Windows Service runtime.

Install the service from the executable

After building the project, open an elevated command prompt in the output directory and run:

SampleWorker.exe install

That registers the executable as a Windows service using the configuration you set in code. Administrative privileges are usually required because service installation modifies system state.

If the install succeeds, you can start the service with:

SampleWorker.exe start

Or through the Windows Services management console.

Common service-management commands

Topshelf supports a small set of service-oriented commands from the same executable:

1SampleWorker.exe install
2SampleWorker.exe start
3SampleWorker.exe stop
4SampleWorker.exe uninstall

This makes deployment and cleanup much simpler than hand-writing service registration logic.

Choose the right account

The example above uses RunAsLocalSystem(), which is convenient but often broader than necessary. In production, choose the least-privileged account that still allows the service to do its work.

Topshelf also supports options such as running under a specified account. Account choice affects:

• file-system access
• network access
• database credentials
• interaction with other Windows resources

Service installation is not just about "make it run." It is also about running it with the right permissions.

Test as a console app first

One reason Topshelf is popular is that the same executable can usually be run interactively for debugging. Before installing it as a service, test the process in console mode so startup failures are easier to see.

This is especially helpful for:

• logging configuration issues
• missing app settings
• dependency injection startup failures
• file path assumptions that differ under service execution

If the program does not run cleanly as a console app, it will usually be harder to debug once installed as a service.

Logging matters more for services

A Windows service has no normal UI, so logs become your primary feedback channel. Topshelf does not replace the need for proper structured logging. It just simplifies hosting.

In practice, you will want logs around:

• startup
• shutdown
• recurring work
• error handling

Without logs, a failed service install or a service that stops immediately can be much harder to diagnose.

Common Pitfalls

• Running install without administrative privileges.
• Assuming RunAsLocalSystem() is always the right production account choice.
• Installing the service before testing the executable in console mode.
• Forgetting to add logging and then having no visibility into service startup failures.
• Renaming the executable or moving files after installation without reinstalling the service.

Summary

• A Topshelf executable can be installed as a Windows service with commands such as install and start.
• Service behavior is defined in code through HostFactory.Run.
• Administrative privileges are usually required to install or uninstall the service.
• Test the executable in console mode before relying on service hosting.
• Choose the service account and logging strategy deliberately for production use.