Getting started with DSC 3.0 – Part 3: Capturing the current state with dsc config export

In the previous post we wrote a configuration document for a single service by hand. That works when you know exactly what you want to manage.

But what if you inherit a machine and have no idea what's configured on it? Or you have one server that works fine and you want the others to look the same? Writing the document from scratch is slow and you will forget things.

That's what dsc config export is for.

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
• Getting started with DSC 3.0 – Part 3: Capturing the current state with dsc config export (this post)

What does export do?

The export command inspects the system and generates a configuration document that contains every instance of the resources you ask for. The result is a normal configuration document, so you can use it with get, test and set like any other.

It's the reverse of what we did in Part 2. Instead of describing the state and applying it, you read the state and turn it into a description.

Step 1: Tell DSC what to export

The input document only lists the resource types you want. Save this as export.dsc.yaml:

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: All services
  type: Microsoft.Windows/Service
  properties: {}

Remark: DSC ignores any properties you specify here. It only looks at the resource type. The document must still be valid, so keep properties in place.

Step 2: Run it

dsc config export --file export.dsc.yaml

The output is a new configuration document with one resource instance for every service registered on the machine, each with its full configuration: start type, status, logon account, executable path and so on.

Remark: in the console, DSC shows the result as YAML. If you redirect or capture the output, DSC switches to JSON. Use --output-format (or -o) to choose explicitly: json, pretty-json or yaml.

Step 3: Save it

Let's put the result in a file, as YAML:

dsc config export --file export.dsc.yaml --output-format yaml > baseline.dsc.yaml

Without the explicit format, you would get JSON in that file.

Remark: I had to change the name of the exported resources as the exported names were invalid:

You now have a snapshot of the machine. That's useful on its own: keep it in source control and you can compare it with a later export.

Step 4: Turn the export into a desired state

A full export is a description of what is, not what you want. You probably don't want to enforce the state of every service on the machine.

So treat the export as raw material:

• Remove the instances you don't care about
• Check the values you keep. status is the state at the moment of the export, for example
• Replace hardcoded values with parameters, like we did in Part 2

Because the export is a configuration document, you can also filter it before saving. With PowerShell:

$export = dsc config export --file export.dsc.yaml | ConvertFrom-Json
$export.resources | Where-Object { $_.properties.startType -eq 'Automatic' }

That gives you the services that start automatically. Pick the ones that matter, put them in a document and use dsc config test and dsc config set as before.

The rules

• Only resources that support export can be used. Not every resource does.
• Each resource type can only be listed once in the input document. If you list a type twice, or a type that isn't exportable, DSC returns an error.
• The command only reads. It never changes anything on the system.

Tip: if you only want to export one resource type, you can skip the document and call the resource directly:

dsc resource export --resource Microsoft.Windows/Service

Same output, one command less.

Up to the next one!

More information

• dsc config export reference
• Microsoft.Windows/Service resource reference
• Resource manifest export property