xService

xService

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
Name	Key	String	Indicates the service name. Note that sometimes this is different from the display name. You can get a list of the services and their current state with the Get-Service cmdlet.
Ensure	Write	String	Ensures that the service is present or absent. Defaults to Present.	Present, Absent
Path	Write	String	The path to the service executable file. Required when creating a service. The user account specified by BuiltInAccount or Credential must have access to this path in order to start the service.
StartupType	Write	String	Indicates the startup type for the service. If StartupType is 'Disabled' and Service is not installed the resource will complete as being DSC compliant.	Automatic, Manual, Disabled
State	Write	String	Indicates the state you want to ensure for the service. Defaults to 'Running'.	Running, Stopped, Ignore
BuiltInAccount	Write	String	The built-in account the service should start under. Cannot be specified at the same time as Credential or GroupManagedServiceAccount. The user account specified by this property must have access to the service executable path defined by Path in order to start the service.	LocalSystem, LocalService, NetworkService
GroupManagedServiceAccount	Write	String	The Group Managed Service Account the service should start under. Cannot be specified at the same time as Credential or BuiltinAccount. The user account specified by this property must have access to the service executable path defined by Path in order to start the service. When specified in a DOMAIN\User$ form, remember to also input the trailing dollar sign.
Credential	Write	PSCredential	The credential of the user account the service should start under. Cannot be specified at the same time as BuiltInAccount or GroupManagedServiceAccount. The user specified by this credential will automatically be granted the Log on as a Service right. The user account specified by this property must have access to the service executable path defined by Path in order to start the service.
DesktopInteract	Write	Boolean	Indicates whether or not the service should be able to communicate with a window on the desktop. Must be false for services not running as LocalSystem. The default value is False.
DisplayName	Write	String	The display name of the service.
Description	Write	String	The description of the service.
Dependencies	Write	StringArray[]	An array of strings indicating the names of the dependencies of the service.
StartupTimeout	Write	UInt32	The time to wait for the service to start in milliseconds. Defaults to 30000 (30 seconds).
TerminateTimeout	Write	UInt32	The time to wait for the service to stop in milliseconds. Defaults to 30000 (30 seconds).

Description

Provides a mechanism to configure and manage Windows services. This resource works on Nano Server.

Examples

Example 1

#Requires -Module xPSDesiredStateConfiguration

<#
    .DESCRIPTION
        Configuration that changes the state for an existing service.

    .PARAMETER Name
        The name of the Windows service.

    .PARAMETER State
        The state that the Windows service should have.

    .EXAMPLE
        xService_ChangeServiceState_Config -Name 'spooler' -State 'Stopped'

        Compiles a configuration that make sure the state for the Windows
        service 'spooler' is 'Stopped'. If the service is running the
        Windows service will be stopped.
#>
Configuration xService_ChangeServiceState_Config
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Name,

        [Parameter()]
        [ValidateSet('Running', 'Stopped')]
        [System.String]
        $State = 'Running'
    )

    Import-DscResource -ModuleName xPSDesiredStateConfiguration

    Node localhost
    {
        xService ChangeServiceState
        {
            Name   = $Name
            State  = $State
            Ensure = 'Present'
        }
    }
}

Example 2

#Requires -Module xPSDesiredStateConfiguration

<#
    .DESCRIPTION
        Configuration that creates a new Windows service from an executable.
        The executable must be built to run as a Windows service.

    .PARAMETER Path
        The path to the executable for the Windows service.

    .PARAMETER Name
        The name of the Windows service to be created.

    .EXAMPLE
        xService_CreateService_Config -Path 'C:\FilePath\MyServiceExecutable.exe' -Name 'Service1'

        Compiles a configuration that creates a new service with the name Service1
        using the executable path 'C:\FilePath\MyServiceExecutable.exe'.
        If the service with the name Service1 already exists and the executable
        path is different, then the executable will be changed for the service.
        The service is started by default if it is not running already.
#>
Configuration xService_CreateService_Config
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Path,

        [Parameter(Mandatory = $true)]
        [System.String]
        $Name
    )

    Import-DscResource -ModuleName xPSDesiredStateConfiguration

    Node localhost
    {
        xService CreateService
        {
            Name   = $Name
            Ensure = 'Present'
            Path   = $Path
        }
    }
}

Example 3

#Requires -Module xPSDesiredStateConfiguration

<#
    .DESCRIPTION
        Configuration that creates a new Windows service from an executable.
        The executable must be built to run as a Windows service.

    .PARAMETER Path
        The path to the executable for the Windows service.

    .PARAMETER Name
        The name of the Windows service to be created.

    .PARAMETER GroupManagedServiceAccount
        The name of the GroupManagedServiceAccount to run the service.

    .EXAMPLE
        $gmsaSplat = @{
            Path                        = 'C:\FilePath\MyServiceExecutable.exe'
            Name                        = 'Service1'
            GroupManagedServiceAccount  = 'DOMAIN\gMSA$'
        }

        xService_CreateServiceConfigGroupManagedServiceAccount_Config @gmsaSplat

        Compiles a configuration that creates a new service with the name Service1
        using the executable path 'C:\FilePath\MyServiceExecutable.exe'.
        If the service with the name Service1 already exists and the executable
        path is different, then the executable will be changed for the service.
        The service is started by default if it is not running already. The user
        DOMAIN\gMSA$ is used to start the service, the username could also be provided
        in UPN format (gMSA$@domain.fqdn).
#>
Configuration xService_CreateServiceConfigGroupManagedServiceAccount_Config
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Path,

        [Parameter(Mandatory = $true)]
        [System.String]
        $Name,

        [Parameter(Mandatory = $true)]
        [System.String]
        $GroupManagedServiceAccount
    )

    Import-DscResource -ModuleName xPSDesiredStateConfiguration

    Node localhost
    {
        xService CreateService
        {
            Name                        = $Name
            Ensure                      = 'Present'
            Path                        = $Path
            GroupManagedServiceAccount  = $GroupManagedServiceAccount
        }
    }
}

Example 4

#Requires -Module xPSDesiredStateConfiguration

<#
    .DESCRIPTION
        Configuration that stops and then removes a Windows service.

    .PARAMETER Name
        The name of the Windows service to be removed.

    .EXAMPLE
        xService_RemoveService_Config -Name 'Service1'

        Compiles a configuration that stops and then removes the service with the
        name Service1.
#>
Configuration xService_RemoveService_Config
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Name
    )

    Import-DscResource -ModuleName xPSDesiredStateConfiguration

    Node localhost
    {
        xService RemoveService
        {
            Name   = $Name
            Ensure = 'Absent'
        }
    }
}

Example 5

#Requires -Module xPSDesiredStateConfiguration

<#
    .DESCRIPTION
        Configuration that updates startup type to manual for the service Print
        Spooler, ignoring it's current state (e.g. running, stopped, etc).

    .NOTES
        If the service with the name spooler does not exist, this configuration would throw an
        error since the Path is not included here.

        If the service with the name spooler already exists, sets the startup type of the service
        with the name spooler to Manual and ignores the state that the service is currently in.
        If State is not specified, the configuration will ensure that the state of the service is
        Running by default.

    .EXAMPLE
        xService_UpdateStartupTypeIgnoreState_Config

        Compiles a configuration that make sure the service Print Spooler
        has the startup type set to 'Manual' regardless of the current state
        of the service (e.g. running, stopped, etc).
#>
Configuration xService_UpdateStartupTypeIgnoreState_Config
{
    [CmdletBinding()]
    param ()

    Import-DscResource -ModuleName xPSDesiredStateConfiguration

    Node localhost
    {
        xService ServiceResource1
        {
            Name = 'spooler'
            Ensure = 'Present'
            StartupType = 'Manual'
            State = 'Ignore'
        }
    }
}