Getting started with DSC 3.0 – Part 2: Managing a Windows service end to end

In the previous post we looked at what DSC is and what changed in 3.0. Time to put it to work.

A Windows service is a good first example. It's something most teams have, and it's easy to break without anybody noticing. Someone sets the start type to Manual while troubleshooting, forgets to put it back, and a few weeks later the service doesn't come up after a reboot.

Let's use DSC to describe the state we want and keep it that way.

Note: this post is part of a bigger series on Microsoft Desired State Configuration:

• Getting started with DSC 3.0 – Part 1: What is DSC and what changed?
• Getting started with DSC 3.0 – Part 2: Managing a Windows service end to end (this post)

What you need

• DSC v3.3 or later, because Microsoft.Windows/Service was added in that release
• A Windows machine
• An elevated terminal for the set operation

Check your version first:

dsc --version

Remark: the resource can only manage services that are already registered with the Service Control Manager. Creating a new service is out of scope here. For the demo I use the Print Spooler (Spooler), but a service of your own application works exactly the same.

Step 1: Look at the current state

Before writing any configuration, ask DSC what it sees. A single resource can be called directly with dsc resource get:

dsc resource get --resource Microsoft.Windows/Service --input '{ "name": "Spooler" }'

This returns the full configuration of the service: start type, status, logon account, executable path and more. Nothing is changed. It's a good way to discover which properties you can use.

Remark: the key property is name, the short internal name of the service (wuauserv, Spooler), not the display name you see in the Services console.

Step 2: Describe the desired state

Now it's time to create our first configuration document. Save this as service.dsc.yaml:

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
parameters:
  serviceName:
    type: string
    defaultValue: Spooler
  startType:
    type: string
    defaultValue: Automatic
    allowedValues:
    - Automatic
    - AutomaticDelayedStart
    - Manual
    - Disabled
resources:
- name: Managed service
  type: Microsoft.Windows/Service
  properties:
    name: "[parameters('serviceName')]"
    startType: "[parameters('startType')]"
    status: Running

Two things to notice:

• Parameters make the document reusable. The same file works for another service or another start type, without generating anything first.
• status accepts Running, Stopped and Paused as desired state. The ...Pending values you may see in the output are transient and can't be used here.

Step 3: Break it on purpose

To see DSC do something, we need drift. Let's create it ourselves by changing the startup type and stopping the service:

Set-Service -Name Spooler -StartupType Manual
Stop-Service -Name Spooler

Step 4: Test

dsc config test --file service.dsc.yaml

test compares the actual state with the document and changes nothing. 

Look for the inDesiredState value in the output. It should be false now.

Step 5: Apply

Time to fix it. Open an elevated terminal and run:

dsc config set --file service.dsc.yaml

Remark: without elevation, the set operation fails with an access-denied error from the Service Control Manager. get and test don't need it.

Run test again and inDesiredState is back to true. The service is running and starts automatically again.

Tip: don't want to change anything yet? Add --what-if to the set command and DSC shows what it would change without doing it.

Using different values

What if you want the same document for a different start type? That's what the parameters are for. Create params.yaml:

parameters:
  startType: AutomaticDelayedStart

And pass it to DSC:

dsc config --parameters-file params.yaml set --file service.dsc.yaml

Same document, different outcome.

One thing to keep in mind

DSC 3.0 has no Local Configuration Manager. Nobody is watching your service in the background. The state is only enforced when you run set, or when an orchestrator does it for you.

So, for real drift protection, you need something that calls DSC on a schedule, like a pipeline, a scheduled task or Azure Machine Configuration.

That's it!

More information

• Microsoft.Windows/Service resource reference
• Example: Configure a Windows service
• Announcing Microsoft Desired State Configuration v3.3.0