Edit

Configure a Windows service

This example shows how you can use the Microsoft.Windows/Service resource in a DSC configuration document to enforce the desired configuration and runtime status of multiple Windows services.

Important

Set operations for this resource require an elevated (administrator) process context. Run your terminal or PowerShell session as Administrator before using dsc config set.

Definition

The configuration document for this example defines two instances of the Service resource.

The first instance ensures that the Print Spooler service (Spooler) is stopped and configured for manual start. The second instance ensures that the Windows Time service (W32Time) is running and configured to start automatically.

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Ensure Print Spooler is stopped and set to manual start
    type: Microsoft.Windows/Service
    properties:
      name: Spooler
      status: Stopped
      startType: Manual
  - name: Ensure Windows Time service is running
    type: Microsoft.Windows/Service
    properties:
      name: W32Time
      status: Running
      startType: Automatic

Copy the configuration document and save it as service.config.dsc.yaml.

Setup

The output in this example assumes that the system has the Spooler service stopped with a manual startup and the W32Time service stopped with an automatic startup. You can set the system to this starting state with the following commands:

Set-Service -Name Spooler  -StartupType Manual    -Status Stopped
Set-Service -Name W32Time  -StartupType Automatic -Status Stopped

Test the configuration

To see whether the system is already in the desired state, use the dsc config test command.

dsc config test --file ./service.config.dsc.yaml

executionInformation:
  # Elided for brevity
metadata:
  # Elided for brevity
results:
- executionInformation:
    duration: PT0.1113118S
  metadata:
    Microsoft.DSC:
      duration: PT0.1113118S
  name: Ensure Print Spooler is stopped and set to manual start
  type: Microsoft.Windows/Service
  result:
    desiredState:
      name: Spooler
      status: Stopped
      startType: Manual
    actualState:
      name: Spooler
      displayName: Print Spooler
      description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers.
      _exist: true
      status: Stopped
      startType: Manual
      executablePath: C:\Windows\System32\spoolsv.exe
      logonAccount: LocalSystem
      errorControl: Normal
      dependencies:
      - RPCSS
    inDesiredState: true
    differingProperties: []
- executionInformation:
    duration: PT0.0353328S
  metadata:
    Microsoft.DSC:
      duration: PT0.0353328S
  name: Ensure Windows Time service is running
  type: Microsoft.Windows/Service
  result:
    desiredState:
      name: W32Time
      status: Running
      startType: Automatic
    actualState:
      name: W32Time
      displayName: Windows Time
      description: Maintains date and time synchronization on all clients and servers in the network. If this service is stopped, date and time synchronization will be unavailable. If this service is disabled, any services that explicitly depend on it will fail to start.
      _exist: true
      status: Stopped
      startType: Automatic
      executablePath: C:\Windows\system32\svchost.exe -k LocalService
      logonAccount: NT AUTHORITY\LocalService
      errorControl: Normal
    inDesiredState: false
    differingProperties:
    - status
messages: []
hadErrors: false

The inDesiredState field for the first instance is true because the Print Spooler service is already Stopped with Manual start, so no change is required. The second instance is false: the Windows Time service exists and already has startType: Automatic, but its status is Stopped while the desired state requires Running. Only status is listed in differingProperties.

Set the configuration

To enforce the desired state, use the dsc config set command.

dsc config set --file ./service.config.dsc.yaml

executionInformation:
  # Elided for brevity
metadata:
  # Elided for brevity
results:
- executionInformation:
    duration: PT0.0924309S
  metadata:
    Microsoft.DSC:
      duration: PT0.0924309S
  name: Ensure Print Spooler is stopped and set to manual start
  type: Microsoft.Windows/Service
  result:
    beforeState:
      name: Spooler
      status: Stopped
      startType: Manual
    afterState:
      name: Spooler
      displayName: Print Spooler
      description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers.
      _exist: true
      status: Stopped
      startType: Manual
      executablePath: C:\Windows\System32\spoolsv.exe
      logonAccount: LocalSystem
      errorControl: Normal
      dependencies:
      - RPCSS
    changedProperties: null
- executionInformation:
    duration: PT0.3682548S
  metadata:
    Microsoft.DSC:
      duration: PT0.3682548S
  name: Ensure Windows Time service is running
  type: Microsoft.Windows/Service
  result:
    beforeState:
      name: W32Time
      displayName: Windows Time
      description: Maintains date and time synchronization on all clients and servers in the network. If this service is stopped, date and time synchronization will be unavailable. If this service is disabled, any services that explicitly depend on it will fail to start.
      _exist: true
      status: Stopped
      startType: Automatic
      executablePath: C:\Windows\system32\svchost.exe -k LocalService
      logonAccount: NT AUTHORITY\LocalService
      errorControl: Normal
    afterState:
      name: W32Time
      displayName: Windows Time
      description: Maintains date and time synchronization on all clients and servers in the network. If this service is stopped, date and time synchronization will be unavailable. If this service is disabled, any services that explicitly depend on it will fail to start.
      _exist: true
      status: Running
      startType: Automatic
      executablePath: C:\Windows\system32\svchost.exe -k LocalService
      logonAccount: NT AUTHORITY\LocalService
      errorControl: Normal
    changedProperties:
    - status
messages: []
hadErrors: false

The Print Spooler instance shows changedProperties: null because it was already in the desired state and DSC made no changes to it. The Windows Time instance lists only status in changedProperties because DSC only needed to start the service. The startType was already Automatic and required no update.

  • Last updated on