Install-ChocolateyWindowsService

NOTE: This function requires a Chocolatey for Business License to use.

Installs a Windows Service using Install Util, plus some extra awesome-sauce.

Syntax

Install-ChocolateyWindowsService `
  -Name <string> `
  -ServiceExecutablePath <string> `
  [-Username <string>] `
  [-Password <string>] `
  [-DisplayName <string>] `
  [-Description <string>] `
  [-StartupType <ChocolateyWindowsServiceStartupType> {Unknown | Manual | Automatic | Disabled}] `
  [-DoNotStartService] `
  [-DoNotReinstallService] `
  [<CommonParameters>]

Description

This installs a Windows Service onto a machine. When provided a user name, this
will ensure that user exists, is in the Administrators group, and has all of the
correct privileges to run as a service. For more details on the privileges, see
the Username parameter below.

If a user is not a built in user and no password is provided, Chocolatey will
manage the password, which will be different for every machine and user and very
complex. For more details on the password, see the Password parameter below.

One of the additional advanced features of this function is being able to
upgrade a service without shutting it down first - Chocolatey will move the
current running service and put in all of the new binaries. It will require a
restart of the service to move to the new code, but you can upgrade a service in
place without shutting it down first (one time). To use this, you must supply
the DoNotReinstallService switch. See the parameter below for more details.

Notes

Requires Chocolatey for Business.

Aliases

None

Examples

EXAMPLE 1

Install-ChocolateyWindowsService -Name 'bob' -ServiceExecutablePath 'c:\somewhere\to\service.exe'

EXAMPLE 2

$toolsDir   = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"
$serviceExe = Join-Path $toolsDir 'service\dan-agent.exe'

$packageArgs = @{
  Name                  = 'dan'
  DisplayName           = 'Dan Agent'
  ServiceExecutablePath = $serviceExe
  Username              = 'DanTheBuilder'
}

Install-ChocolateyWindowsService @packageArgs

EXAMPLE 3
This is the installation code for the Chocolatey Agent service itself.

$toolsDir   = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"
$serviceExe = Join-Path $toolsDir 'service\chocolatey-agent.exe'

$packageArgs = @{
  Name                  = 'chocolatey-agent'
  DisplayName           = 'Chocolatey Agent'
  Description           = 'Chocolatey Agent is a backgound service for Chocolatey.'
  StartupType           = 'Automatic'
  ServiceExecutablePath = $serviceExe
  Username              = 'ChocolateyLocalAdmin'
}

$pp = Get-PackageParameters
if ($pp['Username']) { $packageArgs['Username'] = $pp['Username'] }
if ($pp['Password']) { $packageArgs['Password'] = $pp['Password'] }
if ($pp['EnterPassword']) { $packageArgs['Password'] = Read-Host "Enter password for $($packageArgs['Username']):" -AsSecureString}
if ($pp['UseDefaultChocolateyConfigUser']) { $packageArgs.Remove('Username') }

# We don't want to shut down the service when we are running in background mode
if ($env:ChocolateyBackgroundService -eq 'true') {
  Write-Warning "Detected running in background mode to upgrade the chocolatey-agent. Upgrade will attempt without restarting the service. \n Changes to service itself (like user/password) will be ignored."
  $packageArgs['DoNotReinstallService'] = $true
}

# Explicit request not to restart or reinstall the service.
if ($pp['NoRestartService'] -or $pp['DoNotReinstallService']) {
  Write-Warning "Upgrade will attempt without restarting the service. \n Changes to service itself (like user/password) will be ignored."
  $packageArgs['DoNotReinstallService'] = $true
}

Install-ChocolateyWindowsService @packageArgs

Inputs

None

Outputs

None

Parameters

-Description [<string>]

The description of the service.

Property Value
Aliases
Required? false
Position? Named
Default Value
Accept Pipeline Input? true (ByPropertyName)

-DisplayName [<string>]

The display name of the service.

Property Value
Aliases
Required? false
Position? Named
Default Value
Accept Pipeline Input? true (ByPropertyName)

-DoNotReinstallService

Do not uninstall/restart service. This is for advanced scenarios when you need
to deploy a newer version of a service and control when the restart happens over
to the newly deployed code.

Property Value
Aliases
Required? false
Position? Named
Default Value
Accept Pipeline Input? true (ByPropertyName)

-DoNotStartService

Do not start service after install. This keeps the service from starting up when
installing/upgrading.

Property Value
Aliases
Required? false
Position? Named
Default Value
Accept Pipeline Input? true (ByPropertyName)

-Name <string>

The name of the service to install.

Property Value
Aliases
Required? true
Position? 0
Default Value
Accept Pipeline Input? true (ByPropertyName)

-Password [<string>]

The password for the service - defaults to empty. If the user is not a built-in
account like LocalSystem and the user name is provided without a password being
provided, the password will automatically be a Chocolatey Managed Password.

When Chocolatey manages the password for an account, it creates a very complex
password:

No one at Chocolatey Software could even tell you what the password is for a
particular machine without local access.

Property Value
Aliases
Required? false
Position? Named
Default Value
Accept Pipeline Input? true (ByPropertyName)

-ServiceExecutablePath <string>

The full path (absolute path) to the service executable file.

Property Value
Aliases
Required? true
Position? 1
Default Value
Accept Pipeline Input? true (ByPropertyName)

-StartupType [<ChocolateyWindowsServiceStartupType>]

The startup type of the service. Defaults to Automatic.

Property Value
Aliases
Required? false
Position? Named
Default Value
Accept Pipeline Input? true (ByPropertyName)

-Username [<string>]

The username for the service - defaults to LocalSystem (SYSTEM). If the user
does not exist, the user will be created. When a user is specified for a
service, the following things will also occur as part of this function:

Property Value
Aliases user
Required? false
Position? 2
Default Value
Accept Pipeline Input? true (ByPropertyName)

Function Reference

NOTE: This documentation has been automatically generated from licensed code.