Replacing an Error instance using PowerShell

This article describes how to use PowerShell to replace an Error instance with zero downtime.

Disable error message ingestion

Configure the old Error instance so that it will no longer ingest new messages from the error queue:

1. Locate the ServiceControl.exe.config file.
2. In the appSettings section, add a setting key for ServiceControl/IngestErrorMessages with a value of false.
3. Restart the Error instance for the changes to take effect.

Replace the Error instance

In some cases, an instance where the database cannot be easily upgraded can be force upgraded, which involves moving the existing database aside and creating a brand new database in its place. The old database is not lost, but using it again would require reconfiguring the instance to look at the old database instead of the new one. A force-upgraded instance will retain the same API URL of the original.

The alternative is to create a brand new instance, which can be done to make it easier to roll back to the original, or must be done if the specific upgrade scenario doesn't support force upgrading.

Force upgrading the Error instance

Perform a Forced upgrade for the old Error instance. Note: This is a destructive operation. A database backup is made but will require application re-installation of the instance to recover.

# List existing error/primary instances
Get-ServiceControlInstances | Select Name, Version
# For each instance
Invoke-ServiceControlInstanceUpgrade -Name <InstanceName> -Force

Then, re-enable error message ingestion by removing the ServiceControl/IngestErrorMessages setting from the ServiceControl.exe.config file.

Once condfident that the upgrade process has been a success, the old database path (in a directory named DB_UpgradeBackup can be deleted.

Create a new Error instance

If the Error instance cannot be force-upgraded, instead create a new Error instance.

$serviceControlInstance = New-ServiceControlInstance `
  -Name Particular.ServiceControl.NewError `
  -InstallPath C:\ServiceControl.NewError\Bin `
  -DBPath C:\ServiceControl.NewError\DB`
  -LogPath C:\ServiceControl.NewError\Logs `
  -Port 33343 `
  -DatabaseMaintenancePort 33344 `
  -Transport MSMQ `
  -ErrorQueue error `
  -ErrorRetentionPeriod 10:00:00:00

Now that the instance is created, the configuration must be modified so that the Error instance can communicate with the same Audit instances as the previous Error instance. In this example, the Audit instance at http://localhost:4444 is added.

# For each Audit instance URL used by the existing Error instance
Add-ServiceControlRemote `
  -Name $serviceControlInstance.Name `
  -RemoteInstanceAddress "http://localhost:44444"

Now, the old and new Error instance's are both available, but the old Error instance is not ingesting messages.

When confident of a successful upgrade, the old Error instance can be removed:

Remove-ServiceControlInstance `
  -Name <OLD_INSTANCE_NAME> `
  -RemoveDB `
  -RemoveLogs