Desired State Configuration: Modern DSC and PowerShell DSC Context

1. Declarative configuration states the destination, not the route

An imperative script describes steps. A declarative configuration describes the state that should be true. The engine and resource implementations are responsible for observing current state, comparing it with desired state, and enforcing changes when necessary.

This is the same convergence loop from Lesson 1, but expressed as data plus resource contracts instead of hand-written orchestration for every target.

2. “DSC” names several generations—do not mix their architecture

As of this chapter’s generation, Microsoft DSC 3.x is the current standalone, true cross-platform product. It is not dependent on PowerShell. Microsoft’s own overview separately identifies PowerShell DSC 2.0 (available as the PSDesiredStateConfiguration module) and Windows PowerShell DSC 1.1 as older generations.

That distinction matters. Modern DSC uses the dsc executable, configuration documents, command/resource manifests, schemas, and adapters. Older examples centered on MOF compilation, Local Configuration Manager (LCM), Configuration blocks, and Start-DscConfiguration belong to PowerShell DSC generations and should not be taught as the current general architecture.

3. Modern DSC still revolves around Get, Test, and Set semantics

A resource exposes a state contract. Get retrieves actual state. Test determines whether actual state satisfies desired state. Set attempts to converge a resource instance. At configuration level, dsc config get, dsc config test, and dsc config set process the resource instances in a document.

The important design rule is unchanged: Set should be safe to repeat because Test and Set model desired-state convergence rather than blind command replay.

dsc resource list
dsc config get  --file ./example.dsc.yaml
dsc config test --file ./example.dsc.yaml
# dsc config set --file ./example.dsc.yaml   # state-changing; review first

4. Configuration documents are versioned YAML or JSON data

Modern DSC configuration documents are YAML or JSON. Microsoft recommends YAML for authoring. A document includes a schema URI and a resources array; it can also define parameters, variables, dependencies, metadata, and expressions.

Using the v3 schema alias lets the document follow the latest compatible major-version schema. Production teams may pin a specific schema version when they need stricter reproducibility.

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: operating-system
    type: Microsoft/OSInfo
    properties: {}

5. Discover resources before assuming capabilities

DSC discovers command-based resources and adapters. Resource discovery is machine-readable, so automation can verify that a required type exists before applying a configuration. Adapted resources are not enumerated by default; adapter discovery can be requested explicitly.

# Native shell commands shown for reference.
dsc resource list Microsoft/OSInfo
dsc resource list --adapter Microsoft.DSC/PowerShell

6. PowerShell resources now fit through an adapter boundary

Modern DSC can still use existing PowerShell DSC resources. The Microsoft.DSC/PowerShell adapter discovers and invokes class-based PSDSC resources in PowerShell. The adapter does not require the PSDesiredStateConfiguration module for those class-based resources.

For classic resources that require Windows PowerShell—including MOF/script/binary scenarios—modern DSC provides the Windows-specific Microsoft.Windows/WindowsPowerShell adapter. The adapter boundary makes the dependency explicit instead of making PowerShell itself the DSC engine.

# Conceptual adapted-resource shape
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Example PowerShell resource
    type: ExampleModule/ExampleResource
    properties:
      Name: demo
      Ensure: Present

7. DSC output is a machine contract, not console decoration

DSC commands can emit JSON, pretty JSON, or YAML. Capture JSON when PowerShell needs to inspect results, because it preserves a stable structured boundary between the native dsc executable and your orchestration layer.

$raw = & dsc config test --file ./osinfo.dsc.yaml --output-format json
if ($LASTEXITCODE -ne 0) { throw "DSC test failed with exit code $LASTEXITCODE" }
$result = $raw | ConvertFrom-Json
$result.hadErrors
$result.results

8. DSC, Ansible, Terraform, and configuration managers overlap—but are not identical

DSC is a desired-state/resource platform. Ansible commonly orchestrates host configuration over inventories and modules. Terraform focuses on declarative infrastructure resource lifecycles and provider state. Puppet/Chef/Salt have their own agents, servers, catalogs, or orchestration models. The point is not “which one wins”; it is choosing the abstraction that matches the ownership boundary, target type, scale, ecosystem, and operating model.

PowerShell can orchestrate any of these tools, but Chapter 20 keeps the lesson on state contracts rather than duplicating future tool-specific courses.

9. Lab — read local OS state with modern DSC when available

This lab is read-only. It writes a configuration document that uses the built-in Microsoft/OSInfo resource. If dsc is unavailable, it creates a mock result so you can still practice the PowerShell parsing contract.

$root = Join-Path $PWD 'chapter20-dsc-lab'
New-Item -ItemType Directory -Path $root -Force | Out-Null
$configPath = Join-Path $root 'osinfo.dsc.yaml'
@'
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: operating-system
    type: Microsoft/OSInfo
    properties: {}
'@ | Set-Content -LiteralPath $configPath -Encoding utf8

if (Get-Command dsc -CommandType Application -ErrorAction SilentlyContinue) {
    $json = & dsc config get --file $configPath --output-format json
    if ($LASTEXITCODE -ne 0) { throw "dsc failed: $LASTEXITCODE" }
    $result = $json | ConvertFrom-Json
} else {
    $result = [pscustomobject]@{
        results = @([pscustomobject]@{
            name='operating-system'
            type='Microsoft/OSInfo'
            result=[pscustomobject]@{ actualState=[pscustomobject]@{
                family=[System.Runtime.InteropServices.RuntimeInformation]::OSDescription
            }}
        })
        hadErrors = $false
        Mocked = $true
    }
}
$result | ConvertTo-Json -Depth 8

10. Treat dsc config set as an approval boundary

dsc config set is state-changing. A safe delivery workflow validates schemas and required resources, runs get/test, reviews the difference, obtains any required approval, then performs set and verifies again. Do not turn a configuration engine into an unreviewed production mutation shortcut.

11. Verification checklist

Before using DSC in a production workflow, verify the executable version, schema choice, resource versions, adapter requirements, state-changing scope, output parsing, and post-set verification.

• dsc --version is recorded in CI evidence.
• The configuration uses an explicit schema.
• Required resources are discovered before Set.
• Get/Test evidence is retained.
• Set requires an explicit change boundary.
• PowerShell resources use the appropriate adapter.
• Legacy PSDesiredStateConfiguration examples are labeled as legacy context.

12. Knowledge check

13. Summary and bridge to observability

Modern DSC separates desired-state data from implementation through resource contracts and adapters. Production automation still needs something DSC does not replace: an observability contract that explains what ran, for whom, for how long, with what outcome, and how an operator should respond.

14. Authoritative references

Microsoft Learn — DSC overview
Microsoft Learn — dsc config
Microsoft.DSC/PowerShell adapter
PowerShell/DSC releases