The Particular.
module can be installed from the PowerShell Gallery, and is used to add, remove, update and delete instances of ServiceControl.
Prerequisites
The ServiceControl PowerShell module has the following prerequisites:
- PowerShell (Core) 7.2 or later
Installing and using the PowerShell module
In order to use the PowerShell module, the PowerShell execution policy needs to be set to RemoteSigned
. Refer to the PowerShell documentation on how to change the execution policy.
The module can be installed from the PowerShell Gallery with the following command:
Install-Module -Name Particular.ServiceControl.Management
Once the module is installed, it can be used by importing the module into the PowerShell session with the following command:
Import-Module Particular.ServiceControl.Management
To obtain the version of the installed management module the following command can be used:
Get-Module Particular.ServiceControl.Management | Select-Object -ExpandProperty Version
The majority of the cmdlets will only work if the PowerShell session is running with administrator privileges.
Error instance Cmdlets and Aliases
The following cmdlets and aliases are provided by the ServiceControl Management PowerShell module for the management of ServiceControl Error instances.
Alias | Cmdlet |
---|---|
sc-add | New-ServiceControlInstance |
sc-delete | Remove-ServiceControlInstance |
sc-instances | Get-ServiceControlInstances |
sc-upgrade | Invoke-ServiceControlInstanceUpgrade |
The following general cmdlets and aliases are provided by the ServiceControl Management PowerShell module.
Alias | Cmdlet |
---|---|
sc-addlicense | Import-ServiceControlLicense |
sc-findlicense | Get-ServiceControlLicense |
sc-transportsinfo | Get-ServiceControlTransportTypes |
sc-help | Get-ServiceControlMgmtCommands |
urlacl-add | Add-UrlAcl |
urlacl-delete | Remove-UrlAcl |
urlacl-list | Get-UrlAcls |
port-check | Test-IfPortIsAvailable |
user-sid | Get-SecurityIdentifier |
Help
All of the cmdlets have local help which can be accessed via the standard PowerShell help command
Get-Help Get-ServiceControlManagementCommands
Deploying an Error instance
Use the New-ServiceControlInstance
cmdlet to deploy a new ServiceControl Error instance:
$serviceControlInstance = New-ServiceControlInstance `
-Name Test.ServiceControl `
-InstallPath C:\ServiceControl\Bin `
-DBPath C:\ServiceControl\DB `
-LogPath C:\ServiceControl\Logs `
-Port 33334 `
-DatabaseMaintenancePort 33335 `
-Transport MSMQ `
-ErrorQueue error1 `
-ErrorRetentionPeriod 10:00:00:00
Use the Get-Help
cmdlet for a full list of parameters available.
Use the Get-ServiceControlTransportTypes
cmdlet to determine the correct -Transport
value to use. See the ServiceControl transport guide for transport configuration options via the connection string.
Listing deployed instances
Use the Get-ServiceControlInstances
cmdlet to find a list of all of the ServiceControl Error instances and their version numbers:
Get-ServiceControlInstances | Select Name, Version
Removing an instance
Use the Remove-ServiceControlInstance
cmdlet to remove the instance and delete the database and logs:
Remove-ServiceControlInstance `
-Name Test.ServiceControl `
-RemoveDB -RemoveLogs
Upgrading a deployed instance
The ServiceControl PowerShell module must be updated to deploy a newer version of a ServiceControl instance, as the binaries are embedded in the module version that is installed.
To update the PowerShell module use the following command:
Update-Module -Name Particular.ServiceControl.Management
Once the PowerShell module is updated, use the Invoke-ServiceControlInstanceUpgrade
cmdlet to upgrade the Audit instance to the installed version:
Invoke-ServiceControlInstanceUpgrade -Name InstanceToUpgrade
If the instance is running when the upgrade starts, it will be shut down during the upgrade and restarted once the upgrade is complete.
Before the upgrade begins the configuration file of the existing version is examined to determine if all of the required settings are present. If a configuration setting is missing then the cmdlet will throw an error indicating the required additional parameter for the cmdlet.
Additional parameters may be required when upgrading instances. See the upgrade guide for the specific version for more details.
Licensing
Copies the license file to the machine-wide license location so it is available to all instances of ServiceControl installed on the machine.
Import-ServiceControlLicense License.xml
Troubleshooting via PowerShell
The ServiceControl Management PowerShell module offers some cmdlets to assist with troubleshooting the installation of ServiceControl instances.
Check if a port is already in use
Before adding an instance of ServiceControl test if the port to use is currently in use.
Test-IfPortIsAvailable -Port 33333
This example shows the available ports out of a range of ports
33330..33339 | Test-IfPortIsAvailable | ? Available
If the port is already in use, then choose a different port.
Checking and manipulating UrlAcls
The Window HTTPServer API is used by underlying components in ServiceControl. This API uses a permissions system to limit what accounts can add a HTTP listener to a specific URI. The standard mechanism for viewing and manipulating these ports is with the netsh.exe command line tool.
For example netsh.
will list all of the available UrlAcls. This output is detailed but not easy to query. The ServiceControl Management PowerShell provides simplified PowerShell equivalents for listing, adding, and removing UrlAcls and makes the output easier to query.
For example the following command lists all of the UrlAcls assigned to any URI for port 33333.
Get-UrlAcls | ? Port -eq 33333
In this example any UrlAcl on port 33335 is removed
Get-UrlAcls | ? Port -eq 33335 | Remove-UrlAcl
The following example shows how to add a UrlAcl for a ServiceControl service that should only respond to a specific DNS name. This would require an update of the ServiceControl configuration file as well. Refer to setting a custom host name and port number
Add-UrlAcl -Url http://servicecontrol.mycompany.com:33333/api/ -Users Users