# Deploying ServiceControl Error instances using PowerShell


The `Particular.ServiceControl.Management` module can be installed from the [PowerShell Gallery](https://www.powershellgallery.com/packages/Particular.ServiceControl.Management), and is used to add, remove, update and delete instances of ServiceControl.

## Prerequisites



The ServiceControl PowerShell module requires a version of PowerShell (Core) greater or equal to the [oldest supported LTS version](https://learn.microsoft.com/en-us/powershell/scripting/install/powershell-support-lifecycle#powershell-end-of-support-dates). The [PowerShell Gallery page](https://www.powershellgallery.com/packages/Particular.ServiceControl.Management) will identify the minimum PowerShell version for each release.

Windows PowerShell is not supported.

> [!NOTE]
> The ServiceControl and PowerShell modules versions must match. When installing ServiceControl, instance versions must match the version of the PowerShell module used to install them.



## 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](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy) on how to change the execution policy.

The module can be installed from the PowerShell Gallery with the following command:

<!-- snippet: ps-install -->

```ps1
Install-Module -Name Particular.ServiceControl.Management
```

<!-- endsnippet -->

Once the module is installed, it can be used by importing the module into the PowerShell session with the following command:

<!-- snippet: ps-import -->

```ps1
Import-Module Particular.ServiceControl.Management
```

<!-- endsnippet -->

To obtain the version of the installed management module the following command can be used:

<!-- snippet: ps-getversion -->

```ps1
Get-Module Particular.ServiceControl.Management | Select-Object -ExpandProperty Version
```

<!-- endsnippet -->

> [!NOTE]
> 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 managing 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                |
| 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

<!-- snippet: ps-get-help -->

```ps1
Get-Help Get-ServiceControlManagementCommands
```

<!-- endsnippet -->


### Deploying an Error instance

Use the `New-ServiceControlInstance` cmdlet to deploy a new ServiceControl Error instance:

<!-- snippet: ps-new-error-instance -->

```ps1
$serviceControlInstance = New-ServiceControlInstance `
  -Name Test.ServiceControl `
  -InstallPath C:\ServiceControl\Bin `
  -DBPath C:\ServiceControl\DB `
  -LogPath C:\ServiceControl\Logs `
  -Port 33334 `
  -DatabaseMaintenancePort 33335 `
  -Transport MSMQ `
  -EnableIntegratedServicePulse `
  -ErrorQueue error1 `
  -ErrorRetentionPeriod 10:00:00:00
```

<!-- endsnippet -->

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](/servicecontrol/transports.md) 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:

<!-- snippet: ps-get-error-instances -->

```ps1
Get-ServiceControlInstances | Select Name, Version
```

<!-- endsnippet -->

### Removing an instance

Use the `Remove-ServiceControlInstance` cmdlet to remove the instance and delete the database and logs:

<!-- snippet: ps-remove-error-instance -->

```ps1
Remove-ServiceControlInstance `
  -Name Test.ServiceControl `
  -RemoveDB -RemoveLogs
```

<!-- endsnippet -->

### 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:

<!-- snippet: ps-update -->

```ps1
Update-Module -Name Particular.ServiceControl.Management
```

<!-- endsnippet -->

Once the PowerShell module is updated, use the `Invoke-ServiceControlInstanceUpgrade` cmdlet to upgrade the Audit instance to the installed version:

<!-- snippet: ps-upgrade-error-instance -->

```ps1
Invoke-ServiceControlInstanceUpgrade -Name InstanceToUpgrade
```

<!-- endsnippet -->

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.

> [!NOTE]
> Additional parameters may be required when upgrading instances. See the [upgrade guide](/servicecontrol/upgrades/index.md) for the specific version for more details.

### Licensing

The `Import-ServiceControlLicense` cmdlet copies the license file to [the machine-wide license location](/nservicebus/licensing/index.md#license-management-machine-wide-license-location) to make it available to all instances of ServiceControl installed on the machine.

<!-- snippet: ps-importlicense -->

```ps1
Import-ServiceControlLicense License.xml
```

<!-- endsnippet -->


## 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.

<!-- snippet: ps-testport -->

```ps1
Test-IfPortIsAvailable -Port 33333
```

<!-- endsnippet -->

This example shows the available ports out of a range of ports

<!-- snippet: ps-testportrange -->

```ps1
33330..33339 | Test-IfPortIsAvailable | ? Available
```

<!-- endsnippet -->

If the port is already in use, then choose a different port.