title	description	ms.date
Desired State Configuration changelog	A log of the changes for releases of DSCv3.	03/06/2024

Changelog

All notable changes to DSCv3 are documented in this file. The format is based on Keep a Changelog, and DSCv3 adheres to Semantic Versioning.

Unreleased

This section includes a summary of user-facing changes since the last release. For the full list of changes since the last release, see the diff on GitHub.

v3.0.0-preview.7 - 2024-04-22

This section includes a summary of changes for the preview.7 release. For the full list of changes in this release, see the diff on GitHub.

Changed

The version segment of the schema URIs for DSC have been updated from 2023/10 to 2024/04 to accommodate breaking schema changes from the schemas that alpha.5 used. You can find more information about the specific changes to the schemas in the following changelog entries:

Renamed 'providers' to 'adapters'
Added the 'delete' operation for resources
Added the option to specify a required security context for a configuration document
Add option to specify a JSON input argument for resource commands
Add 'kind' property to resource manifests
Camel-cased 'SecureObject' and 'SecureString' parameter types
Add 'capabilities' to 'dsc resource list' output
Added metadata to config and resource output

Update your configuration documents and resource manifests to use the following URIs for the $schema keyword:

Canonical URI for configuration documents: >-
  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json

Bundled URI for configuration documents: >-
  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json

Enhanced Authoring in VS Code URI for configuration documents: >-
  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json

Canonical URI for resource manifests: >-
  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json

Bundled URI for resource manifests: >-
  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json

Enhanced Authoring in VS Code URI for resource manifests: >-
  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json

Related work items

Issues: None.
PRs: #397

In this release, the term DSC Resource Provider is replaced with the more semantically accurate DSC Resource Adapter. These resources enable users to leverage resources that don't define a DSC Resource Manifest with DSC, like PSDSC resources - they're adapters between DSCv3 and resources defined in a different way.

Beyond using different terminology in the documentation, this change also renamed the resource manifest property provider to adapter, and the requires property in the output for dsc resource list has been renamed to requireAdapter.
Related work items
- Issues: #310
- PRs:
  - #334
  - #373
Changed the casing for the parameter type enums from SecureString to secureString and SecureObject to secureObject, to better match the type enumerations in ARM.
Related work items
- Issues: None.
- PRs: #364
The envvar() function now raises an error when the specified environment variable doesn't exist instead of returning an empty string. This change helps reduce unexpected and difficult to diagnose errors when a configuration expects a value from the environment variable.
Related work items
- Issues: #336
- PRs: #358
Renamed the DscConfigRoot environment variable to DSC_CONFIG_ROOT. DSC now correctly absolutizes the variable, even when the path to a configuration document is a relative path. DSC also raises a warning when you define the environment variable outside of DSC before overriding it.
Related work items
- Issues:
  - #317
  - #335
- PRs: #342
Updated the default behavior of the dsc resource list command and added the new --adapter option to the command.

Prior to this release, the command always called the list command for any discovered adapters, even when searching for a non-adapted resource by name. Enumerating the adapted resources can be a slow process, so the command no longer calls the adapters to list their adapted resources by default.

Instead, you can use the --adapter option to specify a filter for the adapters you want to list adapted resources for. Specify the fully qualified type name of an adapter or a string including wildcards (*) to use as a filter for adapter names. You can specify the filter * to have DSC call the list operation for every discovered adapter, returning all adapted resources.

For more information, see dsc resource list.
Related work items
- Issues:
  - #274
  - #368
- PRs: #377
Updated the table view for the dsc resource list command to display the resource kind and capabilities. The capabilities column in the table uses bit flags for the display to keep the column width manageable.

For more information, see the "Output" section of dsc resource list.
Related work items
- Issues: #329
- PRs: #346

Added

Added the dsc resource delete command and the delete operation property to the resource manifest. Prior to this release, resources had to handle deleting resources as part of their set operation, and the development guidance was to use the _exist standard property to indicate whether a resource should exist.

Now, resource authors can indicate through the resource manifest whether the resource supports the delete operation with a separate command or as part of the set operation. It can be simpler to implement a separate delete operation than to handle deleting instances as part of set. You can implement your resource to have an explicit delete command and handle deleting instances as part of a set operation.

You can also use the dsc resource delete command to delete instances one at a time. For this command, the JSON input defines the filter to pass to the resource for deleting the instance. For more information, see dsc resource delete command reference.

If your resource handles deleting instances as part of set, use the handlesExist property to tell DSC so. When this property is true, the resource has the SetHandlesExist capability.

If your resource has a separate command for deleting instances, use the delete property in your resource manifest to tell DSC and other tools how to invoke the operation. When this property is defined, the resource has the Delete capability.

If your resource handles deleting instances, you should add the _exist standard property to the resource's instance schema. While you can use any property name for this, DSC is only aware of deletion operations when you use the _exist property. DSC won't know to call the delete operation for resources that don't have the SetHandlesExist capability.

For resources that implement delete but don't handle _exist in the set operation, DSC can now invoke the delete operation as-needed in a configuration whenever it enforces the desired state for an instance of a resource with the _exist property set to false.
Related work items
- Issues: #290
- PRs:
  - #379
  - #382
Added the option to specify whether a configuration document requires root or elevated permissions. Now, you can define the securityContext metadata property under the Microsoft.DSC namespace in a configuration document to specify which security context to use:
- Current - Any security context. This is the default if you don't specify this property in a configuration document.
- Elevated - Elevated as root or an administrator.
- Restricted - Not elevated as root or an administrator.
For example, the following metadata at the top of a configuration document indicates that DSC must run as a normal user account, not root or administrator:
```
metadata:
  Microsoft.DSC:
    securityContext: restricted
```
For more information, see DSC Configuration document metadata schema.
Related work items
- Issues: #258
- PRs: #351
Added the option to define a JSON input argument for resource commands. When you define the args list for the following commands, you can now define a special argument that the command expects to receive the compressed JSON data for:
- delete
- export
- get
- set
- test
- validate
DSC sends data to these commands in three ways:
1. When input is stdin, DSC sends the data as a string representing the data as a compressed JSON object without spaces or newlines between the object properties.
2. When input is env, DSC sends the data as environment variables. It creates an environment variable for each property in the input data object, using the name and value of the property.
3. When the args array includes a JSON input argument definition, DSC sends the data as a string representing the data as a compressed JSON object to the specified argument.
If you don't define the input property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.

You must define the input property, one JSON input argument in the args property array, or both. For more information, see the relevant schema documentation for the command property.
Related work items
- Issues: #218
- PRs: #385
Added configuration functions:
- New mathematics functions include add(), div(), max(), min(), mod(), mul(), and sub(). The mathematics functions only operate on integer values.
- The reference() function enables you to reference the result output for other resources, so you can use properties of one resource instance as values for another. The reference() function only works for resources that DSC has already managed in a configuration. You should always add the resource you're referencing with the reference() function to the dependsOn list for the instance using the reference.
- The createArray() function enables you to create arrays of a given type from values.
- The int() function enables you to convert strings and numbers with fractional parts into integers.
Related work items
- Issues:
  - #57
- PRs:
  - #347
  - #349
  - #352
  - #353
  - #354
  - #360
  - #361
  - #375
  - #376
Added the kind property to the resource manifest schema and the output for the dsc resource list command. This property indicates whether the resource is a group resource (Group), an adapter resource (Adapter), or neither (Resource). For more information, see DSC Resource kind schema reference.

This property is mandatory in the resource manifest for group resources. If your resource manifest doesn't define the kind property, DSC can infer whether the resource is an adapter resource or not. Microsoft recommends always explicitly defining this property in resource manifests, because the schema can apply enhanced validation based on the value of the kind property.
Related work items
- Issues: #139
- PRs: #338
Added the capabilities property to the output for the dsc resource list command. The capabilities property indicates how you can use the DSC Resource and how DSC and other higher order tools should handle it.
Related work items
- Issues: #356
- PRs: #357
Added the metadata property to the outputs for dsc config and dsc resource subcommands. This property in the output defines the context DSC was run under and information about the operation. See the output reference for each command for more information:
Related work items
- Issues: #401
- PRs: #405
Added parsing for configuration functions in the default values of parameters. Prior to this release, DSC interpreted configuration functions in parameter default values as literal strings.
Related work items
- Issues: None.
- PRs: #364
Added type validation for parameter default values. Prior to this release, DSC didn't validate that the default value for a parameter was valid for the parameter's type.
Related work items
- Issues: None.
- PRs: #364
Added support for resources to send trace information to DSC during command execution. DSC Resources can emit JSON objects to stderr. If the object has a property in the following list with a string value, DSC interprets the emitted object as a message of the matching level: Error, Warning, Info, Debug, Trace.

For example, DSC would interpret a resource emitting the following JSON to stderr as a warning:
```
{"Warning":"Unable to access remote store, using cached local package data only"}
```
DSC emits these messages along with its own messages when the specified trace level for the command is equal to or lower than the message's level.

For more information about trace levels, see the --trace-level option for the dsc root command.
Related work items
- Issues: #89
- PRs: #287
Added validation to ensure resources return data for their instances that is valid against their own instance JSON schema. Prior to this release, the return data wasn't validated.
Related work items
- Issues: #251
- PRs: #362
Added multi-line progress bars for the dsc resource list command to provide feedback to interactive users about the resource discovery process. Prior to this release, the command executed silently.
Related work items
- Issues: None.
- PRs: #323
Added functionality to insert metadata for adapter resources to indicate if the incoming data is for a configuration instead of direct resource invocation. Prior to this release, adapters had no way of discerning between a single-instance call for a configuration and a direct resource invocation.

With this change, DSC inserts the following into the data object sent to the adapter during a dsc config command:
```
"metadata": {
  "Microsoft.DSC": {
    "context": "Configuration"
  }
}
```
Adapters can then check whether this value is set in the input data and handle it as-needed.
Related work items
- Issues: #253
- PRs: #348
Added the Microsoft.Windows/RebootPending resource, which checks whether a Windows machine has a pending reboot. It can only be used for assertions, not to enforce state.
Related work items
- Issues: #333
- PRs: #344
Added the Microsoft.DSC.Transitional/RunCommandOnSet resource, which runs a specified executable or script with given arguments during a set operation. This resource is intended as a temporary transitional resource while migrating to DSCv3 and implementing resources for your needs.
Related work items
- Issues: #302
- PRs: #321

v3.0.0-alpha.5 - 2024-02-27

This section includes a summary of changes for the alpha.5 release. For the full list of changes in this release, see the diff on GitHub.

Changed

Updated the options for the dsc root command:
- Removed the global --format option, which controls the output format. Now, the relevant subcommands that return formattable output have the --format option (short option as -f) added to them.
- Removed the global --input and --input-file options. Now, the config subcommands have the --document and --path options for specifying the configuration document as a string or from a file. The relevant resource subcommands have the --input and --path options for specifying the instance properties as a string or from a file.
- The --logging-level option is renamed to --trace-level with the short name -l. The default trace level is now warning instead of info.
- Added the --trace-format option with the -f short name. This option enables you to choose the format for the trace messages emitted to stderr. By default, the messages are emitted as lines of text with console colors. You can set this option to plaintext to emit the messages without console colors or to json to emit the messages as JSON objects.
  
  The trace messaging is also updated to only emit source files and line numbers for the debug and trace levels.
Related work items
- Issues:
  - #286
  - #227
  - #226
- PRs:
  - #299
  - #303
  - #305
  - #388
Updated the JSON schemas for the get, set, and test output data. This change corrects an issue with how DSC surfaced information about instances nested inside group and adapter resources. Now when you review the output, you'll be able to see the results for each nested instance instead of a confusing object that loses the nested instance type and name information.

This schema change is backwards compatible.
Related work items
- Issues:
  - #165
  - #266
  - #284
- PRs: #318
Changed the concat configuration function to match the behavior of the ARM template function. The concat() function now only accepts strings or arrays of strings as input values. It raises an error if the input values are not of the same type.
Related work items
- Issues: #271
- PRs: #322

Added

Implemented support for referencing parameters in a configuration with the parameters() configuration function. This enables you to take advantage of parameterized configurations. Until this release, you could define but not reference parameters.

Now, you can use the --parameters and --parameters-file options with the dsc config commands to pass values for any parameter defined in the configuration document.
Related work items
- Issues: #49
- PRs:
  - #291
  - #294
Added support for authoring DSC Resource manifests in YAML. DSC now recognizes resource manifests that use the .dsc.resource.yml or .dsc.resource.yaml file extension instead of only .dsc.resource.json.
Related work Items
- Issues: #129
- PRs: #311
Added the DSCConfigRoot environment variable and the envvar() configuration function to enable users to reference files and folders relative to the folder containing the configuration document. DSC automatically and only creates the DSCConfigRoot environment variable when you use the --path option to specify the configuration document instead of passing the document as a string from stdin or with the --document option.

[!NOTE] In this release, DSC doesn't expand the specified path to an absolute path. You should always specify the full path to the configuration document if you want to reference the DSCConfigRoot variable in your configuration. Further, DSC always sets the value for this environment variable when you use the --path option. If the environment variable is already set, it overrides it silently.

In a future release, the variable will be renamed to DSC_CONFIG_ROOT and DSC will automatically expand relative paths into absolute paths when setting the environment variable. It will also emit a warning when it overrides the variable.
Related work Items
- Issues: #75
- PRs: #313
Added support for using the dsc config export and dsc resource export commands with the PowerShell adapter resource. PSDSC resources can now participate in the export command if they define a static method that returns an array of the PSDSC resource class.
Related work Items
- Issues: #183
- PRs: #307
Added the methods column to the default table view for the console output of the dsc resource list command. This new column indicates which methods the resource explicitly implements. Valid values include get, set, test, and export. This information is only available in the table view. It isn't part of the output object for the command. If you use the --format parameter, capture the command output, or redirect the output, the methods information isn't included.

Resources that don't implement test rely on DSC's synthetic test behavior instead. They can still be used for test and set operations.

Resources that don't implement export can't be used with the dsc config export or dsc resource export commands.

Resources that don't implement set can be used for auditing, but not dsc resource set. They can be used with the dsc config set command, but only if they're nested inside a DSC/AssertionGroup instance.
Related work Items
- Issues: #309
- PRs: #314
Added an prototype for a WMI resource adapter to enable users to query WMI. The adapter is disabled by default, as enumerating the WMI resources can have a performance impact. To enable it, rename the resource manifest from wmigroup.dsc.resource.json.optout to wmigroup.dsc.resource.json.
Related work Items
- Issues: #263
- PRs: #279

v3.0.0-alpha.4 - 2023-11-14

This section includes a summary of changes for the alpha.4 release. For the full list of changes in this release, see the diff on GitHub.

Changed

Updated the canonical version of the schema URIs from 2023/08 to 2023/10, as this release includes breaking changes for the schemas.

As part of this change, the $schema keyword for both configuration documents and resource manifests accepts any valid URI for the schemas, instead of only one. Now, you can set the value for the keyword to the unbundled schema, the bundled schema, or the enhanced authoring schema for any supported version.
Replaced the _ensure well-known property with the boolean _exist property. This improves the semantics for users and simplifies implementation for resources, replacing the string enum values Present and Absent with true and false respectively.
Related work items
- Issues: #202
- PRs: #206
Updated the Microsoft.Windows/Registry resource to use the _exist property instead of _ensure and updated the output to be idiomatic for a DSC Resource.
Related work items
- Issues: #162
- PRs: #206
When a user presses the Ctrl+C key combination, DSC now recursively terminates all child processes before exiting. This helps prevent dangling processes that were previously unhandled by the interrupt event.
Related work items
- PRs: #213

Added

Added the --input and --input-file global options to the root dsc command. Now, you can pass input to DSC from a variable or file instead of piping from stdin.
Related work items
- Issues: #130
- PRs: #217
Added the arg value as an option for defining how a command-based DSC Resource expects to receive input. This enables resource authors to define resources that handle DSC passing the instance JSON as an argument.
Related work items
- PRs: #213
Added the new completer command enables users to add shell completions for DSC to their shell. The command supports completions for Bash, Elvish, fish, PowerShell, and ZSH.
Related work items
- Issues: #186
- PRs: #216
DSC now emits log messages to the stderr stream. This can make it easier to understand what DSC is doing. This doesn't affect the data output. By default, DSC emits errors, warnings, and informational messages, but not debug or trace messaging. You can control the level of the logging with the new --logging-level option on the root dsc command.
Related work items
- Issues:
  - #107
  - #158
- PRs:
  - #211
  - #248
Added optimizations for the resource discovery process that runs before most dsc commands. These optimizations significantly reduce the command execution duration, especially for the dsc resource * commands, which rarely need to run a full discovery for resources.
Related work items
- Issues: #173
- PRs: #240
Added initial configuration document functions to DSC. You can now use the base64(), concat(), and resourceId() functions in the configuration document.

[!NOTE] The resourceId function has been reimplemented as a document function instead of a special case, but it has the same functionality and parameters.
Related work items
- Issues: #57
- PRs:
  - #241
  - #252

Fixed

The --format option now works as users expect when the output is redirected or saved to a variable. Before this fix, DSC always returned JSON output, even when the user wanted to save the output as YAML. With this fix, the specified format is respected.
Related work items
- PRs: #215
The DSC/PowerShellGroup resource now correctly returns the labels for enumerations instead of their integer value, making it easier to understand and compare results.
Related work items
- Issues: #159
- PRs: #208
DSC no longer terminates during discovery when a resource errors unless the erroring resource is being used for the command. DSC still terminates on a resource error during discovery under the following conditions:
- When the erroring resource type is the same as the value of the --resource option for a dsc resource * command.
- When an instance in the configuration document uses the erroring resource type for a dsc config * command.
DSC emits the resource errors during discovery as warning messages for the dsc resource list command. In all other cases, DSC emits the errors as debug messages.
Related work items
- Issues: #121
- PRs: #240

v3.0.0-alpha.3 - 2023-09-26

This section includes a summary of changes for the alpha.3 release. For the full list of changes in this release, see the diff on GitHub.

Changed

Replaced the manifestVersion property for resource manifests with $schema. Instead of specifying a semantic version, resources need to indicate which canonical schema DSC should use to validate and process the manifest.
Related work items
- Issues: #127
- PRs: #199
Updated the preTest property for the set command in resource manifests to implementsPretest to more make the manifest easier to read and understand.
Related work items
- PRs: #197
The dsc resource set command no longer tests the resource instance before invoking the set operation. This simplifies the behavior for the command and adheres more accurately to the implied contract for directly invoking a resource with DSC.
Related work items
- Issues: #98
- PRs: #197
Replaced the args option with env for defining how a command-based resource expects to receive input for the get, set, and test commands in the resource manifest.

The args option was never implemented. Instead, resource authors can set the input property to env to indicate that the resource expects input as environmental variables.
Related work items
- PRs: #198
The input property for the get command in a resource manifest no longer has a default value. Instead, when a resource doesn't define input for the get command, DSC doesn't send any input to the resource for that command.
Related work items
- PRs: #198

v3.0.0-alpha.2 - 2023-09-05

This section includes a summary of changes for the alpha.2 release. For the full list of changes in this release, see the diff on GitHub.

Changed

The $schema value for configuration documents now points to the canonical published schema URI, https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json.
Related work items
- PRs: #156

Added

Implemented functionality for the dependsOn property of resource instances in configuration documents, enabling resource instances to depend on the successful processing of one or more other instances in the document.
Related work items
- Issues: #45
- PRs: #175
Added the export property to the resource manifest schema, indicating that the resource is exportable and defining how DSC can retrieve the current state for every instance of the resource.
Related work items
- Issues: #73
- PRs: #171
Added the dsc config export command to convert an input configuration document defining a list of resource types into a usable configuration document that defines the current state for every instance of those resources.
Related work items
- Issues: #73
- PRs: #171
Added the dsc resource export command to generate a usable configuration document that defines the current state for every instance of a specified resource.
Related work items
- Issues: #73
- PRs: #171
Added the --all option for the dsc resource get command, enabling users to retrieve the current state for every instance of an exportable resource with a single command.
Related work items
- Issues:
  - #73
  - #174
- PRs: #171
Added handling for the Ctrl+C key combination to cancel a DSC operation. When dsc cancels an operation due to this key-press, it indicates that the operation was cancelled with exit code 6.
Related work items
- PRs: #177
- Issues: #150
Added support for using the DSC_RESOURCE_PATH environment variable to define a list of folders to search for command-based DSC Resource manifests. When DSC_RESOURCE_PATH is defined, DSC searches those folders for resources and ignores the PATH variable for resource discovery.
Related work items
- PRs: #176
- Issues: #133
The DSC/AssertionGroup, DSC/Group, and DSC/ParallelGroup resources now define semantic exit codes in their manifests. These resources now indicate that they use the same exit codes as the dsc command.
Related work items
- PRs: #182
- Issues: #181
Added type validation in the schema for the defaultValue and allowedValues properties of configuration document parameters to improve the authoring experience. Now, when a parameter defines values for these properties that are incompatible with the defined data type, validation raises an error indicating that the values are invalid and why.
Related work items
- PRs: #172
Enhanced VS Code-specific schemas for configuration documents and resource manifests to improve the authoring experience. The enhanced schemas use keywords only supported by VS Code to:
- Render Markdown help information for properties and enums.
- Provide contextual error messages when a value fails pattern validation.
- Define default snippets to autocomplete values.
These schemas are non-canonical and should only be used for authoring. For more information, see Authoring with enhanced schemas.
Related work items
- PRs: #172
Documentation to the Microsoft/OSInfo resource instance schema and command-line tool to provide contextual help about the properties the resource can validate.
Related work items
- PRs: #168

Fixed

The data-type conditionals for the configuration parameters schema so that the min* and max* keywords apply to the correct data types. Previously, the logic prevented them from ever applying.
Related work items
- PRs: #172
Using the registry find command no longer raises a panic error due to conflicting option definitions on the command.
Related work items
- PRs: #163

v3.0.0-alpha.1 - 2023-08-04

This is the first public release of DSC v3. Consider this release alpha quality. Use it only for development evaluation, as it has known issues and isn't feature complete.

For the full list of changes in this release, see the diff on GitHub.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CHANGELOG.md

CHANGELOG.md

Changelog

Unreleased

v3.0.0-preview.7 - 2024-04-22

Changed

Added

v3.0.0-alpha.5 - 2024-02-27

Changed

Added

v3.0.0-alpha.4 - 2023-11-14

Changed

Added

Fixed

v3.0.0-alpha.3 - 2023-09-26

Changed

v3.0.0-alpha.2 - 2023-09-05

Changed

Added

Fixed

v3.0.0-alpha.1 - 2023-08-04

Files

CHANGELOG.md

Latest commit

History

CHANGELOG.md

File metadata and controls

Changelog

Unreleased

v3.0.0-preview.7 - 2024-04-22

Changed

Added

v3.0.0-alpha.5 - 2024-02-27

Changed

Added

v3.0.0-alpha.4 - 2023-11-14

Changed

Added

Fixed

v3.0.0-alpha.3 - 2023-09-26

Changed

v3.0.0-alpha.2 - 2023-09-05

Changed

Added

Fixed

v3.0.0-alpha.1 - 2023-08-04