Alternative ServiceControl v4 upgrade option

The standard guide to upgrade ServiceControl from 4 to 5 assumes that all failed messages can be retried without side-effects. In cases where this cannot be confirmed, the approach below can be used to upgrade ServiceControl v4.

Monitor Instances

Monitor instances are stateless and can be safely reinstalled elsewhere:

• Remove the old instance from (virtual) machine 1.
• Install the same monitor instance name on (virtual) machine 2.

No special migration steps required.

Audit Instances

Audit v4 instances do not need to be migrated. They can remain active until the retention period expires.

To stop ingesting audit messages:

1. Stop and disable the old audit instance in Windows Services.
2. Add the following setting to servicecontrol.audit.exe.config:

   <add key="ServiceControl.Audit/IngestAuditMessages" value="False" />
   

3. Start and enable the instance again.
4. Confirm it's no longer ingesting by checking that the audit queue is building up.

Error Instances

The error instance needs to be prevented from ingesting, renamed, and replaced.

Steps:

1. Stop and disable the v4 error instance
2. Prevent error queue ingestion
3. Change the instance’s queue name
4. Run setup
5. Enable and start the v4 error instance
6. Verify the instance
7. Add a new error instance

Stop and Disable v4 Error Instance

1. Open Windows Services.
2. Locate the error instance, right-click → Properties.
3. Set Startup type to Disabled → Apply.
4. Click Stop.

Configure to Stop Ingestion of Error Queue

1. Locate the instance folder (via ServiceControl Management Utility → Installation location → 📁 Browse...)
2. Open servicecontrol.exe.config in an elevated text editor
3. Add:

   <add key="ServiceControl/IngestErrorMessages" value="False" />
   

4. Save the file

Change ServiceControl Instance Queue

1. Open regedit and navigate to:

   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
   

2. Find the key representing the ServiceControl service
3. Export it as a backup
4. Locate ImagePath, note the --serviceName argument
5. Modify the service name to a unique value, e.g.:

   --serviceName=particular.servicecontrol_v4
   

Run Setup

1. Open an elevated command prompt
2. Navigate to the install folder, e.g.:

   C:\Program Files (x86)\Particular Software\Particular.ServiceControl
   

3. Run:

   servicecontrol.exe -s --serviceName=particular.servicecontrol_v4
   

Enable and Start v4 Error Instance

1. Open Windows Services
2. Locate the error instance, right-click → Properties
3. Set Startup type to Automatic → Apply
4. Click Start

Verify Instance is Running Without Issues

1. Open the log folder (via ServiceControl Management Utility → Log Path → 📁 Browse...)
2. Open the latest logfile.{YYYY-MM-DD}
3. Scroll to the end and ensure no errors are present

Add New Error Instance

1. Add a new error instance as usual (on the same machine or a new one)
2. Configure it as needed to take over ingestion