Execution modes and command line arguments

Execution modes

When your service is built with a class derived from ServiceHostBase (such as MicrodotServiceHost<T> or MicrodotOrleansServiceHost), it can run in various modes. These modes are automatically selected based on various cues from the environment. Most of the time, there is no need to change those defaults. Nevertheless, there are a few main scenarios you would want to change the defaults:

• When writing automated tests with advanced scenarios. You might want to set up a cluster of silos to work in primary-secondary configuration, which requires changing the defaults.
• When running a service, you might want to run it in a different mode than its default mode, in a one-off case.
• When running under Linux (Mono), which requires a different mode than the default suitable for Windows.

There are two ways to change the modes:

• Programmatically: Typically use in automated tests. This is done by passing an instance of the ServiceArguments class to the .Run() method (or .RunAsync() extension method) of your service host class. You can specify one or more modes to the constructor of ServiceArguments that takes strongly-typed parameters. For example the following runs a secondary silo on port 7777 (overriding the service's default port of 5555):

  new MySpecialServiceHost().Run(new ServiceArguments(siloClusterMode: SiloClusterMode.SecondaryNode, basePortOverride: 7777))

• Command line arguments: Typically used to run a certain service in a different mode in an ad hoc fashion. You can specify the modes using the following format:

  --OptionName:OptionValue

  That is, two dashes followed by the option name, then a semicolon and then the option value. Any unrecognized command line argument is simply ignored. For example, the following will run MySpecialService with the same arguments as in the previous example:

  MySpecialService.exe --SiloClusterMode:SecondaryNode --BasePortOverride:7777

Smart Defaults

All the arguments have smart defaults, which are selected based on either the environment, the program itself or on the values of other arguments. Because the defaults for one argument depends on the value of another, which may in turn use a default based on a third argument, specifying one arguments can affect many others. Please take care when specifying values, as this may lead to values changing along the "chain". Enum values always have an Unspecified value which means that smart default should be used. Those are not listed below. The equivalent for non-enum values is null when specifying arguments programmatically, or completely omitting the argument when specifying them via the command line.

Full list of parameters currently supported

Name	Type	Description	Valid Values
ServiceStartupMode	Enum	Specifies under which mode to start the service (command line, Windows service, etc)	See description below
ConsoleOutputMode	Enum	Specifies how to output log messages to the console, if at all.	See description below
SiloClusterMode	Enum	Specifies how a silo started in this service should behave in a cluster. Not relevant for non-Orleans services.	See description below
BasePortOverride	Int32	Specifies what base port should be used for the silo. Not relevant for non-Orleans services. This value takes precedence over any base port overrides in configuration.	Any valid port number, from 1 to 65534
InstanceName	String	Logical instance name for the current application, which can be used to differentiate between multiple identical applications running on the same host.	Any non-empty string.

ServiceStartupMode enum values

Name	Description	Is the default value when
CommandLineInteractive	Specifies that the service will run in command-line mode, expecting input from the user.	Standard output is not redirected.
CommandLineNonInteractive	Specifies that the service will run in command-line mode, not requiring any input from the user.	Standard output is redirected.
WindowsService	Specifies that the service will run as a Windows service. Note: This is not suitable for Linux and should therefore a different value should be explicitly set when running under Linux.	Never.

ConsoleOutputMode enum values

Name	Description	Is the default value when
Color	Specifies that log messages should be written to the console with coloring. Currently this is done with Log4Net's ColoredConsoleAppender which is not compatible without output redirection or Linux.	CommandLineInteractive is used for ServiceStartupMode.
Standard	Specifies that log messages should be written to the console without coloring.	CommandLineInteractive is used for CommandLineNonInteractive.
Disabled	Specifies that log messages should not be written to the console at all.	WindowsService is used for CommandLineNonInteractive.

SiloClusterMode enum values

Name	Description	Is the default value when
PrimaryNode	Specifies that this node is the primary node in a local cluster, and should host its own in-memory membership and reminder tables.	Either CommandLineInteractive or CommandLineNonInteractive is used for ServiceStartupMode.
SecondaryNode	Specifies that this node is a secondary node in a local cluster, and should contact a primary node for membership and reminder tables. If running on the same computer as the PrimaryNode, then BasePortOverride should be used to prevent port conflicts.	Never, must be explicitly set.
ZooKeeper	Specifies that this node belongs to a real cluster, which has it's membership table managed by ZooKeeper and the reminder table stored on a MySQL table. Make sure that both ZooKeeper and MySQL connection strings are present in the configuration. Note: When this mode is used, there is no longer any localhost fallback for RemoteHostPool (i.e. for ServiceProxy and ResilientConfluentClient), so remote endpoints must be specified in the configuration.	WindowsService is used for CommandLineNonInteractive.