library/xPSDesiredStateConfiguration/9.2.0/DSCResources/DSC_xServiceResource/en-US/about_xService.help.txt
|
.NAME
xService .DESCRIPTION Provides a mechanism to configure and manage Windows services. This resource works on Nano Server. .PARAMETER 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. .PARAMETER Ensure Write - String Allowed values: Present, Absent Ensures that the service is present or absent. Defaults to Present. .PARAMETER 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. .PARAMETER StartupType Write - String Allowed values: Automatic, Manual, Disabled Indicates the startup type for the service. If StartupType is 'Disabled' and Service is not installed the resource will complete as being DSC compliant. .PARAMETER State Write - String Allowed values: Running, Stopped, Ignore Indicates the state you want to ensure for the service. Defaults to 'Running'. .PARAMETER BuiltInAccount Write - String Allowed values: LocalSystem, LocalService, NetworkService 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. .PARAMETER 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. .PARAMETER Credential Write - Instance 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. .PARAMETER 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. .PARAMETER DisplayName Write - String The display name of the service. .PARAMETER Description Write - String The description of the service. .PARAMETER Dependencies Write - StringArray An array of strings indicating the names of the dependencies of the service. .PARAMETER StartupTimeout Write - UInt32 The time to wait for the service to start in milliseconds. Defaults to 30000 (30 seconds). .PARAMETER TerminateTimeout Write - UInt32 The time to wait for the service to stop in milliseconds. Defaults to 30000 (30 seconds). .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' } } } |