Announcing DSC v3.2.0

We’re excited to announce the General Availability of Microsoft Desired State Configuration (DSC) v3.2.0. This release delivers new built-in Windows resources, experimental Bicep integration via gRPC, version pinning, a richer expression language, custom functions, and continued adapter improvements. All these changes are driven by real-world use, partner feedback, and community contributions. Special thanks to the WinGet team and the incredible DSC community.

For background on the DSC v3 platform, see:

• DSC v3.0.0 Announcement
• DSC v3.1.0 Announcement

What’s New in DSC v3.2

New Windows resources

DSC v3.2 ships several new built-in Windows resources, significantly expanding what you can manage out of the box:

• Microsoft.Windows/Service — manage Windows services
• Microsoft.Windows/OptionalFeatureList — manage Windows Optional features
  • Requires using the ZIP package of DSC for now
• Microsoft.Windows/FeatureOnDemandList — manage Windows Features on Demand
  • Requires using the ZIP package of DSC for now
• Microsoft.Windows/FirewallRuleList — manage Windows Firewall rules
• Microsoft.OpenSSH.SSHD/sshd_config — manage entire SSH server configuration
• Microsoft.OpenSSH.SSHD/Subsystem and Microsoft.OpenSSH.SSHD/SubsystemList — manage SSH server configuration for subsystem entries
• Microsoft.OpenSSH.SSHD/Windows — manage Windows SSH server configuration, such as the default shell

These resources are included in the DSC package and ready to use without additional installation.

Bicep integration via gRPC (experimental)

DSC v3.2 introduces a gRPC server, enabling Bicep to orchestrate DSC resources directly. The dsc-bicep-ext extension is now included in the MSIX package and exposed on PATH.

This is the foundation for the Bicep to DSC integration. Write your configuration in Bicep. Bicep orchestrates the execution directly over gRPC without going through ARM.

Extended WhatIf support

DSC v3.2 adds --what-if support to the dsc resource set command, letting you preview changes before applying them:

dsc resource set --what-if --resource Microsoft.Windows/Service --input '{
    "name": "spooler",
    "startupType": "disabled"
}'

Prior to this release there was no way to run --what-if against individual resources. You could use the --what-if flag with the dsc config set command, which ran all resources in your configuration in --what-if mode.

Resource manifests can now declare whatIfReturns to describe what a what-if operation returns, enabling richer preview output across resources.

Version pinning

DSC v3.2 supports pinning configuration documents to specific versions of DSC and pinning resource instances in configuration documents to specific versions of the resource.

Now you can author a DSC configuration document and ensure that it only executes when the given versions of DSC and resources that are available on the system. Prior to this release, DSC always used the latest version of a resource discovered on a system for configuration operations.

The following example shows how to pin a configuration document to a specific version of DSC using the version directive and how to pin individual resource instances to specific versions using the requireVersion field.

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
directives:
  version: '=3.2.0' # This configuration is only valid for exactly version 3.2.0
resources:
- name: os
  type: Microsoft/OSInfo
  requireVersion: '^1.0' # Resource versions >= 1.0.0 and < 2.0.0 are valid
  properties: {}
- name: echo
  type: Microsoft.DSC.Debug/Echo
  requireVersion: '>=1.0.0, <1.3'
  properties:
    output: echo

When DSC evaluates a resource version pin in a configuration document, it looks for the latest version of the resource that meets the given requirement. If no compatible version is discovered on the system, DSC raises an error.

Starting with version 3.2, when you specify the version directive, DSC raises an error when the version of DSC operating on the configuration document isn’t compatible.

Expression language improvements

Configuration documents now support a richer expression syntax:

• Lambda expressions with map() and filter() functions (ARM syntax)
• dataUri() and dataUriToString() functions
• reference() usage inside copy loops
• requireVersion replaces apiVersion for version requirements

These additions make configuration documents more expressive and reduce the need to duplicate values across resources.

Adapter improvements

DSC 3.2 adds support for adapted resource manifests to the PowerShell adapters. Resource authors can create adapted resource manifests that prevent adapters from needing to do more intensive discovery operations.

This release also includes other improvements to the PowerShell adapters:

• Added automatic conversion of PowerShell streams to DSC traces. Resource authors can participate in DSC’s tracing model by using the normal Write-* cmdlets.
• Fixed passing credentials to adapted PSDSC resource instances.

Metadata and execution improvements

• Microsoft.DSC metadata is now split into directives and executionInformation — cleaner separation of configuration intent from execution context.
• _refreshEnv resource metadata updates Windows environment variables during deployment without requiring a restart.
• Resource manifests can now specify requireSecurityContext per operation, helping users avoid problems where they retrieve data for a resource with a get or test operation and then get an access denied error when they try to run the set command.
• Resources and extensions can now be marked as deprecated, with a deprecation message surfaced at runtime.

New extension capabilities

DSC 3.2 adds support for two new extension capabilities: importing configurations and retrieving secrets.

You can use an extension with the import capability to process arbitrary files as DSC configuration documents. For example, a hypothetical extension with this capability could transform the following TOML snippet into a DSC configuration document:

# example.dsc.toml
[directives]
version = '3.2.0'
[resources.os]
type       = 'Microsoft/OSInfo'
properties = {}

The resulting DSC configuration document:

# effective DSC configuration document
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
directives:
  version: '=3.2.0' # This configuration is only valid for exactly version 3.2.0
resources:
- name: os
  type: Microsoft/OSInfo
  properties: {}

When you use the --file option with the dsc config * commands, DSC checks the file extension to see whether an extension can process that file. If there is no DSC extension that handles the given file extension, DSC tries to parse the file as a configuration document.

You can use a DSC extension with the secret capability to retrieve secrets at runtime. Presenting secret retrieval through the extension model enables DSC to be used with secrets in a variety of contexts without requiring the core engine to handle these operations directly. This capability is paired with the new secret() configuration expression for retrieving secrets by name.

Experimental PowerShell discovery extension

DSC now includes a discovery extension for finding DSC resources in PowerShell modules. This extension looks for resource manifests and adapted resource manifests located inside PowerShell modules on the system. This makes it possible for resource authors to ship DSC resources written in PowerShell that are not PSDSC resources.

For example, with this extension, DSC could discover a resource implemented as a PowerShell script as long as the module also includes a valid manifest for the resource.

Bug fixes

• Fixed duplicate resources appearing in dsc resource list
• Added a clear error when attempting to use DISM resources via Appx (previously a silent failure)
• Fixed executionInformation in config export results
• Fixed discovery failures when encountering unsupported manifests

Community contributions

DSC v3.2 reflects the work of an active and growing contributor community. The following community members made notable contributions to this release:

• @Gijsreyn (Gijs Reijn) — experimental PowerShell discovery extension, lambda/map/filter expressions, dataUri functions, adapted resource manifest fixes, and more.
• @mimachniak — PowerShell adapter credentials fix for passing username and password.

Thank you to everyone who filed issues, tested previews, and submitted fixes during the DSC v3.2 release cycle.

Installing DSC

On Windows, you can install DSC from the Microsoft Store using winget. Installing from the Store gives you automatic updates.

Search for the latest version of DSC:

winget search DesiredStateConfiguration --source msstore

Name                              Id           Version
------------------------------------------------------
DesiredStateConfiguration         9NVTPZWRC6KQ Unknown
DesiredStateConfiguration-Preview 9PCX3HX4HZ0Z Unknown

Install DSC using the id parameter:

# Install latest stable
winget install --id 9NVTPZWRC6KQ --source msstore

# Install latest preview
winget install --id 9PCX3HX4HZ0Z --source msstore

To install the ZIP package on Windows, Linux, or macOS:

1. Download the latest release from the PowerShell/DSC repository.
2. Expand the release archive.
3. Add the folder containing the expanded archive contents to your PATH environment variable.

Support lifecycle

DSC follows semantic versioning. DSC v3.2.0 is the current stable release. Patch releases update the third digit of the semantic version number — for example, 3.2.1 is a patch update to 3.2.0.

Stable releases receive patches for critical bugs and security vulnerabilities for three months after the next stable release. For example, v3.2.0 is supported for three months after v3.3.0 is released.

Always update to the latest patch version of the release you’re using.

Looking ahead

Work continues on DSC v3.3, with previews starting shortly after the v3.2.0 GA release.

Call to action

For more information about DSC, see the DSC documentation. We value your feedback. Stop by our GitHub repository and let us know of any issues you find.

Jason Helmick

Sr. Product Manager, PowerShell