Categories
BLOG

topshelf auto

Topshelf Command-Line Reference¶

Once a service has been created using Topshelf, an extensive command-line vocabulary is available which can be used to install, uninstall, start, and configure the service.

The command-line help can be displayed at any time by entering myService.exe help on the command-line.

Help Text¶

The help text from the command line is shown below for easy reference.

service.exe [verb] [-option:value] [-switch]

run Runs the service from the command line (default)

help or –help Displays help

install Installs the service

-u sername The username to run the service
-p assword The password for the specified username
-i nstance An instance name if registering the service multiple times
–autostart The service should start automatically (default)
–disabled The service should be set to disabled
–manual The service should be started manually
–delayed The service should start automatically (delayed)
–localsystem Run the service with the local system account
–localservice Run the service with the local service account
–networkservice
Run the service with the network service permission
–interactive The service will prompt the user at installation for the service credentials
–sudo Prompts for UAC if running on Vista/W7/2008
-s ervicename The name that the service should use when installing
-d escription The service description the service should use when installing. Eg: -description: MyService Eg: -description “My Service”
-d isplayname The display name the the service should use when installing Eg: -displayname: MyService Eg: -displayname “My Service”

start Starts the service if it is not already running

-i nstance The instance to start

stop Stops the service if it is running

-i nstance The instance to stop

uninstall Uninstalls the service

-i nstance An instance name if registering the service multiple times
–sudo Prompts for UAC if running on Vista/W7/2008

Examples¶

Basic Service Installation

Service Installation with Quoted Arguments

© Copyright 2011, Chris Patterson, Travis Smith, and Dru Sellers Revision e92bff10 .

Topshelf Command-Line Reference¶ Once a service has been created using Topshelf, an extensive command-line vocabulary is available which can be used to install, uninstall, start, and configure

Topshelf Configuration¶

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.

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).

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.

Display Name¶

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

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.

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

Service Configuration¶

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.

Simple Service¶

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

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.

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

Custom Service¶

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

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.

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

Service Start Modes¶

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.

Service Recovery¶

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

Service Identity¶

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

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 [email protected].

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

Runs the service using the NETWORK_SERVICE built-in account.

Runs the service using the local system account.

Runs the service using the local service account.

Custom Install Actions¶

These actions allow user-specified code to be executed during the service install/uninstall process. Each install action takes a settings parameter of type Topshelf.HostSettings, providing you with an API to service-related properties such as the InstanceName, ServiceName, etc.

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.

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.

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.

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.

Service Dependencies¶

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.

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

Advanced Settings¶

EnablePauseAndContinue¶

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

EnableShutdown¶

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

OnException¶

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.

Service Recovery¶

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.

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.

© Copyright 2011, Chris Patterson, Travis Smith, and Dru Sellers Revision e92bff10 .

Topshelf Configuration¶ 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