<\/p>\n
We’re excited to announce the General Availability of Microsoft Desired State Configuration (DSC)\nv3.3.0. This release delivers three new built-in Windows resources, a new registry-backed adapter,\nexpanded For background on the DSC v3 platform, see:<\/p>\n For information on installing DSC v3.3, see the installation documentation<\/a>.<\/p>\n All these changes are driven by real-world use, partner feedback, and community contributions.\nSpecial thanks to the WinGet team and the incredible DSC community.<\/p>\n For a complete list of changes, see the release page on GitHub<\/a>.<\/p>\n DSC v3.3 adds three new resources to the All three ship in the box. You can discover them, and inspect their schemas, with the DSC CLI:<\/p>\n v3.3 introduces <\/i>NOTE<\/strong><\/p>The conversion helpers currently cover the types needed by\n The Three new tools are available to connected clients in v3.3:<\/p>\n Together these let a client inspect what a resource expects and evaluate configuration\nexpressions without shelling out to the CLI.<\/p>\n The DSC v3.3 adds two new stable expression functions for reasoning about resource state within a\nconfiguration document:<\/p>\n Preview a service change without applying it:<\/p>\n DSC reports the state it would<\/em> set, so you can review the change before committing to it.<\/p>\n In this release of DSC, the The The following snippet shows an instance of This feature is experimental in v3.3 and its syntax may change in a future release.<\/strong><\/p>\n Starting with version In this release, resources can opt into letting the DSC engine filter the resources returned by the\nexport operation by defining the When a resource opts into using synthetic export:<\/p>\n The synthetic export filtering in this release has the following limitations:<\/p>\n For example, the following snippet of a configuration document shows how you could export a subset\nof Windows services even though The The rename better reflects the semantics and usage for the parameter. The previous name,\n You can only specify a single comparator for the version. You can’t combine them in a single\ninstance to define a version range. When you specify a comparator other than the equal to comparator\n( The comparison works for versions that include non-digit segments but the version must start<\/em> with\na digit.<\/p>\n DSC v3.3 is published to the This release leaned heavily on the community, and we’re grateful for it.<\/p>\n @Gijsreyn<\/a> (Gijs Reijn)<\/strong> was the standout contributor this cycle. Gijs contributed\n @JohnMcPMS<\/a><\/strong> (Winget team) contributed a fix for stdin being inherited by child processes\nwhen no input was provided.<\/p>\n @Alex-shearing<\/a><\/strong> contributed documentation fixes and documentation for previously\nundocumented functions.<\/p>\n @ThomasNieto<\/a> (Thomas Nieto)<\/strong> added dev container support to the repository, making it\neasier to get a working DSC build environment.<\/p>\n We’ll keep iterating on the platform based on what you tell us \u2014 real configurations, real adapters,\nand real bug reports shape what we build next. Watch the DSC repository<\/a> for what’s in flight.<\/p>\n--what-if<\/code> support, experimental export filtering, expression function updates, and Linux\npackages published to PMC.<\/p>\n\n
What’s New in DSC v3.3<\/h2>\n
New built-in Windows resources<\/h3>\n
Microsoft.Windows<\/code> namespace.<\/p>\n\n
Microsoft.Windows\/RegistryList<\/code>Manages an array of registry entries in a single resource instance, instead of requiring one\nMicrosoft.Windows\/Registry<\/code> instance per key or value. The underlying registry.exe<\/code> gained a\n--list<\/code> switch to support it, the resource version moved to 1.1, and the registry manifests were\nconsolidated into a single registry.dsc.manifests.json<\/code> file.<\/li>\nMicrosoft.Windows\/WindowsFeatureList<\/code>Manages Windows features as a list, following the same list-oriented pattern.<\/li>\nMicrosoft.Windows\/Personalization<\/code>Manages Windows personalization settings, including accent color, light and dark mode, and\ntransparency.<\/li>\n<\/ul>\ndsc resource list 'Microsoft.Windows\/*'\r\ndsc resource schema --resource Microsoft.Windows\/Personalization<\/code><\/pre>\nNew adapter:
Microsoft.Windows.Adapter\/Registry<\/code><\/h3>\nMicrosoft.Windows.Adapter\/Registry<\/code>, a registry-backed adapter that includes\nhelpers for converting between JSON property values and their registry representations. This lets a\nresource express its desired state as ordinary JSON properties while the adapter handles the\nregistry read and write.<\/p>\nMicrosoft.Windows\/Personalization<\/code>. We deliberately started narrow rather than guessing at a\ncomplete type mapping up front. We’ll add more conversions as real use cases surface. If you hit a\nregistry type the adapter doesn’t handle, open an issue. That’s exactly the signal we’re looking\nfor.<\/div><\/p>\ndsc mcp<\/code> is now dsc server<\/code><\/h3>\ndsc mcp<\/code> command is renamed to dsc server<\/code> to better reflect usability. Many of the endpoints\nthat are useful to MCP clients are also useful to integrating tools and provides a clean API for\nfunctionality that higher order tools can leverage. The mcp<\/code> name is retained as a\nbackward-compatible alias, so existing client configurations keep working.<\/p>\ndsc server<\/code><\/pre>\n\n
show_dsc_schema()<\/code> \u2014 returns the JSON schema for a DSC resource or type<\/li>\ninvoke_dsc_function()<\/code> \u2014 invokes a DSC built-in function<\/li>\ninvoke_dsc_expression()<\/code> \u2014 evaluates a DSC expression<\/li>\n<\/ul>\nformat()<\/code> is no longer experimental<\/h3>\nformat()<\/code> expression function graduates to stable in v3.3. It behaves the same as it did in\npreview, but the experimental warning is gone and you can rely on it in production configurations.<\/p>\n$schema: https:\/\/aka.ms\/dsc\/schemas\/v3\/bundled\/config\/document.json\r\nresources:\r\n - name: Echo formatted message\r\n type: Microsoft.DSC.Debug\/Echo\r\n properties:\r\n output: \"[format('{0}\/{1}', 'Microsoft.Windows', 'Personalization')]\"<\/code><\/pre>\nNew expression functions:
stateChanged()<\/code> and restartRequired()<\/code><\/h3>\n\n
stateChanged()<\/code> – returns whether a resource instance changed state during the current set<\/code>\noperation. The input must be the resource ID for another instance in a configuration, like\nstateChanged(resourceId('<resourceTypeName>', '<resourceInstanceName>'))<\/code>.<\/li>\nrestartRequired()<\/code> – returns whether a system, service, or process requires a restart. The input\ndepends on which kind of restart you want to query:<\/p>\n\n
restartRequired('system')<\/code> – indicates whether the system itself requires a restart.<\/li>\nrestartRequired('service', '<serviceName>')<\/code> – indicates whether the specified service\nrequires a restart.<\/li>\nrestartRequired('process', '<processName>')<\/code> – indicates whether the specified process\nrequires a restart.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\nExpanded
--what-if<\/code> support<\/h3>\n--what-if<\/code> lets you preview what a set<\/code> operation would change without modifying your system. In\nv3.3, three more resource areas support it.<\/p>\n\n
Microsoft.Windows\/Service<\/code><\/li>\nMicrosoft.Windows\/FirewallRuleList<\/code><\/li>\n# service.dsc.config.yaml\r\n$schema: https:\/\/aka.ms\/dsc\/schemas\/v3\/bundled\/config\/document.json\r\nresources:\r\n - name: Print Spooler\r\n type: Microsoft.Windows\/Service\r\n properties:\r\n name: Spooler\r\n startType: Disabled<\/code><\/pre>\ndsc config set --what-if --file .\/service.dsc.config.yaml<\/code><\/pre>\nUnspecified rules handling for
Microsoft.Windows\/FirewallRuleList<\/code><\/h3>\nMicrosoft.Windows\/FirewallRuleList<\/code> resource added the\nunspecifiedRules<\/code> property to control how DSC treats firewall rules you didn’t list in your\nconfiguration.<\/p>\nunspecifiedRules<\/code> property has three fields to provide more fine-grained control:<\/p>\n\n
action<\/code> (required) – indicates whether the resource should ignore<\/code>, disable<\/code>, or remove<\/code> the\nrules.<\/li>\ndirection<\/code> (optional) – limits the action to Inbound<\/code> or Outbound<\/code> rules if specified. To apply\nthe action to all unspecified rules regardless of direction omit this field.<\/li>\nprofiles<\/code> (optional) – limits the action to an array of specified profiles – Domain<\/code>, Private<\/code>,\nPublic<\/code>, or All<\/code>.<\/li>\n<\/ul>\nMicrosoft.Windows\/FirewallRuleList<\/code> that disables every\ninbound rule for the Public<\/code> profile:<\/p>\n# firewall.dsc.config.yaml\r\n$schema: https:\/\/aka.ms\/dsc\/schemas\/v3\/bundled\/config\/document.json\r\nresources:\r\n - name: Firewall rules\r\n type: Microsoft.Windows\/FirewallRuleList\r\n properties:\r\n rules: [] # Define no rules to apply to _all_ rules\r\n unspecifiedRules:\r\n action: disable\r\n direction: Inbound\r\n profiles: [Public]<\/code><\/pre>\nSynthetic export filtering (experimental)<\/h3>\n
3.3.0<\/code>, the DSC engine supports synthetic export filtering for resources\nthat don’t directly implement filtering for instances in export<\/code> operations.<\/p>\nexport.supportsFiltering<\/code> field in a resource manifest as\nfalse<\/code>.<\/p>\n\n
\n
\n
*<\/code>), which DSC uses for a case-insensitive\nwildcard match.<\/li>\n<\/ul>\n<\/li>\nobject<\/code> you can specify\nthe subproperties as valid values or wildcard matching strings. DSC applies the filter through\nnested layers, enabling you to filter for deeply nested subproperties as well as top-level\nproperties.<\/li>\narray<\/code> you can specify one or more\nitems. When you specify multiple items, DSC treats each item as a logical OR<\/code> filter.<\/li>\nMicrosoft.Windows\/Service<\/code> doesn’t implement export filtering:<\/p>\n# services.dsc.config.yaml\r\n$schema: https:\/\/aka.ms\/dsc\/schemas\/v3\/bundled\/config\/document.json\r\nresources:\r\n # Only exports services where the startup type begins with `auto` and the logon account inludes\r\n # `local` in the account name\r\n - name: Automatically starting local account services\r\n type: Microsoft.Windows\/Service\r\n properties:\r\n startType: Auto*\r\n logonAccount: '*Local*'\r\n # Only exports services that depend on `rpcss` or a service that starts with `w`\r\n - name: Services depending on RpcSs or a service that starts with w\r\n type: Microsoft.Windows\/Service\r\n properties:\r\n dependencies:\r\n - RpcSs\r\n - w*\r\n # Only exports services where the following are all true:\r\n # - the startup type begins with `auto`\r\n # - the logon account inludes `local` in the account name\r\n # - the service depends on `rpcss` or a service that starts with `w`\r\n - name: Combined service filter\r\n type: Microsoft.Windows\/Service\r\n properties:\r\n startType: Auto*\r\n logonAccount: '*Local*'\r\n dependencies:\r\n - RpcSs\r\n - w*<\/code><\/pre>\n--required-version<\/code> replaces --version<\/code><\/h3>\ndsc resource *<\/code> commands now take --required-version<\/code> instead of --version<\/code>. The old flag\nis retained as a backward-compatible alias.<\/p>\n--version<\/code>, implied an exact match for a specific version instead of a version requirement<\/em>, which\nis how DSC actually parses and uses the parameter value. You can specify Rust-like semantic version\nrequirements, like ^1.1<\/code>, ~1.2.3<\/code>, and >=1<\/code>.<\/p>\ndsc resource schema --resource Microsoft.Windows\/RegistryList --required-version '^1.1.0'<\/code><\/pre>\nMicrosoft\/OSInfo<\/code> version comparison<\/h3>\nMicrosoft\/OSInfo<\/code> now supports version comparison, so a configuration can assert a version\nconstraint on the OS rather than matching an exact value. Starting with this release, you can\nspecify the version field with a comparison operator followed by a full or partial version, like\n>10.1<\/code>. The available comparators are:<\/p>\n\n
=<\/code>) – this is the default comparator, requiring an exact match<\/em> for the text that\nfollows the comparator.<\/li>\n<<\/code>)<\/li>\n<=<\/code>)<\/li>\n><\/code>)<\/li>\n>=<\/code>)<\/li>\n<\/ul>\n=<\/code>), you can specify a partial version to match. For example, if you define the version as > 10<\/code>\nthe instance will be valid for any operating system versions like 10.0.1<\/code> and 11.3.7<\/code>.<\/p>\nLinux packages on PMC<\/h3>\n
https:\/\/packages.microsoft.com<\/code> (PMC) for Linux as both RPM and DEB\npackages. You can now install and update DSC through your distribution’s package manager instead of\ndownloading a tarball from GitHub releases.<\/p>\nCommunity contributions<\/h2>\n
Microsoft.Windows\/WindowsFeatureList<\/code>, --what-if<\/code> support for Microsoft.Windows\/Service<\/code>,\nMicrosoft.Windows\/FirewallRuleList<\/code>, and the SSHD config resources, experimental export filtering,\nthe graduation of format()<\/code> out of experimental, category and description filters for the function\nlist, and a large amount of documentation work. Thank you, Gijs.<\/p>\nLooking ahead<\/h2>\n
Call to action<\/h2>\n