The essentials

Quick reference

One focused task per row. Jump to the related section for complete, working examples.

UseSyntaxExamples
Inspect standalone DSCdsc --versionView examples
Inspect legacy moduleGet-Module -ListAvailable PSDesiredStateConfiguration | Select-Object Name,Version,PathView examples
List DSC 3 resourcesdsc resource listView examples
Inspect resource schemadsc resource schema --resource Microsoft.DSC.Debug/EchoView examples
Read current statedsc config get --file .\server.dsc.yamlView examples
Test desired statedsc config test --file .\server.dsc.yamlView examples
Apply desired statedsc config set --file .\server.dsc.yamlView examples
Supply parameter datadsc config --parameters-file .\prod.parameters.yaml set ` --file .\server.dsc.yamlView examples
Inspect Windows LCMGet-DscLocalConfigurationManagerView examples
Test legacy configurationTest-DscConfiguration -Path .\Compiled -DetailedView examples
Apply compiled MOFStart-DscConfiguration -Path .\Compiled -Wait -VerboseView examples
Read last LCM runGet-DscConfigurationStatus -AllView examples
Parse a configuration script$null = ` [System.Management.Automation.Language.Parser]::ParseFile('.\Config.ps1',[ref]$null,[ref]$null)View examples
Recognize WhatIf boundaryGet-Command Start-DscConfiguration | Select-Object -ExpandProperty ParametersView examples
Export discoverable statedsc config export --file .\resources.yamlView examples
Read DSC operational eventsGet-WinEvent -LogName ` 'Microsoft-Windows-DSC/Operational' -MaxEvents 50View examples

Desired State Configuration makes machine state declarative and repeatable, but two distinct stacks now share the DSC name. Microsoft DSC 3 is a standalone, cross-platform command that consumes JSON or YAML and has no Local Configuration Manager. Windows PowerShell DSC 1.1 uses PowerShell configuration scripts, MOF documents, and the Windows LCM. Identify the engine and resource contract first, test before set, keep secrets out of documents and MOF, and stage every change with rollback evidence.

Step by step

Detailed examples

01

Choose the DSC engine deliberately

Microsoft DSC 3 is a standalone executable for Windows, Linux, and macOS. It accepts JSON or YAML configuration documents, discovers command resources on PATH, can adapt PowerShell resources, and runs only when invoked; it has no LCM service. Windows PowerShell DSC 1.1 ships with Windows PowerShell 5.1 and uses configuration scripts compiled to MOF for the LCM. PSDesiredStateConfiguration 2.x is separately installable for PowerShell 7. Do not assume documents, resources, scheduling, or security behavior transfer between these stacks.

Inventory both DSC surfaces without changing state
$Standalone = if (Get-Command dsc -ErrorAction SilentlyContinue) { dsc --version } else { 'not installed' }
$Legacy = Get-Module -ListAvailable PSDesiredStateConfiguration |
    Select-Object Name, Version, Path
[pscustomobject]@{ StandaloneDSC = $Standalone; PowerShellDSC = $Legacy }
Back to quick reference ↑
02

Discover resources and inspect their contracts

A resource name is not enough: pin or record its version, provider, schema, platform, and required privilege. DSC 3 discovers manifests on PATH and adapters may expose existing PowerShell resources. Capabilities show whether get, set, test, export, or other operations exist. Schema inspection prevents guessed property names and types. Resource installation changes the trusted code base and can introduce dependencies, so acquire modules or binaries through an approved repository and verify publisher provenance before production use.

Review a resource before authoring
dsc resource list
dsc resource schema --resource Microsoft.DSC.Debug/Echo
dsc resource get --resource Microsoft.DSC.Debug/Echo --input '{"text":"inventory"}'
Back to quick reference ↑
03

Get and test before enforcing

Use get to inventory actual state and test to compare it with desired state. Neither is a perfect preview of set: a flawed resource may have side effects, and test cannot predict every restart, lockout, or application consequence. Run under the same identity, architecture, environment, and resource versions intended for deployment. Capture structured output and exit status in the orchestration system, and treat validation errors or hadErrors as deployment failures rather than continuing blindly.

Audit a reviewed DSC 3 document
$Document = '.\server.dsc.yaml'
dsc config get --file $Document
if ($LASTEXITCODE -ne 0) { throw 'DSC get failed' }
dsc config test --file $Document
if ($LASTEXITCODE -ne 0) { throw 'DSC test failed' }
Back to quick reference ↑
04

Separate configuration from environment data

Parameter files let one reviewed document serve several environments without string substitution. Keep credentials and private keys out of configuration files, parameters, process arguments, logs, generated MOF, and source control; use a resource's supported secret-reference mechanism or the orchestrator's protected channel. DSC 3 validates before set and tests each resource, but set is still an operational mutation. Use a maintenance window, a canary, a backup, and a documented recovery path. DSC 3 has no general WhatIf mode.

Apply only after an explicit test gate
dsc config --parameters-file .\prod.parameters.yaml test --file .\server.dsc.yaml
if ($LASTEXITCODE -ne 0) { throw 'Desired-state test failed' }
# Run the following only in an approved change window:
# dsc config --parameters-file .\prod.parameters.yaml set --file .\server.dsc.yaml
Back to quick reference ↑
05

Understand the Windows Local Configuration Manager

The LCM is the legacy Windows agent that receives MOF, applies configuration, and can monitor or auto-correct drift according to meta-configuration. Get-DscLocalConfigurationManager and Test-DscConfiguration require Windows PowerShell DSC support and commonly require elevation or delegated remoting rights. LCM modes such as ApplyAndAutoCorrect can repeatedly undo emergency changes, so coordinate break-glass procedures. Changing LCM settings can affect scheduled enforcement and may restart services depending on resources; inspect the generated meta-MOF before applying it.

Read LCM posture and test a compiled node
$Lcm = Get-DscLocalConfigurationManager
$Lcm | Select-Object ConfigurationMode, RefreshMode, RebootNodeIfNeeded
Test-DscConfiguration -Path '.\Compiled' -Detailed
Back to quick reference ↑
06

Treat MOF compilation and application as separate trust steps

A PowerShell configuration block compiles a document; Start-DscConfiguration applies the resulting MOF. Compilation can execute PowerShell code, and MOF can expose sensitive values unless credential encryption is configured correctly with target certificates. Review both the source and compiled artifact. Applying normally requires elevation on the node or configured remoting authorization. A resource can request a reboot; RebootNodeIfNeeded controls LCM behavior, so never assume no restart merely because the command lacks a reboot switch.

Inspect, apply, and confirm a compiled configuration
Get-ChildItem -LiteralPath '.\Compiled' -Filter '*.mof' |
    Select-Object Name, Length, LastWriteTime
# Approved elevated maintenance window only:
# Start-DscConfiguration -Path '.\Compiled' -Wait -Verbose
Get-DscConfigurationStatus -All | Select-Object -First 5
Back to quick reference ↑
07

Validate syntax, idempotence, and blast radius

Parsing proves only PowerShell grammar. Compilation validates more of a legacy configuration, and test validates state, but none replaces staging. Run test, set, test again, then repeat set in a disposable environment to detect non-idempotent resources. Review which account executes, remote transport, file ACLs, required modules, supported Windows edition, and restart behavior. WhatIf support belongs to individual resource implementations, not to DSC as a universal transaction or rollback facility.

Parse a legacy configuration without executing it
$Tokens = $null
$Errors = $null
[void][System.Management.Automation.Language.Parser]::ParseFile(
    '.\Config.ps1', [ref]$Tokens, [ref]$Errors)
if ($Errors.Count) { $Errors | Format-List; throw 'Parse failed' }
Back to quick reference ↑
08

Operate DSC as privileged automation

Configuration engines frequently run with administrative or system authority. Restrict write access to documents, parameter files, resource packages, PATH directories, pull locations, certificates, and transcript or event data. Sign and version artifacts where policy requires it. Exported state can include hostnames, paths, and settings that are sensitive. DSC 3 has no background consistency agent, while legacy LCM does; schedule DSC 3 through an external orchestrator with locking and alerting, and monitor legacy LCM events plus configuration status for drift and failures.

Collect read-only operational evidence
Get-DscConfigurationStatus -All |
    Select-Object Status, StartDate, Type, RebootRequested
Get-WinEvent -LogName 'Microsoft-Windows-DSC/Operational' -MaxEvents 50 |
    Select-Object TimeCreated, Id, LevelDisplayName, Message
Back to quick reference ↑

Keep exploring

More Windows cheat sheets

Sources and further reading

References

Authoritative documentation used to verify and expand this cheat sheet.

  1. Microsoft LearnMicrosoft Desired State Configuration overviewlearn.microsoft.com
  2. Microsoft LearnGet started with DSClearn.microsoft.com
  3. Microsoft Learndsc config command referencelearn.microsoft.com
  4. Microsoft LearnPowerShell Desired State Configuration overviewlearn.microsoft.com
  5. Microsoft LearnGet-DscLocalConfigurationManagerlearn.microsoft.com
  6. Microsoft LearnStart-DscConfigurationlearn.microsoft.com

Help us improve

Found a typo or missing example?

Tell us what would make this cheat sheet clearer, more complete, or more useful.

Share feedback