Announcing Microsoft Desired State Configuration v3.3.0

We’re excited to announce the General Availability of Microsoft Desired State Configuration (DSC) v3.3.0. This release delivers three new built-in Windows resources, a new registry-backed adapter, expanded --what-if support, experimental export filtering, expression function updates, and Linux packages published to PMC.

For background on the DSC v3 platform, see:

• Get Started
• Enhanced Authoring
• DSC v3.2.0 Announcement
• DSC v3.1.0 Announcement
• DSC v3.0.0 Announcement

For information on installing DSC v3.3, see the installation documentation.

What’s New in DSC v3.3

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 a complete list of changes, see the release page on GitHub.

New built-in Windows resources

DSC v3.3 adds three new resources to the Microsoft.Windows namespace.

• Microsoft.Windows/RegistryListManages an array of registry entries in a single resource instance, instead of requiring one Microsoft.Windows/Registry instance per key or value. The underlying registry.exe gained a --list switch to support it, the resource version moved to 1.1, and the registry manifests were consolidated into a single registry.dsc.manifests.json file.
• Microsoft.Windows/WindowsFeatureListManages Windows features as a list, following the same list-oriented pattern.
• Microsoft.Windows/PersonalizationManages Windows personalization settings, including accent color, light and dark mode, and transparency.

All three ship in the box. You can discover them, and inspect their schemas, with the DSC CLI:

dsc resource list 'Microsoft.Windows/*'
dsc resource schema --resource Microsoft.Windows/Personalization

New adapter: Microsoft.Windows.Adapter/Registry

v3.3 introduces Microsoft.Windows.Adapter/Registry, a registry-backed adapter that includes helpers for converting between JSON property values and their registry representations. This lets a resource express its desired state as ordinary JSON properties while the adapter handles the registry read and write.

dsc mcp is now dsc server

The dsc mcp command is renamed to dsc server to better reflect usability. Many of the endpoints that are useful to MCP clients are also useful to integrating tools and provides a clean API for functionality that higher order tools can leverage. The mcp name is retained as a backward-compatible alias, so existing client configurations keep working.

dsc server

Three new tools are available to connected clients in v3.3:

• show_dsc_schema() — returns the JSON schema for a DSC resource or type
• invoke_dsc_function() — invokes a DSC built-in function
• invoke_dsc_expression() — evaluates a DSC expression

Together these let a client inspect what a resource expects and evaluate configuration expressions without shelling out to the CLI.

format() is no longer experimental

The format() expression function graduates to stable in v3.3. It behaves the same as it did in preview, but the experimental warning is gone and you can rely on it in production configurations.

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Echo formatted message
    type: Microsoft.DSC.Debug/Echo
    properties:
      output: "[format('{0}/{1}', 'Microsoft.Windows', 'Personalization')]"

New expression functions: stateChanged() and restartRequired()

DSC v3.3 adds two new stable expression functions for reasoning about resource state within a configuration document:

• stateChanged() – returns whether a resource instance changed state during the current set operation. The input must be the resource ID for another instance in a configuration, like stateChanged(resourceId('<resourceTypeName>', '<resourceInstanceName>')).
• restartRequired() – returns whether a system, service, or process requires a restart. The input depends on which kind of restart you want to query:
  • restartRequired('system') – indicates whether the system itself requires a restart.
  • restartRequired('service', '<serviceName>') – indicates whether the specified service requires a restart.
  • restartRequired('process', '<processName>') – indicates whether the specified process requires a restart.

Expanded --what-if support

--what-if lets you preview what a set operation would change without modifying your system. In v3.3, three more resource areas support it.

• Microsoft.Windows/Service
• Microsoft.Windows/FirewallRuleList
• The SSHD config resources

Preview a service change without applying it:

# service.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Print Spooler
    type: Microsoft.Windows/Service
    properties:
      name: Spooler
      startType: Disabled

dsc config set --what-if --file ./service.dsc.config.yaml

DSC reports the state it would set, so you can review the change before committing to it.

Unspecified rules handling for Microsoft.Windows/FirewallRuleList

In this release of DSC, the Microsoft.Windows/FirewallRuleList resource added the unspecifiedRules property to control how DSC treats firewall rules you didn’t list in your configuration.

The unspecifiedRules property has three fields to provide more fine-grained control:

• action (required) – indicates whether the resource should ignore, disable, or remove the rules.
• direction (optional) – limits the action to Inbound or Outbound rules if specified. To apply the action to all unspecified rules regardless of direction omit this field.
• profiles (optional) – limits the action to an array of specified profiles – Domain, Private, Public, or All.

The following snippet shows an instance of Microsoft.Windows/FirewallRuleList that disables every inbound rule for the Public profile:

# firewall.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Firewall rules
    type: Microsoft.Windows/FirewallRuleList
    properties:
      rules: [] # Define no rules to apply to _all_ rules
      unspecifiedRules:
        action: disable
        direction: Inbound
        profiles: [Public]

Synthetic export filtering (experimental)

This feature is experimental in v3.3 and its syntax may change in a future release.

Starting with version 3.3.0, the DSC engine supports synthetic export filtering for resources that don’t directly implement filtering for instances in export operations.

In this release, resources can opt into letting the DSC engine filter the resources returned by the export operation by defining the export.supportsFiltering field in a resource manifest as false.

When a resource opts into using synthetic export:

1. A user defines an input instance of the resource, defining one or more properties to filter the exported instances on.
2. DSC invokes the export operation for the resource without passing the defined filtering properties from the resource instance.
3. The resource emits the full list of instances to DSC.
4. The DSC engine uses the defined properties in the resource instance to filter the emitted instances the resource returned.

The synthetic export filtering in this release has the following limitations:

• The provided input for the instance must be an object where every property is a valid property name for the resource.
• The value for every property in the input object must be one of:
  • A valid value for the property, which DSC uses for an exact match.
  • A string with at least one wildcard character (*), which DSC uses for a case-insensitive wildcard match.
• When the property is defined in the resource schema as an object you can specify the subproperties as valid values or wildcard matching strings. DSC applies the filter through nested layers, enabling you to filter for deeply nested subproperties as well as top-level properties.
• When the property is defined in the resource schema as an array you can specify one or more items. When you specify multiple items, DSC treats each item as a logical OR filter.
• There is no builtin filtering behavior for more complex cases, like version range matching or minimum/maximum bounds for integer properties.

For example, the following snippet of a configuration document shows how you could export a subset of Windows services even though Microsoft.Windows/Service doesn’t implement export filtering:

# services.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  # Only exports services where the startup type begins with `auto` and the logon account inludes
  # `local` in the account name
  - name: Automatically starting local account services
    type: Microsoft.Windows/Service
    properties:
      startType: Auto*
      logonAccount: '*Local*'
  # Only exports services that depend on `rpcss` or a service that starts with `w`
  - name: Services depending on RpcSs or a service that starts with w
    type: Microsoft.Windows/Service
    properties:
      dependencies:
        - RpcSs
        - w*
  # Only exports services where the following are all true:
  # - the startup type begins with `auto`
  # - the logon account inludes `local` in the account name
  # - the service depends on `rpcss` or a service that starts with `w`
  - name: Combined service filter
    type: Microsoft.Windows/Service
    properties:
      startType: Auto*
      logonAccount: '*Local*'
      dependencies:
        - RpcSs
        - w*

--required-version replaces --version

The dsc resource * commands now take --required-version instead of --version. The old flag is retained as a backward-compatible alias.

The rename better reflects the semantics and usage for the parameter. The previous name, --version, implied an exact match for a specific version instead of a version requirement, which is how DSC actually parses and uses the parameter value. You can specify Rust-like semantic version requirements, like ^1.1, ~1.2.3, and >=1.

dsc resource schema --resource Microsoft.Windows/RegistryList --required-version '^1.1.0'

Microsoft/OSInfo version comparison

Microsoft/OSInfo now supports version comparison, so a configuration can assert a version constraint on the OS rather than matching an exact value. Starting with this release, you can specify the version field with a comparison operator followed by a full or partial version, like >10.1. The available comparators are:

• Equal to (=) – this is the default comparator, requiring an exact match for the text that follows the comparator.
• Less than (<)
• Less than or equal to (<=)
• Greater than (>)
• Greater than or equal to (>=)

You can only specify a single comparator for the version. You can’t combine them in a single instance to define a version range. When you specify a comparator other than the equal to comparator (=), you can specify a partial version to match. For example, if you define the version as > 10 the instance will be valid for any operating system versions like 10.0.1 and 11.3.7.

The comparison works for versions that include non-digit segments but the version must start with a digit.

Linux packages on PMC

DSC v3.3 is published to the https://packages.microsoft.com (PMC) for Linux as both RPM and DEB packages. You can now install and update DSC through your distribution’s package manager instead of downloading a tarball from GitHub releases.

Community contributions

This release leaned heavily on the community, and we’re grateful for it.

@Gijsreyn (Gijs Reijn) was the standout contributor this cycle. Gijs contributed Microsoft.Windows/WindowsFeatureList, --what-if support for Microsoft.Windows/Service, Microsoft.Windows/FirewallRuleList, and the SSHD config resources, experimental export filtering, the graduation of format() out of experimental, category and description filters for the function list, and a large amount of documentation work. Thank you, Gijs.

@JohnMcPMS (Winget team) contributed a fix for stdin being inherited by child processes when no input was provided.

@Alex-shearing contributed documentation fixes and documentation for previously undocumented functions.

@ThomasNieto (Thomas Nieto) added dev container support to the repository, making it easier to get a working DSC build environment.

Looking ahead

We’ll keep iterating on the platform based on what you tell us — real configurations, real adapters, and real bug reports shape what we build next. Watch the DSC repository for what’s in flight.

Call to action

Install DSC v3.3.0, try the new Windows resources, and run --what-if against a configuration before you apply it. If you find a bug, hit a gap in the registry adapter’s type conversions, or have feedback on experimental export filtering, open an issue in the DSC repository. Community feedback is what drove this release, and it’s what will drive the next one.