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 oneMicrosoft.Windows/Registryinstance per key or value. The underlyingregistry.exegained a--listswitch to support it, the resource version moved to 1.1, and the registry manifests were consolidated into a singleregistry.dsc.manifests.jsonfile.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.
NOTE
The conversion helpers currently cover the types needed byMicrosoft.Windows/Personalization. We deliberately started narrow rather than guessing at a
complete type mapping up front. We’ll add more conversions as real use cases surface. If you hit a
registry type the adapter doesn’t handle, open an issue. That’s exactly the signal we’re looking
for.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 typeinvoke_dsc_function()— invokes a DSC built-in functioninvoke_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 currentsetoperation. The input must be the resource ID for another instance in a configuration, likestateChanged(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/ServiceMicrosoft.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 shouldignore,disable, orremovethe rules.direction(optional) – limits the action toInboundorOutboundrules 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, orAll.
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:
- A user defines an input instance of the resource, defining one or more properties to filter the exported instances on.
- DSC invokes the export operation for the resource without passing the defined filtering properties from the resource instance.
- The resource emits the full list of instances to DSC.
- 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
objectyou 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
arrayyou can specify one or more items. When you specify multiple items, DSC treats each item as a logicalORfilter. - 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.
The post Announcing Microsoft Desired State Configuration v3.3.0 appeared first on PowerShell Team.
