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.
Prerequisites
The ServiceControl installation has the following prerequisites:
See ServiceControl Capacity Planning and Hardware Considerations 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:
- Azure Service Bus
- Azure Service Bus - Endpoint-oriented topology
- Azure Service Bus - Forwarding topology
- Azure Storage Queues
- Amazon Simple Queue Service (SQS)
- Microsoft Message Queuing (MSMQ)
- RabbitMQ - Conventional routing topology
- RabbitMQ - Direct routing topology
- SQL Server
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=
- Specifies delay between queue length refresh queries. The default value is 500 ms.<value_in_milliseconds> TopicName=
- Specifies topic name to be used by the instance. The default value is<topic-bundle-name> 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=
- Specifies custom schema for the ServiceControl input queue.<schema_name>
Amazon SQS
The following ServiceControl connection string options are available in versions 4.4 and above:
AccessKeyId=
- AssessKeyId value,<value> SecretAccessKey=
- SecretAccessKey value,<value> Region=
- Region transport option,<value> QueueNamePrefix=
- Queue name prefix transport option,<value> S3BucketForLargeMessages=
- S3 bucket for large messages option,<value> S3KeyPrefix=
- S3 key prefic option.<value>
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.
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.
Migrating to a new host
These are the steps to perform to migrate an instance of ServiceControl to another host:
- Ensure the same Windows version is used on the new machine as storage is not compatible between Windows versions.
- Stop and disable the current instance of ServiceControl in the Windows Service Manager.
- Install and configure a new instance of ServiceControl using the same name on the new server.
- Ensure the name is identical
- Stop the newly installed instance of ServiceControl.
- Copy the data from the previous instance to the new instance server (moving the data is not recommended).
- Start the new service.
- Remove the old instance of ServiceControl.
Things to remember:
- First update the current instance to the latest version.
- Optionally, use the same installer as the current version. Database schemas are not guaranteed to be compatible between different 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.
, ServiceControl.
, and ServiceControl.
.
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.
Uninstall ServiceControl Management
To uninstall ServiceControl Management, use the Apps & features
settings in Windows.