DSC v3 Runbook & Cheatsheet
DSC v3 Runbook & Cheatsheet
DSC v3 is a ground-up rewrite: a standalone dsc executable, configuration documents in YAML/JSON, and resources in any language — no MOF, no LCM. Part one installs it and applies a first configuration; part two is the reference: the CLI, the config document, built-in resources, and adapters for your existing PowerShell DSC content.
The v3 model
| PSDSC 1.1 / 2.0 | DSC v3 | |
|---|---|---|
| Engine | LCM + MOF | dsc binary, no LCM |
| Config format | compiled MOF | YAML / JSON document |
| Resources | PowerShell only | Any language (+ PS via adapter) |
| Platform | Windows only | Windows + Linux |
| Scheduling | LCM built in | You bring it (task / orchestrator) |
The big shift There is no LCM, so nothing re-applies on its own. Enforcement and drift correction are something you schedule (Phase 7). In exchange, any tool that can run a command can drive DSC.
Windows (or Linux), winget to install, and PowerShell 7.2+ if you will use PowerShell-based resources. System changes need an elevated shell.
Server Core On Windows Server 2025, winget is only present with the Desktop Experience. On Core, download the release from GitHub instead.
Install
winget install --id Microsoft.DSC --exact
# PowerShell 7 is required for PowerShell-based resources
winget install --id Microsoft.PowerShell --exact
dsc --versionExplore resources
A resource is a unit of manageable state. Every resource ships a schema, so you never have to guess property names.
dsc resource list # everything discoverable dsc resource list "Microsoft.Windows/*" # filter by type # Read current state of a resource (no changes) dsc resource get --resource Microsoft/OSInfo # Learn a resource's exact properties dsc resource schema --resource Microsoft.Windows/Registry
Schema first dsc resource schema is the authoritative source for a resource’s properties — especially for the newer 3.2 built-ins (Service, Firewall, SSH), whose fields you should read rather than assume.
Write a configuration document
A config document is a list of resource instances and their desired state. Built-in resources run natively; classic PowerShell DSC resources run through an adapter.
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: # Native built-in resource - name: App registry key type: Microsoft.Windows/Registry properties: keyPath: HKLM\Software\bubim valueName: Installed valueData: String: "yes" # Classic PowerShell DSC resource via the adapter - name: IIS web server type: Microsoft.Windows/WindowsPowerShell properties: resources: - name: WebServer type: PSDesiredStateConfiguration/WindowsFeature properties: Name: Web-Server Ensure: Present
Ordering Add dependsOn: [“[resourceId(‘type’,’name’)]”] to a resource to make it wait for another. Without it, order is not guaranteed.
Test / preview
# Is the machine already in the desired state? (read-only) dsc config test --file baseline.dsc.yaml # Preview what a 'set' WOULD change, without changing anything dsc config set --file baseline.dsc.yaml --what-if
Two safety nets test reports drift without touching anything; –what-if (extended to individual resources in 3.2) shows the exact changes a real set would make.
Apply
dsc config set --file baseline.dsc.yaml
# Or feed the document from stdin
Get-Content baseline.dsc.yaml | dsc config setIdempotent set only changes what is out of state, so re-running is safe and cheap. That property is what makes scheduled re-apply (Phase 7) sound.
Reuse PowerShell DSC resources
# From a PowerShell 7 session Install-PSResource PSDesiredStateConfiguration Install-PSResource xWebAdministration # example community module # See the resources the adapter now exposes dsc resource list --adapter Microsoft.Windows/WindowsPowerShell
Two adapters Microsoft.Windows/WindowsPowerShell runs Windows PowerShell 5.1 (MOF-based) resources; Microsoft.DSC/PowerShell runs PowerShell 7 class-based resources. Existing DSC content keeps working under v3.
Schedule & operate
There is no LCM, so enforcement is a job you own. The simplest form is a Scheduled Task that re-applies the baseline.
$action = New-ScheduledTaskAction -Execute 'dsc' ` -Argument 'config set --file C:\dsc\baseline.dsc.yaml' $trigger = New-ScheduledTaskTrigger -Daily -At 3am Register-ScheduledTask -TaskName 'DSC-Baseline' ` -Action $action -Trigger $trigger ` -User 'SYSTEM' -RunLevel Highest
Fleet control plane For more than a box or two, drive dsc from winget Configuration (winget configure), Azure Machine Configuration, or an orchestrator you already run (Ansible, scheduled tasks pushed by GPO). v3 is deliberately unopinionated about this.
Verify & troubleshoot
dsc config get --file baseline.dsc.yaml # actual current state # Crank up diagnostics; JSON trace for a log pipeline dsc --trace-level debug config set --file baseline.dsc.yaml dsc --trace-level trace --trace-format json config test --file baseline.dsc.yaml
dsc command line
| Command | Does |
|---|---|
| dsc –version | Version of the dsc binary. |
| dsc resource list [filter] | Discover resources; –adapter / –tags to narrow. |
| dsc resource get –resource TYPE | Read current state of one resource. |
| dsc resource test –resource TYPE –file f | Compare actual vs desired for one resource. |
| dsc resource set –resource TYPE –file f | Enforce one resource. |
| dsc resource schema –resource TYPE | JSON schema (property reference) for a resource. |
| dsc config get –file doc.yaml | Actual state for every resource in a document. |
| dsc config test –file doc.yaml | Drift report for the whole document. |
| dsc config set –file doc.yaml | Enforce the whole document. |
| dsc config set –file doc.yaml –what-if | Preview changes without applying. |
| dsc config export –file doc.yaml | Capture current state as a document. |
Input & trace Pass state via –file, –input ‘{json}’, or stdin (cat doc.yaml | dsc config set). Diagnostics: –trace-level error|warn|info|debug|trace and –trace-format default|plaintext|json.
Configuration document
| Top-level key | Purpose |
|---|---|
| $schema | Document schema URL — pins the format version. |
| resources | The list of resource instances to manage. |
| parameters | Typed inputs, referenced as [parameters(‘x’)]. |
| variables | Computed values, referenced as [variables(‘x’)]. |
| metadata.Microsoft.DSC | Engine metadata — split into directives + executionInformation in 3.2. |
Each entry under resources:
| Resource key | Purpose |
|---|---|
| name | Unique instance name (used by resourceId). |
| type | Namespace/Name, e.g. Microsoft.Windows/Registry. |
| properties | Desired state, per the resource’s schema. |
| dependsOn | Ordering: [“[resourceId(‘type’,’name’)]”]. |
| metadata | Per-resource directives (e.g. _refreshEnv in 3.2). |
Built-in resources
| Type | Manages |
|---|---|
| Microsoft/OSInfo | Read OS facts (get / test). |
| Microsoft.Windows/Registry | Registry keys and values. |
| Microsoft.Windows/Service | Service state and startup type (3.2). |
| Microsoft.Windows/Firewall, SSH | Firewall rules, SSH settings (3.2) — check schema. |
| Microsoft.DSC.Debug/Echo | Echo input; testing and learning. |
| Microsoft.DSC/Assertion | Fail the config unless a nested resource is in state. |
| Microsoft.DSC/Group | Group resources into a nested unit. |
| Microsoft.DSC/Parallel | Run a group of resources in parallel. |
| Microsoft.DSC/Include | Pull in another configuration document. |
| Microsoft.DSC.Transitional/RunCommandOnSet | Run a command during set (escape hatch). |
Live list dsc resource list shows what is actually installed; built-ins evolve per release, so treat this as a starting map and confirm with dsc resource schema.
Adapters (PowerShell)
| Adapter | Runs |
|---|---|
| Microsoft.Windows/WindowsPowerShell | Windows PowerShell 5.1, MOF-based script/class resources. |
| Microsoft.DSC/PowerShell | PowerShell 7 class-based DSC resources. |
# Adapted resources nest under the adapter's 'resources' property
- name: Feature
type: Microsoft.Windows/WindowsPowerShell
properties:
resources:
- name: DotNet
type: PSDesiredStateConfiguration/WindowsFeature
properties:
Name: NET-Framework-45-Core
Ensure: PresentDiscover dsc resource list –adapter Microsoft.Windows/WindowsPowerShell lists every adapted resource available after you install its module.
Config functions
ARM-style expressions inside [ … ], evaluated when the document is processed.
| Function | Returns |
|---|---|
| parameters(‘n’) | Value of an input parameter. |
| variables(‘n’) | Value of a variable. |
| resourceId(‘type’,’name’) | Canonical id for dependsOn / reference. |
| reference(resourceId(…)) | Output properties of another resource. |
| envvar(‘NAME’) | An environment variable. |
| concat / createArray / if / base64 | String, array, conditional, encoding helpers. |
Author a command resource
A resource is just a program that speaks JSON on stdin/stdout, described by a manifest. Any language works.
{
"$schema": "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json",
"type": "bubim/AppState",
"version": "1.0.0",
"get": { "executable": "app-state", "args": ["get"] },
"set": { "executable": "app-state", "args": ["set"], "input": "stdin" },
"test": { "executable": "app-state", "args": ["test"], "input": "stdin" },
"schema": {
"command": { "executable": "app-state", "args": ["schema"] }
}
}Discovery Put the manifest on PATH (or under DSC_RESOURCE_PATH) and dsc resource list picks it up. Declare requireSecurityContext per operation (3.2) so DSC warns when get/test needs different privileges than set.
Optimize
| Area | Lever |
|---|---|
| Safety | Run config test or set –what-if before every real set. |
| Correctness | Read dsc resource schema instead of guessing property names. |
| Ordering | Be explicit with dependsOn + resourceId(); use Group / Parallel for structure and speed. |
| Reproducibility | Pin $schema and use resource version pinning (3.2) so configs are deterministic. |
| Automation | –trace-format json and JSON output feed straight into a pipeline or SIEM. |
| Privilege | Mind requireSecurityContext; only elevate the operations that need it. |
| Enforcement | No LCM: schedule set for enforcement, test for drift reporting. |
| Reuse | Adapt existing PowerShell DSC resources rather than rewriting them. |
References
| Resource | Use | Link |
|---|---|---|
| DSC docs | Official reference | learn.microsoft.com/powershell/dsc |
| PowerShell/DSC | Source, releases, schemas | github.com/PowerShell/DSC |
| Announcing v3 | Design + concepts | devblogs.microsoft.com |
| winget configure | Applying configs at scale | WinGet Configuration |
