Installing ServiceControl • ServiceControl • Particular Docs

The ServiceControl installation file consists of an embedded MSI bootstrapper EXE and an embedded MSI. The installation package includes a utility to install, upgrade, and remove ServiceControl services. This utility is launched as the final step in the installation process and is also available via the Windows Start Menu.

A community managed puppet module is available to install ServiceControl.

Prerequisites

The ServiceControl installation has the following prerequisites:

Microsoft .NET 4.6.1 Runtime

ServiceControl should be installed on a separate dedicated machine with dedicated storage in a production environment to isolate the audit and error queue message ingestion. These operations have a big impact on other processes. ServiceControl must be given sufficient CPU, RAM (6GB minimum) and storage suitable for low-latency write operations, similar to how a database server would be provisioned. See ServiceControl Capacity Planning for more guidance.

Transport support

In ServiceControl version 1.7 and above, the transport packages are managed by the installation and do not need to be downloaded from NuGet. ServiceControl can be configured to use one of the supported transports listed below using the ServiceControl Management application:

Transport-specific features

Transport adapters

Certain transport features are not supported natively by ServiceControl and will require a transport adapter. Contact support@particular.net for further guidance.

Adding third-party transports via the ServiceControl Management application is not supported.

MSMQ

If MSMQ is the selected transport, ensure the MSMQ service has been installed and configured as outlined in Installing The Platform Components.

RabbitMQ

In addition to the connection string options of the transport the following ServiceControl specific options are available in versions 4.4 and above:

UseExternalAuthMechanism=true|false(default) - Specifies that an external authentication mechanism should be used for client authentication.
DisableRemoteCertificateValidation=true|false(default) - Allows ServiceControl to connect to the broker even if the remote server certificate is invalid.

Azure Service Bus

In addition to the connection string options of the transport the following ServiceControl specific options are available in versions 4.4 and above:

QueueLengthQueryDelayInterval=<value_in_milliseconds> - Specifies delay between queue length refresh queries. The default value is 500 ms.
TopicName=<topic-bundle-name> - Specifies topic name to be used by the instance. The default value is bundle-1.

SQL

In addition to the connection string options of the transport the following ServiceControl specific options are available in versions 4.4 and above:

Queue Schema=<schema_name> - Specifies custom schema for the ServiceControl input queue.

Amazon SQS

The following ServiceControl connection string options are available in versions 4.4 and above:

AccessKeyId=<value> - AssessKeyId value,
SecretAccessKey=<value> - SecretAccessKey value,
Region=<value> - Region transport option,
QueueNamePrefix=<value> - Queue name prefix transport option,
S3BucketForLargeMessages=<value> - S3 bucket for large messages option,
S3KeyPrefix=<value> - S3 key prefic option.

Performance counter

Metrics are reported via the performance counters if the counters are installed.

For instructions on how to install the performance counters, refer to Installing The Platform Components Manually

The installation of the NServiceBus performance counters is optional for ServiceControl version 1.7 and above.

Using ServiceControl Management to upgrade ServiceControl instances

ServiceControl Management provides a simple means of setting up one or more instances of ServiceControl service types (error, audit, and monitoring). For production systems, it is recommended to limit the number of instances per machine to one.

The ability to add multiple instances of the same type on a single machine is primarily intended to assist development and test environments.

ServiceControl Management can be launched automatically at the end of the installation process to enable adding or upgrading ServiceControl instances.

ServiceControl Management will display the instances of the ServiceControl service installed. If the version of the binaries used by an instance are older than those shipped with ServiceControl Management, an upgrade link will be shown next to the version label.

To upgrade the service, click the upgrade link next to the service name.

Clicking the upgrade link will:

Prompt for additional required information, i.e. new mandatory settings introduced in the newer version
Stop the service
Remove the old binaries for ServiceControl and the configured transport
Run the new binaries to create required queues
Start the service

Using ServiceControl Management to add ServiceControl instances

If this is a new installation of ServiceControl, click on the Add New Instance button in the center of the screen or the "New Instance" link at the top of the screen; both options launch the "New instance form". Complete the form to register a new ServiceControl service.

Service name and plugins

When adding the first instance of the ServiceControl service, the default service name is "Particular.ServiceControl". This can be changed to a custom service name. This will also change the queue name associated with this instance of ServiceControl.

The ServiceControl queue name is required for configuring the endpoint plugins. See Install Heartbeats Plugin and Install Custom Checks Plugin for more information.

Removing ServiceControl

To perform a clean uninstallation of ServiceControl from a machine:

Remove each ServiceControl instance using ServiceControl Management (or PowerShell)
Uninstall ServiceControl Management using Add or Remove programs

Remove ServiceControl instances

To remove a ServiceControl instance, click the Advanced Options button and select Remove. If applicable, select the option to remove the database and logs directories. This will stop the running instance (if it is running) and remove all files related to the instance from the local file system.

Remaining artifacts

Even after a ServiceControl instance has been removed, there are artifacts left behind. Each ServiceControl instance leaves queues in the configured transport. The queue names will depend on the configuration of the ServiceControl instance.

instance name - control messages for the ServiceControl instance
instance name.errors - control messages that the ServiceControl instance was not able to process
instance name.staging - temporary failed messages while they are being retried
audit queue name - messages that have been processed by endpoints and then forwarded to the audit queue. These messages have not yet been ingested by the ServiceControl instance.
error queue name - messages that failed processing in endpoints and have passed immediate and delayed retries. These messages have not yet been ingested by the ServiceControl instance.
audit log queue name if audit log forwarding was configured - messages that have been ingested from the audit queue, processed by this ServiceControl instance, and then forwarded to the audit log queue.
error log queue name if error log forwarding was configured - messages that have been ingested from the error queue, processed by this ServiceControl instance, and then forwarded to the error log queue.

If the option to delete the database/log folders was not selected when removing the instance, then these folders and their contents are left on disk.

If the instance was configured to run under a service account then that account may have been granted Logon as a Service privileges. This is not reversed when the instance is removed.

Uninstall ServiceControl Management

To uninstall ServiceControl Management, use the Apps & features settings in Windows.

Uninstalling the ServiceControl Management application will not remove existing instances. Remove all ServiceControl instances using ServiceControl Management before uninstalling the application itself.