Edit

Microsoft.Windows/Service

Synopsis

Manage Windows services.

Metadata

Version    : 0.1.0
Kind       : resource
Tags       : [Windows]
Author     : Microsoft

Instance definition syntax

resources:
  - name: <instance name>
    type: Microsoft.Windows/Service
    properties:
      # Key properties
      name: string
      # Instance properties
      description:
      dependencies:
      displayName:
      errorControl:
      executablePath:
      logonAccount:
      startType:
      status:

Description

The Microsoft.Windows/Service resource enables you to idempotently manage the configuration and runtime state of Windows services registered with the Service Control Manager (SCM). The resource can:

  • Retrieve the full configuration and status of a service.
  • Change the start type, status, description, display name, logon account, error control, executable path, and service dependencies.
  • Export a list of all services registered on the system.

Note

This resource is installed with DSC itself on Windows systems.

You can update this resource by updating DSC. When you update DSC, the updated version of this resource is automatically available.

Requirements

  • The resource is only usable on a Windows system.
  • Set operations require an elevated (administrator) process context. Running dsc without elevation when using the Set operation causes an access-denied error from the SCM.

Capabilities

The resource has the following capabilities:

  • get - You can use the resource to retrieve the actual state of a service instance.
  • set - You can use the resource to enforce the desired configuration and status of a service.
  • export - You can use the resource to export a list of all services registered on the system.

This resource uses the synthetic test functionality of DSC to determine whether an instance is in the desired state. For more information about resource capabilities, see DSC resource capabilities.

Examples

  1. Get service status - Shows how to retrieve the current state of a Windows service with the dsc resource commands.
  2. Configure a Windows service - Shows how to enforce the desired configuration of a Windows service using a DSC configuration document.

Properties

The following list describes the properties for the resource.

  • Key properties: The following properties uniquely identify an instance. If two instances of a resource have the same values for their key properties, the instances are conflicting. For more information about key properties, see the "Key resource properties" section in DSC resource properties.

    • name - The name of the service in the Service Control Manager.

  • Instance properties: The following properties are optional. They define the desired state for an instance of the resource.

    • dependencies - A list of service names that this service depends on.
    • description - A description of the service.
    • displayName - The display name of the service shown in the Services console.
    • errorControl - The error control level for the service.
    • executablePath - The fully qualified path to the service binary.
    • logonAccount - The account under which the service runs.
    • startType - The start type of the service.
    • status - The current or desired status of the service.

  • Read-only properties: The resource returns the following properties, but they aren't configurable. For more information about read-only properties, see the "Read-only resource properties" section in DSC resource properties.

    • _exist - Indicates whether the service exists in the Service Control Manager.

name

Expand for name property metadata 
Type        : string
IsRequired  : false
IsKey       : true
IsReadOnly  : false
IsWriteOnly : false

The service key name as registered in the Service Control Manager. This is the short internal name used to identify the service. For example, wuauserv for Windows Update. This value is case-insensitive.

When performing a Get operation you may supply either name or displayName (or both) to identify the service. For Set operations you must supply name.

displayName

Expand for displayName property metadata 
Type        : string
IsRequired  : false
IsKey       : false
IsReadOnly  : false
IsWriteOnly : false

The friendly display name of the service shown in the Windows Services console — for example, Windows Update. You can define displayName instead of (or alongside) name in a Get operation to locate a service when you don't know its key name. If both are provided, DSC verifies that they refer to the same service and returns an error if they don't match.

description

Expand for description property metadata 
Type        : string
IsRequired  : false
IsKey       : false
IsReadOnly  : false
IsWriteOnly : false

A human-readable description of the service. Setting this property updates the description shown in the Services console and the Description field in the SCM database.

_exist

Expand for _exist property metadata 
Type        : boolean
IsRequired  : false
IsKey       : false
IsReadOnly  : true
IsWriteOnly : false

Indicates whether the service exists in the Service Control Manager. This property is returned by the resource and cannot be set. A value of true means the service is registered; false means it is not found.

status

Expand for status property metadata 
Type        : string
IsRequired  : false
IsKey       : false
IsReadOnly  : false
IsWriteOnly : false
Enum        : [Running, Stopped, Paused, StartPending, StopPending, PausePending, ContinuePending]

The runtime status of the service. When used as desired state in a Set operation, only the following values are valid:

Value Effect
Running DSC starts the service if it is not running.
Stopped DSC stops the service if it is not stopped.
Paused DSC pauses the service if it is not paused.

The following additional values may be returned by a Get or Export operation to describe a transient state, but they must not be used as desired-state values:

  • StartPending
  • StopPending
  • PausePending
  • ContinuePending

startType

Expand for startType property metadata 
Type        : string
IsRequired  : false
IsKey       : false
IsReadOnly  : false
IsWriteOnly : false
Enum        : [Automatic, AutomaticDelayedStart, Manual, Disabled]

Defines how the service is started. The following values are valid:

Value Description
Automatic The service is started automatically by the SCM at system startup.
AutomaticDelayedStart The service starts automatically after other auto-start services have initialized.
Manual The service is started only when explicitly requested (e.g., via sc start).
Disabled The service cannot be started.

executablePath

Expand for executablePath property metadata 
Type        : string
IsRequired  : false
IsKey       : false
IsReadOnly  : false
IsWriteOnly : false

The fully qualified path to the service binary, including any command-line arguments registered with the SCM. For example, C:\Windows\System32\svchost.exe -k netsvcs.

logonAccount

Expand for logonAccount property metadata 
Type        : string
IsRequired  : false
IsKey       : false
IsReadOnly  : false
IsWriteOnly : false

The account under which the service process runs. Only the following built-in service accounts are supported by the Set operation:

  • LocalSystem
  • NT AUTHORITY\LocalService
  • NT AUTHORITY\NetworkService

Specifying a regular user account causes the Set operation to return an error.

errorControl

Expand for errorControl property metadata 
Type        : string
IsRequired  : false
IsKey       : false
IsReadOnly  : false
IsWriteOnly : false
Enum        : [Ignore, Normal, Severe, Critical]

Controls the action taken if the service fails to start during system boot. The following values are valid:

Value Description
Ignore The error is logged and startup continues.
Normal The error is logged, a message box is displayed, and startup continues.
Severe The error is logged. If the last-known-good configuration is in use, startup continues; otherwise the system restarts with the last-known-good configuration.
Critical The error is logged. If the last-known-good configuration is in use, startup fails; otherwise the system restarts with the last-known-good configuration.

dependencies

Expand for dependencies property metadata 
Type              : array
ItemsType         : string
ItemsMustBeUnique : false
IsRequired        : false
IsKey             : false
IsReadOnly        : false
IsWriteOnly       : false

A list of service key names that this service depends on. The SCM will not start the service until all listed dependencies are running. Setting this property replaces the existing dependency list for the service.

Instance validating schema

The following snippet contains the JSON Schema that validates an instance of the resource.

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string"
    },
    "displayName": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "_exist": {
      "type": "boolean",
      "readOnly": true
    },
    "status": {
      "type": "string",
      "enum": [
        "Running", "Stopped", "Paused",
        "StartPending", "StopPending", "PausePending", "ContinuePending"
      ]
    },
    "startType": {
      "type": "string",
      "enum": ["Automatic", "AutomaticDelayedStart", "Manual", "Disabled"]
    },
    "executablePath": {
      "type": "string"
    },
    "logonAccount": {
      "type": "string"
    },
    "errorControl": {
      "type": "string",
      "enum": ["Ignore", "Normal", "Severe", "Critical"]
    },
    "dependencies": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Exit codes

The resource returns the following exit codes from operations:

  • 0 - Success
  • 1 - Invalid arguments
  • 2 - Invalid input
  • 3 - Service error

Exit code 0

Indicates the resource operation completed without errors.

Exit code 1

Indicates the resource operation failed because required arguments were missing or the operation name was not recognized.

Exit code 2

Indicates the resource operation failed because the JSON input could not be deserialized into a valid WindowsService instance.

Exit code 3

Indicates the resource operation failed due to an error raised by the Windows Service Control Manager API, or the result could not be serialized.

See also

  • Last updated on