Install-Service

Installs a Windows service.

Syntax

Install-Service -Name <String> -Path <String> [-ArgumentList <String[]>] [-StartupType {Boot | System | Automatic | Manual | Disabled}] [-OnFirstFailure {TakeNoAction | Restart | Reboot | RunCommand}] [-OnSecondFailure {TakeNoAction | Restart | Reboot | RunCommand}] [-OnThirdFailure {TakeNoAction | Restart | Reboot | RunCommand}] [-ResetFailureCount <Int32>] [-RestartDelay <Int32>] [-RebootDelay <Int32>] [-Dependency <String[]>] [-Command <String>] [-RunCommandDelay <Int32>] [-Description <String>] [-DisplayName <String>] [-Force] [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
Install-Service -Name <String> -Path <String> [-ArgumentList <String[]>] [-StartupType {Boot | System | Automatic | Manual | Disabled}] [-OnFirstFailure {TakeNoAction | Restart | Reboot | RunCommand}] [-OnSecondFailure {TakeNoAction | Restart | Reboot | RunCommand}] [-OnThirdFailure {TakeNoAction | Restart | Reboot | RunCommand}] [-ResetFailureCount <Int32>] [-RestartDelay <Int32>] [-RebootDelay <Int32>] [-Dependency <String[]>] [-Command <String>] [-RunCommandDelay <Int32>] [-Description <String>] [-DisplayName <String>] -UserName <String> [-Password <String>] [-Force] [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
Install-Service -Name <String> -Path <String> [-ArgumentList <String[]>] [-StartupType {Boot | System | Automatic | Manual | Disabled}] [-OnFirstFailure {TakeNoAction | Restart | Reboot | RunCommand}] [-OnSecondFailure {TakeNoAction | Restart | Reboot | RunCommand}] [-OnThirdFailure {TakeNoAction | Restart | Reboot | RunCommand}] [-ResetFailureCount <Int32>] [-RestartDelay <Int32>] [-RebootDelay <Int32>] [-Dependency <String[]>] [-Command <String>] [-RunCommandDelay <Int32>] [-Description <String>] [-DisplayName <String>] -Credential <PSCredential> [-Force] [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]

Description

Install-Service uses sc.exe to install a Windows service. If a service with the given name already exists, it is stopped, its configuration is updated to match the parameters passed in, and then re-started. Settings whose parameters are omitted are reset to their default values.

Beginning in Carbon 2.0, use the PassThru switch to return a ServiceController object for the new/updated service.

By default, the service is installed to run as NetworkService. Use the Credential parameter to run as a different account (if you don't have a Credential parameter, upgrade to Carbon 2.0 or use the UserName and Password parameters). This user will be granted the logon as a service right. To run as a system account other than NetworkService, provide just the account's name as the UserName parameter.

The minimum required information to install a service is its name and path.

Managed service accounts and virtual accounts should be supported (we don't know how to test, so can't be sure). Simply omit the -Password parameter when providing a custom account name with the -Username parameter.

Manual services are not started. Automatic services are started after installation. If an existing manual service is running when configuration begins, it is re-started after re-configured.

The ability to provide service arguments/parameters via the ArgumentList parameter was added in Carbon 2.0.

Related Commands

Parameters

Name Type Description Required? Pipeline Input Default Value
Name String

The name of the service.

true false
Path String

The path to the service.

true false
ArgumentList String[]

The arguments/startup parameters for the service. Added in Carbon 2.0.

false false
StartupType ServiceStartMode

The startup type: automatic, manual, or disabled. Default is automatic.

false false Automatic
OnFirstFailure FailureAction

What to do on the service's first failure. Default is to take no action.

false false TakeNoAction
OnSecondFailure FailureAction

What to do on the service's second failure. Default is to take no action.

false false TakeNoAction
OnThirdFailure FailureAction

What to do on the service' third failure. Default is to take no action.

false false TakeNoAction
ResetFailureCount Int32

How many seconds after which the failure count is reset to 0.

false false 0
RestartDelay Int32

How many milliseconds to wait before restarting the service. Default is 60,0000, or 1 minute.

false false 60000
RebootDelay Int32

How many milliseconds to wait before handling the second failure. Default is 60,000 or 1 minute.

false false 60000
Dependency String[]

What other services does this service depend on?

false false
Command String

The command to run when a service fails, including path to the command and arguments.

false false
RunCommandDelay Int32

How many milliseconds to wait before running the failure command. Default is 0, or immediately.

false false 0
Description String

The service's description. If you don't supply a value, the service's existing description is preserved.

The Description parameter was added in Carbon 2.0.

false false
DisplayName String

The service's display name. If you don't supply a value, the display name will set to Name.

The DisplayName parameter was added in Carbon 2.0.

false false
UserName String

The user the service should run as. Default is NetworkService.

true false
Password String

OBSOLETE. The Password parameter will be removed in a future major version of Carbon. Use the Credential parameter instead.

false false
Credential PSCredential

The credential of the account the service should run as.

The Credential parameter was added in Carbon 2.0.

true false
Force SwitchParameter

Update the service even if there are no changes.

false false False
PassThru SwitchParameter

Return a System.ServiceProcess.ServiceController object for the configured service.

false false False
WhatIf SwitchParameter false false
Confirm SwitchParameter false false
CommonParameters This cmdlet supports common parameters. For more information type
Get-Help about_CommonParameters.

Return Values

System.ServiceProcess.ServiceController.

EXAMPLE 1

Install-Service -Name DeathStar -Path C:\ALongTimeAgo\InAGalaxyFarFarAway\DeathStar.exe

Installs the Death Star service, which runs the service executable at C:\ALongTimeAgo\InAGalaxyFarFarAway\DeathStar.exe. The service runs as NetworkService and will start automatically.

EXAMPLE 2

Install-Service -Name DeathStar -Path C:\ALongTimeAgo\InAGalaxyFarFarAway\DeathStar.exe -StartupType Manual

Install the Death Star service to startup manually. You certainly don't want the thing roaming the galaxy, destroying thing willy-nilly, do you?

EXAMPLE 3

Install-Service -Name DeathStar -Path C:\ALongTimeAgo\InAGalaxyFarFarAway\DeathStar.exe -Credential $tarkinCredentials

Installs the Death Star service to run as Grand Moff Tarkin, who is given the log on as a service right.

EXAMPLE 4

Install-Service -Name DeathStar -Path C:\ALongTimeAgo\InAGalaxyFarFarAway\DeathStar.exe -Username SYSTEM

Demonstrates how to install a service to run as a system account other than NetworkService. Installs the DeathStart service to run as the local System account.

EXAMPLE 5

Install-Service -Name DeathStar -Path C:\ALongTimeAgo\InAGalaxyFarFarAway\DeathStar.exe -OnFirstFailure RunCommand -RunCommandDelay 5000 -Command 'engage_hyperdrive.exe "Corruscant"' -OnSecondFailure Restart -RestartDelay 30000 -OnThirdFailure Reboot -RebootDelay 120000 -ResetFailureCount (60*60*24)

Demonstrates how to control the service's failure actions. On the first failure, Windows will run the engage-hyperdrive.exe "Corruscant" command after 5 seconds (5,000 milliseconds). On the second failure, Windows will restart the service after 30 seconds (30,000 milliseconds). On the third failure, Windows will reboot after two minutes (120,000 milliseconds). The failure count gets reset once a day (60*60*24 seconds).