Declarative Configuration Management for Windows with DSC — Starting IaC with dsc.exe

The setup runbook for a new PC, the Excel sheet with the server build steps, the secret BAT file left behind by someone who has since left the company — in many shops, Windows configuration management still runs on “a document that describes the steps” and “a script that executes the steps”. The weakness of this approach is clear: the steps start drifting from reality the moment they are executed, and the script breaks on its second run.

On Linux and in the cloud, declarative IaC (Infrastructure as Code) such as Terraform and Ansible has become the norm. So what should you use to manage Windows clients and servers themselves with the same mindset? Microsoft’s answer is DSC (Desired State Configuration), and with Microsoft DSC v3 (dsc.exe), rewritten in 2025 as a command-line tool that does not depend on PowerShell, it has finally reached a form you can “just start using”.¹

Intended readers are developers and IT staff who manage the configuration of Windows clients and servers with runbooks and scripts and want to move to declarative management. Prerequisites are Windows 10/11 and DSC 3.0 or later, with basic PowerShell operation assumed as background knowledge. The difficulty is intermediate.

1. The Bottom Line First

With DSC you write the “desired state” in YAML, not the “steps to execute”. Resources take on detecting the difference from the current state (test) and applying it (set), so the same file is safe (idempotent) no matter how many times you run it, and the configuration becomes data you can review in Git. If you are starting now, Microsoft DSC v3 (dsc.exe) is the only choice.

The difference between a runbook script and a declarative configuration shows in how they break. A script that encodes steps stops with duplicate application or errors when you run it again against a machine that failed partway through or one that is already configured. A declarative configuration describes only the desired state, so no matter how many times you run it, and from whatever intermediate state, it converges on the same result.²

flowchart TB
    accTitle: Imperative runbook versus declarative configuration
    accDescr: An imperative script executes steps from the top, so re-running it causes duplicate application or a halt, whereas declarative DSC declares the desired state and applies only the difference, so it converges on the same state no matter how many times it runs
    imp["Imperative: write the steps (BAT, runbook)"] --> i1["Execute from the top"]
    i1 --> i2["Re-run: duplicate application, errors"]
    dec["Declarative: write the state (DSC)"] --> d1["Detect the difference from the current state"]
    d1 --> d2["Apply only the difference, safe every time"]

Figure 1: An imperative script is sensitive to “how many times it has run”; a declarative configuration converges on the same state however many times it runs.

In the diagram a solid line marks a relation that always holds and a dashed line marks a conditional one (the conditions are given per relation on the detail page). The full list of relations (17 in total, with evidence and certainty) and the definitions of the main concepts are collected on the knowledge map detail page (in Japanese). Data: JSON-LD / Turtle

2. Untangling the Confusion Around the Name “DSC” — Four Lineages

The first thing that trips you up when learning DSC is not the technology itself but the confusion in the search results. Four lineages of mechanisms carry the name “DSC”, and they differ in how you write them, how you run them, and what they are compatible with.³

Microsoft DSC v3 is not simply an update of the earlier PowerShell DSC (PSDSC); it is a separate product, rewritten with the dependency on PowerShell cut away. Configurations become JSON/YAML data instead of PowerShell scripts, resources can be implemented in any language, and it runs the same way on Linux, macOS, and Windows.¹

flowchart TB
    accTitle: Lineage of the four DSC generations
    accDescr: From PSDSC v1.1 built into Windows PowerShell 5.1 derive PSDSC v2 for PowerShell 7 and the PSDSC v3 preview for Machine Configuration, while Microsoft DSC v3, rewritten separately without a PowerShell dependency, is the current mainline
    v11["PSDSC v1.1 (built into WinPS 5.1)"] --> v2["PSDSC v2 (PowerShell 7)"]
    v2 --> v3ps["PSDSC v3 preview"]
    v11 -.->|"rewrite"| dsc3["Microsoft DSC v3 (dsc.exe)"]
    v3ps --> mc["Azure Machine Configuration"]
    dsc3 --> now["The subject of this article"]

Figure 2: Searching for “DSC” returns information from all four lineages mixed together. Telling which lineage an article or document is about is the first thing to do.

From here on, “DSC” in this article means Microsoft DSC v3. That assets from the older generations are not wasted is covered later (Section 6).

3. What “Declarative” Means — get, test, set, and Idempotency

The central concept in DSC is the resource. A resource provides the operations of retrieving state (Get), evaluating it (Test), and applying it (Set) for one kind of configuration target, such as “registry value”, “Windows feature”, or “environment variable”. Every resource implements Get. For resources that do not implement Test, DSC stands in with a synthetic test that compares the retrieved result against the declaration. Set is implemented only by resources that can enforce a state; read-only resources such as OS information do not have it.⁴ The user leaves “how to configure it” to the resource and writes only “what should be in what state” as data.

This division of labor is what produces idempotency. When a configuration document is applied (dsc config set), DSC first tests each instance and calls set only on those that are not in the desired state. That is why applying the same configuration any number of times is safe. Note one difference: when you run dsc resource set on a single resource, set is always called, and whether a test runs beforehand depends on the resource’s implementation (implementsPretest).⁵

flowchart TB
    accTitle: The convergence loop of get, test, and set
    accDescr: test compares the desired state written in the configuration document with the current state, nothing happens if there is no difference, and if there is one, set applies only the difference and get confirms the result, an idempotent flow of convergence
    doc["Configuration document (desired state)"] --> test["test: compare with the current state"]
    test -->|"no difference"| ok["Do nothing (idempotent)"]
    test -->|"difference"| set["set: apply only the difference"]
    set --> get["get: confirm the resulting state"]

Figure 3: Applying DSC is a “compare first, then change only what is needed” loop, which frees you from the notion of run count.

Let us look at the difference from an imperative script in code. Take “put this value in the registry”: in a script you write out the existence check, the creation, and the update yourself, each as its own branch.

# Imperative: write the "steps". You manage every branch and every ordering yourself
$path = 'HKCU:\Software\MyCompany\App'
if (-not (Test-Path $path)) {
    New-Item -Path $path -Force | Out-Null
}
Set-ItemProperty -Path $path -Name 'Mode' -Value 'standard'

In DSC you write the same thing as a declaration of the “desired state”. There is no existence check and no branching.

# Declarative: write the "state". Creating and fixing are the resource's job
- name: App operating mode
  type: Microsoft.Windows/Registry
  properties:
    keyPath: HKCU\Software\MyCompany\App
    valueName: Mode
    valueData:
      String: standard

4. Install dsc.exe and Call Resources One at a Time

There are two ways to install DSC. Extract the archive from the GitHub release and add it to PATH, or, on Windows, install it with winget from the Microsoft Store source.¹

# Search for and install the stable release from the Microsoft Store source
winget search DesiredStateConfiguration --source msstore
winget install --id 9NVTPZWRC6KQ --source msstore

Once it is installed, first list the resources available on the local machine.

dsc resource list

Before writing a configuration document, you can also call resources one at a time on their own. Being able to “try things small” is what makes v3 easy to learn.⁶

# Retrieve the current state (get)
dsc resource get --resource Microsoft.Windows/Registry `
  --input '{"keyPath":"HKCU\\Software\\MyCompany\\App","valueName":"Mode"}'

# Evaluate whether it is in the desired state (test) — makes no changes at all
dsc resource test --resource Microsoft.Windows/Registry `
  --input '{"keyPath":"HKCU\\Software\\MyCompany\\App","valueName":"Mode","valueData":{"String":"standard"}}'

flowchart TB
    accTitle: The four operations of the dsc resource command
    accDescr: Under the dsc resource command hang four operations, list to enumerate resources, get to retrieve the current state, test to evaluate the desired state without changes, and set to apply the state (only for resources that implement Set)
    cli["dsc resource command"] --> l["list: enumerate resources"]
    cli --> g["get: retrieve the current state"]
    cli --> t["test: evaluate only, no changes"]
    cli --> s["set: apply (resources that support Set)"]

Figure 4: Resources can be called on their own without writing a configuration document. Starting with observation, using only get and test, is the safe entry route.

Operations that make changes through set, and resources that handle HKLM or system settings, require administrator privileges. It is safest to start experimenting with examples whose write target is under the user’s own scope (such as HKCU).

5. The Configuration Document — Writing the “Desired State” in YAML

A configuration document declares several resources together. It is written in YAML or JSON and defines, at minimum, the two properties $schema and resources. Each resource instance has a name (a display name unique within the document), a type (the fully qualified resource name), and properties (the desired state).²

# standard-pc.dsc.config.yaml — the desired state of a standard client PC
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
parameters:
  appMode:
    type: string
    defaultValue: standard
resources:
  - name: App operating mode
    type: Microsoft.Windows/Registry
    properties:
      keyPath: HKCU\Software\MyCompany\App
      valueName: Mode
      valueData:
        String: "[parameters('appMode')]"

With parameters and variables, differences between environments (per-department setting values, for example) can be expressed in a single document. The expression syntax is a subset of the ARM template functions.²

flowchart TB
    accTitle: Structure of a configuration document
    accDescr: A configuration document consists of a schema that identifies the document schema, parameters and variables that absorb environment differences, and a resources array of resource instances, each of which has name, type, and properties
    docroot["Configuration document (YAML / JSON)"] --> sch["$schema: URI of the document schema"]
    docroot --> par["parameters / variables"]
    docroot --> res["resources: array of instances"]
    res --> inst["name, type, properties"]
    par -.-> inst

Figure 5: A configuration document is straightforward data, nothing more than “schema + parameters + resource declarations”; it is not a program.

Always put “observation” before applying. dsc config test reports whether there are differences without making changes, and dsc config set --what-if shows a prediction of “what would change if this were run”.⁷

# 1. Check whether there are differences (no changes)
dsc config test --file .\standard-pc.dsc.config.yaml

# 2. Show a prediction of what applying would change (no changes)
dsc config set --file .\standard-pc.dsc.config.yaml --what-if

# 3. Apply once you are satisfied
dsc config set --file .\standard-pc.dsc.config.yaml

# 4. Confirm the state after applying
dsc config get --file .\standard-pc.dsc.config.yaml

There is also an entry point in the reverse direction. For the resources listed in the input document passed with --file (only those that support export), dsc config export generates a configuration document containing every instance on the system and writes it to standard output. It can serve as the starting point for writing down the current state of an existing environment.⁸

# Pass an input document listing the target resources and save the current configuration document
dsc config export --file .\export-targets.dsc.config.yaml > .\current-state.dsc.config.yaml

flowchart TB
    accTitle: The four steps of safe application
    accDescr: Check for differences with dsc config test, which makes no changes, preview the changes with the what-if option of dsc config set, apply with set once satisfied, and confirm the result with get, in that safe order
    t["dsc config test (check for differences)"] --> w["set --what-if (predict the changes)"]
    w --> s["dsc config set (apply)"]
    s --> g["dsc config get (confirm the result)"]

Figure 6: As long as you keep the order “observe, predict, apply, confirm”, applying a declarative configuration carries none of the fear of a one-shot gamble.

That a configuration document is data, not a program, is its greatest operational advantage. “What should be configured on this machine” can be reviewed as a YAML diff, and the change history is, as it stands, the change history of the configuration.

6. Reusing Existing Assets — Adapters for PSDSC Resources and WinGet Configuration

Hearing that “v3 is a separate product” makes you worry about past assets, but DSC v3 can call the older-generation PSDSC resources through a mechanism called adapter resources. Under the current names in DSC 3.2 and later, Microsoft.Adapter/PowerShell serves the class-based resources for PowerShell 7 and Microsoft.Adapter/WindowsPowerShell serves the MOF-based and script-based resources for Windows PowerShell 5.1 (before that they were named Microsoft.DSC/PowerShell and Microsoft.Windows/WindowsPowerShell).⁹ The ecosystem of PSDSC resources accumulated over many years is reachable directly from a v3 configuration document.

The other connection point is WinGet Configuration. The .winget files introduced in the PC provisioning article use DSC v3 directly as their processor from the v3 schema (WinGet 1.11 and later) onward. When you specify dscv3 as the processor in the configuration file’s metadata, the body of the document is a DSC v3 configuration document itself.¹⁰

# WinGet Configuration v3 — the body is a DSC v3 configuration document
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
metadata:
  winget:
    processor:
      identifier: dscv3
resources:
  - name: App operating mode
    type: Microsoft.Windows/Registry
    properties:
      keyPath: HKCU\Software\MyCompany\App
      valueName: Mode
      valueData:
        String: standard

There is one caveat. An existing v2-format file (the format with properties.configurationVersion: 0.2.0 and the resources placed under properties) does not run as is under the dscv3 processor. v2 files keep working with the previous processor, but to put them on DSC v3 you migrate the format by following the official conversion guide (“Convert to v3” in the samples repository).¹⁰

flowchart TB
    accTitle: The layered structure centered on DSC v3
    accDescr: Orchestration layers such as winget configure and Azure Machine Configuration call DSC v3, and DSC v3 calls native resources directly and existing PSDSC resources through adapter resources
    orch["winget configure, Machine Configuration"] --> dsc["dsc.exe (DSC v3)"]
    dsc --> native["Native resources (Registry etc.)"]
    dsc --> adapter["Adapter resources"]
    adapter --> psdsc["Existing PSDSC resources (PowerShell assets)"]

Figure 7: DSC v3 is a standalone tool and, at the same time, the common foundation beneath higher-level tools such as winget and Azure. Existing PSDSC assets hang below the adapter.

In other words, the knowledge and configurations you write for v3 work with dsc.exe on your own machine, with winget configure in provisioning, and with Machine Configuration in cloud management. This is not relearning; the paths join up.¹

7. Putting It into Operation — Manage in Git and Detect Drift

The place to keep configuration documents is a Git repository. Configuration changes then follow the same flow as software development: review in a pull request, merge, apply. The very notion of a runbook that nobody updated disappears.

The challenge after applying is configuration drift (someone changes a setting by hand, and the machine slides away from the desired state). In DSC, drift detection is simply running dsc config test on a schedule. Because test makes no changes, detection and remediation can be separated, which is an important property. The safe operating pattern is to automate detection first, and to remediate (set) only after checking what the differences are.

# For scheduled runs: distinguish a failure of test itself, per-resource errors, and drift, and exit non-zero for all of them
$json = dsc config test --file C:\config\standard-pc.dsc.config.yaml
if ($LASTEXITCODE -ne 0 -or -not $json) {
    Write-Error "dsc config test itself failed to run (exit code: $LASTEXITCODE)"
    exit 2
}
$result = $json | ConvertFrom-Json
if ($result.hadErrors) {
    # Document validation failed or some resource exited non-zero. The check did not complete, so do not report healthy
    Write-Error "Checking some resources ended in errors. Inspect messages"
    exit 2
}
if ($result.results.result.inDesiredState -contains $false) {
    Write-Error "Configuration drift detected"
    exit 1
}

For the scheduling infrastructure, Task Scheduler works on clients (the design of unattended execution is covered in a separate article) and CI runners work for server fleets. For organizations that have consolidated management in Azure, Machine Configuration is the managed orchestration service that audits and applies configuration to Azure VMs and, through Azure Arc, to on-premises servers.¹¹

flowchart TB
    accTitle: The operational cycle of configuration management starting from Git
    accDescr: Configuration documents kept in a Git repository are reviewed in a pull request before being applied, periodic test runs from Task Scheduler or CI detect drift, and after inspecting the difference the cycle returns to remediation or to updating the configuration
    git["Git repository (configuration documents)"] --> pr["Changes reviewed in pull requests"]
    pr --> apply["Apply with dsc config set"]
    apply --> sched["Scheduled run: dsc config test"]
    sched -->|"drift detected"| judge["Inspect the difference and decide"]
    judge -.->|"configuration is right"| fix["Remediate with set"]
    judge -.->|"reality is right"| git

Figure 8: Handling drift is not only “remediation”. If the change made in the field is the right one, fixing the configuration document and merging it is the proper practice of declarative management.

The branch at the lower right of Figure 8 is easy to overlook. Drift is not always “bad”; sometimes it just means a change that was needed in the field has not been reflected in the configuration. In that case, rather than reverting the machine, update the configuration document to match reality. As long as you keep the discipline that the source of truth is always the declaration in Git, management does not break whichever way you go.

8. Constraints and Pitfalls

Here, honestly, are the constraints you should know before adopting it.

There is no LCM. The LCM (Local Configuration Manager) in v1.1 was a resident agent that held the configuration and performed periodic application and automatic remediation. v3 is “a command that runs only when called” and does not stay resident as a service.¹ If you need continuous enforcement, you have to choose the execution infrastructure yourself (Task Scheduler, CI, Machine Configuration), as in the previous section. This is not a regression but a design change that opens “how it gets run” to modern tooling; still, it is disorienting if you arrive with the mindset of v1.1 pull-server operation.

Handling administrator privileges. set on resources that affect the whole machine (HKLM, Windows features, and so on) requires elevation, and using Windows PowerShell PSDSC resources through the adapter also assumes running as administrator.⁶ Separating per-user settings from per-machine settings at the configuration-document stage makes designing the execution context easier.

Do not write secrets into the configuration. Configuration documents are data that goes into Git. Do not write passwords or API keys into them directly; parameterize them and pass them at run time.

Read other people’s configuration files before running them. A configuration document has the power to change the system through resources. Before applying a .winget file or configuration document obtained from a public repository, check its contents and the trustworthiness of the resources it references. This is an operational must that the official documentation, too, warns about explicitly.¹²

flowchart TB
    accTitle: The resident LCM of v1.1 versus the command model of v3
    accDescr: In PSDSC v1.1 a resident LCM held the configuration and handled periodic pull and automatic remediation, whereas DSC v3 is only started as a command, so you choose and prepare the scheduling infrastructure yourself from Task Scheduler, CI, and Machine Configuration
    v1["PSDSC v1.1: resident LCM"] --> pull["Holds the configuration, periodic pull, auto-remediation"]
    v3["DSC v3: command invocation only"] --> push["You provide the execution infrastructure"]
    push -.-> ex["Task Scheduler, CI, Machine Configuration"]

Figure 9: In v3 there is no “someone who remembers the configuration and fixes it on their own”. Whether you take that as an inconvenience or as regaining control over execution is where the design decision lies.

9. Summary — Replacing the Runbook with a Repository

• If you are starting declarative IaC for Windows now, use Microsoft DSC v3 (dsc.exe). Of the four lineages called “DSC”, always be aware which one the information you are reading is about.³
• DSC writes the “desired state”, not the “steps”, in YAML/JSON, and test (compare) and set (apply the difference) guarantee idempotent convergence. The safe flow is to start with observation via dsc resource get/test, check the impact with --what-if, and then apply.⁷
• Existing PSDSC resources join the v3 world through adapters, and .winget provisioning assets through the WinGet Configuration v3 schema (v2-format files need a format migration following the conversion guide).⁹¹⁰
• v3 has no LCM. The backbone of operation is to keep the source of truth in Git, detect drift with scheduled runs of dsc config test, and follow the discipline “if the configuration is right, remediate; if reality is right, update the configuration”.

The fate of a runbook was to drift from reality from the moment it was written. Declarative configuration management turns that drift into a “detectable difference”. Start by writing a handful of your own machine’s settings into a configuration document and running dsc config test. You should get a feel for how the runbook turns into a repository.

Related Articles

• Automating PC Provisioning With winget + PowerShell — Making the Runbook Executable
• Should That Batch File Move to PowerShell? — Auditing cmd/bat Assets and Making the Migration Call
• When Task Scheduler Tasks Don’t Run or Exit with 0x1 — Isolating the Cause and Designing for Reliable Operation
• From Group Policy to Intune — A Device-Management Migration Guide for Small and Medium Businesses
• Windows Update Management After WSUS Deprecation

Related Consulting Areas

KomuraSoft LLC supports migrating the configuration of Windows clients and servers to declarative management, automating provisioning and in-house standard environments, and making person-dependent runbooks executable.

• Technical Consulting & Design Review
• Maintenance & Modernization of Existing Windows Software
• Legacy Asset Reuse & Migration Support
• Contact Us

References

Related Articles

Recent articles sharing the same tags. Deepen your understanding with closely related topics.

Related Topics

These topic pages place the article in a broader service and decision context.

Where This Topic Connects

This article connects naturally to the following service pages.

Frequently Asked Questions

Common questions about the topic of this article.

There seem to be several versions of DSC. Which one should I use?

If you are starting declarative configuration management now, use Microsoft DSC v3 (dsc.exe). There are four lineages of DSC: PSDSC v1.1 built into Windows PowerShell 5.1, PSDSC v2 as a module for PowerShell 7, PSDSC v3 (preview) used for the Linux support of Azure Machine Configuration, and Microsoft DSC v3, rewritten as a standalone command that does not depend on PowerShell. v3 is cross-platform, writes configuration as YAML/JSON data rather than PowerShell scripts, and can reuse existing PSDSC resources through adapters. When searching, adding "DSC v3" or "dsc.exe" makes it easier to separate the results from older-generation material.

What is the difference between DSC v3 and a runbook script (BAT or PowerShell)?

A runbook script describes "the steps to execute", so you have to build idempotency in yourself to avoid duplicate application or errors on the second run. DSC writes the "desired state" as data, and resources take on the comparison with the current state (test) and the application of the difference (set). No matter how many times you run the same configuration document, it does nothing to items that are already in the desired state, so you can distribute and re-run it without worrying about the run count. And because the configuration is YAML data, diff reviews and version history in Git are far easier than with scripts.

Will my existing PowerShell DSC resources and WinGet Configuration assets be wasted?

No. DSC v3 can call existing class-based and MOF-based PSDSC resources through adapter resources (Microsoft.Adapter/PowerShell and Microsoft.Adapter/WindowsPowerShell in DSC 3.2 and later; Microsoft.DSC/PowerShell and Microsoft.Windows/WindowsPowerShell before that). WinGet Configuration, from its v3 schema (WinGet 1.11 and later), uses DSC v3 as its processor. Existing v2-format .winget files keep running on the previous processor, but to put them on the DSC v3 processor you need to convert them to the v3 format by following the official conversion guide.

How do I enforce a configuration "continuously" with DSC v3?

DSC v3 itself is a tool started as a command; it has no resident agent or automatic-remediation mechanism like the LCM (Local Configuration Manager) of v1.1. If you need continuous application and auditing, either build your own drift detection by running dsc config test periodically from Task Scheduler or CI, or put it on an orchestration layer such as Azure Machine Configuration (which can also cover on-premises servers through Azure Arc).

I am nervous about running dsc config set straight away. Can I check the impact beforehand?

Yes. Running dsc config test shows which resource instances are not in the desired state, without making changes. In addition, dsc config set has a --what-if option that shows a prediction of "what would change, and how, if this were run" without actually changing anything. Check the differences with test and --what-if first, and run set only once you are satisfied; that sequence is safe.

Author Profile

Profile page for the article author.

Go Komura

Representative of KomuraSoft LLC

Focused on Windows software development, technical consulting, and investigations into failures that are difficult to reproduce.