While the Quickstart gives you enough to get going, there are many more features available in Topshelf. The following details the configuration options available, and how to use them in Topshelf services.

Specify the base name of the service, as it is registered in the services control manager. This setting is optional and by default uses the namespace of the Program.cs file (well, basically, the calling assembly type namespace).

HostFactory.New(x=>{x.SetServiceName("MyService");});

It is recommended that service names not contains spaces or other whitespace characters.

Each service on the system must have a unique name. If you need to run multiple instances of the same service,
consider using the InstanceName command-line option when registering the service.

The service can be configured in multiple ways, each with different goals. For services that can handle a dependency on Topshelf, the ServiceControl interface provides a lot of value for implementing the service control methods. Additionally, a zero-dependency solution is also available when lambda methods can be used to call methods in the service class.

To configure a simple service, the easiest configuration method is available.

HostFactory.New(x=>{x.Service<MyService>();});// Service implements the ServiceControl methods directly and has a default constructorclassMyService:ServiceControl{}

If the service does not have a default constructor, the constructor can be specified, allowing the service to be created by the application, such as when a container needs to be used.

HostFactory.New(x=>{x.Service<MyService>(()=>ObjectFactory.GetInstance<MyService>());});// Service implements the ServiceControl methods directly and has a default constructorclassMyService:ServiceControl{publicMyService(SomeDependencydependency){}}

If the service needs access to the HostSettings during construction, they are also available as an overload.

HostFactory.New(x=>{x.Service<MyService>(hostSettings=>newMyService(hostSettings));});// Service implements the ServiceControl methods directly and has a default constructorclassMyService:ServiceControl{publicMyService(HostSettingssettings){}}

To configure a completely custom service, such as one that has no dependencies on Topshelf, the following configuration is available.

HostFactory.New(x=>{x.Service<MyService>(sc=>{sc.ConstructUsing(()=>newMyService());// the start and stop methods for the servicesc.WhenStarted(s=>s.Start());sc.WhenStopped(s=>s.Stop());// optional pause/continue methods if usedsc.WhenPaused(s=>s.Pause());sc.WhenContinued(s=>s.Continue());// optional, when shutdown is supportedsc.WhenShutdown(s=>s.Shutdown());});});

Each of the WhenXxx methods can also take an argument of the HostControl interface, which can be used to request the service be stopped, request additional start/stop time, etc.

There are multiple service start modes, each of which can be specified by the configuration. This option is only used if the service is being installed.

HostFactory.New(x=>{x.StartAutomatically();// Start the service automaticallyx.StartAutomaticallyDelayed();// Automatic (Delayed) -- only available on .NET 4.0 or laterx.StartManually();// Start the service manuallyx.Disabled();// install the service as disabled});

Topshelf also exposes the options needed to configure the service recovery options as well.

HostFactory.New(x=>{x.EnableServiceRecovery(r=>{//you can have up to three of theser.RestartComputer(5,"message");r.RestartService(0);//the last one will act for all subsequent failuresr.RunProgram(7,"ping google.com");//should this be true for crashed or non-zero exitsr.OnCrashOnly();//number of days until the error count resetsr.SetResetPeriod(1);});});

Services can be configured to run as a number of different identities, using the configuration option that is most appropriate.

HostFactory.New(x=>{x.RunAs("username","password");});

Runs the service using the specified username and password. This can also be configured using the command-line.
Please be sure to include the domain or UPN suffix in the username value e.g. domain\username or username@suffix.com.

HostFactory.New(x=>{x.RunAsPrompt();});

When the service is installed, the installer will prompt for the username/password combination used to launch the service.

Service dependencies can be specified such that the service does not start until the dependent services are started. This is managed by the windows services control manager, and not by Topshelf itself.

HostFactory.New(x=>{x.DependsOn("SomeOtherService");});

There are a number of built-in extension methods for well-known services, including:

Provides a callback for exceptions that are thrown while the service is running. This callback is not a handler, and will not affect the default exception handling that Topshelf already provides. It is intended to provide visibility into thrown exceptions for triggering external actions, logging, etc.

HostFactory.New(x=>{x.OnException(ex=>{// Do something with the exception});});

To configure the service recovery options, a configurator is available to specify one or more service recovery actions. The recovery options are only used when installing the service, and are set once the service has been successfully installed.

HostFactory.New(x=>{x.EnableServiceRecovery(rc=>{rc.RestartService(1);// restart the service after 1 minuterc.RestartSystem(1,"System is restarting!");// restart the system after 1 minuterc.RunProgram(1,"notepad.exe");// run a programrc.SetResetPeriod(1);// set the reset interval to one day})});

The recovery actions are executed in the order specified, with the next action being executed after the previous action was run and the service failed again. There is a limit (based on the OS) of how many actions can be executed, and is typically 2-3 actions.