Installing ServiceControl

Every component in the Particular Service Platform (not including NServiceBus), including ServiceControl, must be downloaded and installed.

After installation, there is no ServiceControl instance running yet. Instances can be installed, upgraded, and removed using the ServiceControl Management Utility. This utility is launched as the final step in the installation process and is also available via the Windows start menu.

Prerequisites

The ServiceControl installation has the following prerequisites:

• Microsoft .NET 4.7.2 Runtime

Planning

The ServiceControl Management Utility provides a simple way to set up one or more ServiceControl instances (error, audit, and monitoring). For production systems, it is recommended to limit the number of instances per machine to one of each type. The ability to add multiple instances of the same type on a single machine is primarily intended to assist development and test environments.

See ServiceControl Capacity Planning and Hardware Considerations for more guidance.

Installing ServiceControl instances

There are three types of ServiceControl instances that can be installed using the ServiceControl Management utility. As the error and audit instance usually go side-by-side, they are installed and configured at the same time.

1. Open the ServiceControl Management Utility in the Windows start menu.
2. Click the New button at the top-right and a popup window appears.
3. Select either Add ServiceControl and Audit instances or Add monitoring instance.
4. Provide a name and transport.
   1. The default name is Particular.ServiceControl. The name is used to derive names for the error and audit instances. The name of each instance can be adjusted from its default if required.
   2. The transport should match the endpoint's transport. If a transport is not available, a transport adapter can be used.
5. For additional instance settings, open the ServiceControl and ServiceControl Audit sections.
   1. The name of the instance can be modified; the defaults for error and audit are Particular.ServiceControl and Particular.ServiceControl.Audit.
      1. The name of the error instance is especially important to enable plugins to send information to ServiceControl.
      2. If multiple instances for different systems are installed on the same server, a name like Particular.SystemName is a common option.
   2. Select the appropriate user account. Note that ServiceControl instances will run as Windows Services in the background.
   3. Be aware of the port numbers as these are used by ServicePulse and ServiceInsight to connect to ServiceControl.
   4. Configure the retention period for each instance.
   5. Configure the name of the queue that messages should arrive in. This queue is important to endpoints that send error and audit messages to these ServiceControl instances, as well as plugins.
   6. If needed, configure forwarding queues.
   7. Full-text search can be turned off for performance reasons if it's not needed.

A monitoring instance differs from error and audit instances in its configuration:

1. There is no configuration for storage as it only stores data in memory.
2. There is no forwarding queue as the messages are specific to ServiceControl monitoring.
3. The queue to forward messages that can't be processed to is different, as described in monitoring setup.

As an example, after configuring an error, audit and monitoring instance for the SQL Server transport, the ServiceControl Management Utility will look similar to this:

Upgrading ServiceControl instances

ServicePulse will show a notification when a new version of ServiceControl is available. New versions can then be downloaded and installed.

The ServiceControl Management Utility displays the instances of the ServiceControl service installed on the current machine. If a ServiceControl instance is running on an outdated version, 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

Upgrading multiple major versions

A ServiceControl installation should be upgraded one major version at a time. Check the currently installed version of ServiceControl to look up the upgrade path in the table below. For each entry in the upgrade path, install the listed version and upgrade all ServiceControl instances to that version. Once all instances are upgraded and running, install the listed version in the next row until all instances are upgraded to the latest version.

All versions are available at https://github.com/Particular/ServiceControl/releases

ServiceControl plugins

Endpoint plugins like heartbeats and custom checks require sending information to ServiceControl. The name of the queue is the same name as the error instance.

See Install Heartbeats Plugin and Install Custom Checks Plugin for more information.

Migrating to a new host

To migrate an instance of ServiceControl to another host:

1. Ensure the same Windows version is used on the new machine as storage is not compatible between Windows versions
2. Stop and disable the current instance of ServiceControl in the Windows Service Manager
3. Install and configure a new instance of ServiceControl using the same name on the new server
4. Ensure the name is identical
5. Stop the newly installed instance of ServiceControl
6. Copy the data from the previous instance to the new instance server (moving the data is not recommended)
7. Start the new service
8. Remove the old instance of ServiceControl

Things to remember:

• Ensure the instance being migrated is on the latest version.
• Optionally, use the same installer as the current version. Database schemas are not guaranteed to be compatible between versions.
• Optionally, script ServiceControl installations via powershell instead of running installers manually

ServiceControl configuration settings are accessible via the Service Control Management Utility or by navigating to the configuration files on the file system stored in ServiceControl.exe.config, ServiceControl.Audit.exe.config, and ServiceControl.Monitoring.exe.config.

Removing ServiceControl

To perform a clean uninstall of ServiceControl from a machine:

1. Remove each ServiceControl instance using the ServiceControl Management Utility (or PowerShell)
2. Uninstall the ServiceControl Management Utility 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.

Uninstall the ServiceControl Management Utility

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