Introduction to Microsoft Desired State Configuration (DSC)

Microsoft's Desired State Configuration (DSC) is the new frontier in declarative configuration. It's a cross-platform CLI utility designed for infrastructure management. Whether you're working on a desktop, macOS, or Linux-based system, it can manage your system.

Unlike imperative tools, DSC cleanly separates the what from the how. You describe what the environment should be (for example," this package must be installed"). DSC then figures out how to bring the system into that particular state.

What you'll learn:

In this getting started module, you'll learn the fundamentals of working with Microsoft DSC. By the end of this module, you'll be able to:

• Understand what Microsoft DSC is.
• Install Microsoft DSC on your system.
• Discover and explore available DSC Resources.
• Read and understand resource schemas.
• Invoke individual resources using the dsc command-line interface.
• Use the core resource operations: get, set, and test.
• Manage system configuration through a practical example.

The DSC command-line utility

Compared to its predecessor (often referred to as PowerShell DSC), DSC provides a command-line utility (CLI) tool to manage components declaratively and idempotently. It runs on Linux, macOS, and Windows, requiring no external dependencies.

With DSC, you can:

• Author DSC resources to manage your systems in any language.
• Invoke individual resources directly.
• Create configuration documents that define the desired state of a system.

Configuration documents

Configuration documents are the foundation of DSC. They're declarative data files that describe the desired state of a system by defining one or more resource instances.

In other words, a configuration document tells DSC what the system should look like once it’s properly configured.

You can write configuration documents in JSON, YAML, or Azure Bicep. Both formats are supported equally, allowing you to choose the one that best suits your workflow or tooling preferences.

Example scenarios

You might use configuration documents to:

• Define the requirements for an application environment.
• Enforce organizational or security configuration standards across systems.
• Maintain consistency between development, test, and production environments.

Imagine you want to set the system locale to a different language. The following configuration document illustrates this:

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Set system locale to en-US
    type: ComputerManagementDsc/SystemLocale
    properties:
      IsSingleInstance: 'Yes'
      SystemLocale: en-US

DSC Resources

DSC Resources define how to manage the state of a specific system or application component.
Each resource provides a schema that describes the settings it can manage and the operations it supports.

In simple terms, a DSC Resource knows what it can control and how to ensure it remains in the desired state.

Resource operations

Each resource can support one or more of the following operations:

• Get – Retrieves the current state of a resource instance.
• Test – Checks whether the current state matches the desired state.
• Set – Enforces the desired state (supported by most resources).
• Delete – Removes or resets a resource instance if it’s no longer needed.
• Export – Captures the current configuration of a resource, allowing it to be reused or versioned elsewhere.

These operations allow DSC to both validate and control the configuration of a system in an idempotent way — meaning that applying the same configuration repeatedly won’t cause unexpected changes.

Example scenarios

You might use DSC Resources to:

• Update the contents of a configuration file.
• Run a command-line utility to adjust system settings.
• Configure application parameters or deployment values.
• Remove obsolete configuration items or services.
• Export current configuration data for auditing or backup purposes.

Instead of defining a full configuration document, you can invoke a resource directly using the DSC CLI. The following command tests if the system locale is actually set to en-US using the ComputerManagementDsc/SystemLocale resource:

# Pipe the input to dsc resource set
'{"IsSingleInstance":"Yes","SystemLocale":"ja-JP"}' | dsc resource test -r ComputerManagementDsc/SystemLocale

Differences from PowerShell DSC

While DSC shares some concepts with PowerShell Desired State Configuration (PSDSC), it differs in several important ways. Understanding these differences helps you leverage DSC more effectively, especially in cross-platform environments.

No PowerShell dependency

Instead, DSC provides full compatibility with PSDSC resources through adapter resources:

• Microsoft.DSC/PowerShell adapter
  • Supports PSDSC resources implemented as PowerShell classes.
  • Handles discovery, validation, and invocation of these resources.
  • Included in the DSC install package on all platforms.
• Microsoft.Windows/WindowsPowerShell adapter
  • Supports PSDSC resources compatible with Windows PowerShell.
  • Handles discovery, validation, and invocation in Windows PowerShell.
  • Included in DSC install packages for Windows only.

No Local Configuration Manager

DSC does not include a local configuration manager. It runs as a command-line tool, not as a background service.

This means DSC configurations are applied on demand when invoked, rather than continuously monitored by a service.

Schema definition format

New DSC resources define their schemas using JSON or YAML, instead of MOF files.

• Self-contained resources include a resource manifest specifying:
  • How DSC should invoke the resource.
  • What properties the resource can manage.
• Adapted resources (e.g., PowerShell-based) rely on their adapter resource to:
  • Discover available properties.
  • Invoke the resource correctly.

Configuration documents format

DSC configuration documents are authored in JSON or YAML, not PowerShell scripts.

These documents support a subset of Azure Resource Manager (ARM) template features, including:

• Parameters
• Variables
• Metadata
• Expression functions

Next up

You have now learned about Microsoft Desired State Configuration (DSC). It's time to install dsc on your machine in the next lesson.