Service Name

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.

Service Description

Specify the description of the service in the services control manager. This is optional and defaults to the service name.

HostFactory.New(x =>
{
    x.SetDescription("My First Topshelf Service");
});

Display Name

Specify the display name of the service in the services control manager. This is optional and defaults to the service name.

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

Instance Name

Specify the instance name of the service, which is combined with the base service name and separated by a $. This is optional, and is only added if specified.

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

This option is typically set using the command-line argument, but it allowed here for completeness.

Simple Service

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 constructor
class MyService : 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 constructor
class MyService : ServiceControl
{
    public MyService(SomeDependency dependency)
    {}
}

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

HostFactory.New(x =>
{
    x.Service<MyService>(hostSettings => new MyService(hostSettings));
});

// Service implements the ServiceControl methods directly and has a default constructor
class MyService : ServiceControl
{
    public MyService(HostSettings settings)
    {}
}

Custom Service

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(() => new MyService());

        // the start and stop methods for the service
        sc.WhenStarted(s => s.Start());
        sc.WhenStopped(s => s.Stop());

        // optional pause/continue methods if used
        sc.WhenPaused(s => s.Pause());
        sc.WhenContinued(s => s.Continue());

        // optional, when shutdown is supported
        sc.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.

HostFactory.New(x =>
{
    x.Service<MyService>(sc =>
    {
        sc.WhenStarted((s, hostControl) => s.Start(hostControl));
    }
}

The HostControl interface can be retained and used as the service is running to Stop the service.

Before Install Actions

Topshelf allows actions to be specified that are executed before the service is installed. Note that this action is only executed if the service is being installed.

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

After Install Actions

Topshelf allows actions to be specified that are executed after the service is installed. Note that this action is only executed if the service is being installed.

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

Before Uninstall Actions

Topshelf allows actions to be specified that are executed before the service is uninstalled. Note that this action is only executed if the service is being uninstalled.

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

After Uninstall Actions

Topshelf allows actions to be specified that are executed after the service is uninstalled. Note that this action is only executed if the service is being uninstalled.

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

EnablePauseAndContinue

Specifies that the service supports pause and continue, allowing the services control manager to pass pause and continue commands to the service.

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

EnableShutdown

Specifies that the service supports the shutdown service command, allowing the services control manager to quickly shutdown the service.

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