PowerShell Desired State Configuration

Desired State Configuration describes what a machine should look like and lets the platform make it so. You write a Configuration block with resources, each declaring a desired state rather than the steps to reach it.

Lesson 2 min read Windows PowerShell 5.1 and PowerShell 7

Documentation: Microsoft Learn

Written and tested by Dhrub Bharali · Updated 02 October 2026

Overview

The idea is worth understanding even if you use something else. A DSC resource is idempotent: applying it when the machine already matches does nothing. That is different from a script, which runs its commands regardless. Test-DscConfiguration answers whether a machine has drifted, which no imperative script gives you for free.

The state of DSC matters before you invest in it. DSC 1.1 is built into Windows and works with Windows PowerShell 5.1. DSC 3 is a separate, cross-platform reimplementation with a different model. Azure Automation DSC was retired in favour of Azure Machine Configuration. So examples you find may target any of three fairly different things, and checking which one you are reading is the first step.

Compiling a configuration produces a MOF file per node. Start-DscConfiguration applies it, Get-DscConfiguration reads current state, and Test-DscConfiguration compares.

If you are choosing today, weigh DSC against the configuration tooling you already run. Its value is drift detection and idempotence; if you have those elsewhere, DSC may not earn its complexity.

Inspect this example’s structure

Read the command and its supplied arguments. This example requires real PowerShell or its module; this diagram does not execute it.

$config = @'
Configuration WebServer {
    Node localhost {
        WindowsFeature IIS {
            Ensure = "Present"
            Name = "Web-Server"
        }
    }
}
'@
Write-Output $config

Stage 1$configPositional values or no named parameters

An example to inspect

Preview the example. Sign in for the full lesson and activities.

$config = @'
Configuration WebServer {
    Node localhost {
        WindowsFeature IIS {
            Ensure = "Present"
            Name = "Web-Server"
        }
    }
}
'@
Write-Output $config

What happens

This prints a minimal configuration using a here-string so you can read the structure without a DSC engine. Ensure = "Present" is the declarative part: it says what the outcome should be, not how to install anything. Applying it twice has the same result as applying it once, which is the property that makes DSC useful.

Worth remembering

Resources declare desired state and are idempotent.
Test-DscConfiguration detects drift, which scripts do not.
DSC 1.1, DSC 3 and Azure Machine Configuration are different things.
Compiling produces a MOF per node; Start-DscConfiguration applies it.

Primary documentation

Windows services and processes documentation

Try it

Illustrative output · values vary by environment

1PS> $config = @' Configuration WebServer { Node localhost { WindowsFeature IIS { Ensure = "Present" Name = "Web-Server" } } } '@

2PS> Write-Output $config

Example reader

Inspect this page's example

Fictional browser data when supported

Run supported commands against the practice data, or inspect the example without executing it.

$config = @'
Configuration WebServer {
    Node localhost {
        WindowsFeature IIS {
            Ensure = "Present"
            Name = "Web-Server"
        }
    }
}
'@
Write-Output $config

Ready to inspect.

Prints a minimal DSC configuration to show the declarative shape.

Show reference output