Skip to content

Latest commit

 

History

History
1848 lines (1341 loc) · 72.6 KB

CHANGELOG.md

File metadata and controls

1848 lines (1341 loc) · 72.6 KB
Raw
title description ms.topic ms.date
Desired State Configuration changelog
A log of the changes for releases of DSCv3.
whats-new
06/24/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.9 - 2024-08-15

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

Removed

  • Removed the url sub-property from the schema property in resource manifests. Starting with this release, resources must either embed their instance property JSON schema in the manifest or define the command that returns the JSON schema for validation.

    Related work items
    • Issues: None.
    • PRs: #457

Changed

  • Changed the invocation for resources from synchronous to asynchronous. Starting with this release, resource invocations are handled asynchronously. This reduced errors related to processing and laid the groundwork for real-time progress reporting.

    Related work items

  • Changed the import resource type to function as a group resource. This resource instances resolved from import to be used correctly for all operations.

    Related work items
    • Issues: None.
    • PRs: #500

  • Changed the inserted property indicating the fully qualified type for an adapted resource from type to adapted_dsc_type. Prior to this release, DSC forwarded the information about adapted resource instances to the adapters by inserting the type property into the property bag for the instance, which had the potential to cause conflicts with actual resource properties named type. This change reduces the probability of conflicts by renaming the inserted property to the more explicit adapted_dsc_type.

    Related work items
    • Issues: None.
    • PRs: #482

Added

  • Added support for using variables in a configuration document. Prior to this release, variables could be defined in the document but not referenced from resource instances with a configuration function. This release includes the new variables() configuration function. For more information, see the reference documentation.

    Related work items

  • Added support for indexing into arrays when using configuration functions. This enables users to access specific items in an array of values returned by a configuration function, such as whe referencing the output of a resource. For more information about configuration functions, see DSC Configuration document functions reference. For a detailed example showing how to access items in an array, see Example 4.

    Related work items

  • Added handling to ensure that the folder containing dsc is always searched for resources. This enables users to find and use built-in resources without manually updating their PATH environment variable. This change has no effect when the DSC_RESOURCE_PATH environment variable is defined.

    Related work items

  • Added support for PSDSC resources defined as derived classes. Prior to this release, the adapter didn't support invoking derived classes as resources.

    Related work items

  • Added the option to clear the PowerShell adapter caches with the ClearCache operation. Prior to this release, the caches needed to be cleared manually.

    Related work items
    • Issues: None.
    • PRs: #468

  • Improved reliability of the PowerShell adapter caches. Starting with this release, the adapter caches include a property defining the version of the caching logic they use. If the adapter caching version doesn't match the property of the cache, the adapter rebuilds it with the new version. This enables updating the caching logic in new releases.

    Related work items
    • Issues: None.
    • PRs: #468

  • Added support for the WhatIf capability to the Microsoft.Windows/Registry resource, improving the user experience when calling dsc config set with the --what-if option.

    Related work items

  • Added handling for when dsc is launched from Explorer or the Microsoft Store. Starting with this release, when dsc is launched from the Microsoft Store application or Explorer, it shows a message linking users to the documentation and waits for a key press before exiting.

    Related work items
    • Issues: None.
    • PRs: #481

  • Improved performance for the PowerShell adapter caching by immediately invalidating the cache when the cache timestampe entries are stale or missing instead of checking each module in the cache.

    Related work items
    • Issues: None.
    • PRs: #497

Fixed

  • Fixed a bug in the Microsoft.Windows/PowerShell adapter causing it to always invoke the Get operation.

    Related work items

  • Fixed a bug in the PowerShell adapters that caused errors when it discovered multiple modules with the same name. Starting with this release, the adapter chooses the version of the module with the latest version.

    Related work items

  • Fixed the error messaging when DSC doesn't get any input for a Test operation to clearly indicate the problem. Prior to this release, users received a difficult-to-decipher message about an unexpected end of file instead.

    Related work items

  • Fixed the behavior when a user specifies an invalid name or wildcard filter when calling dsc resource list with the --adapter option. Prior to this release, DSC returned no data. Starting with this release, DSC writes a message to STDERR indicating that no adapter was found. The operation still exits with exit code 0.

    Related work items

  • Fixed the PowerShell adapters to correctly handle cache updates when a module containing resources is deleted externally.

    Related work items

  • Fixed the PowerShell adapters to return a clear error message when a user attempts to call the Export operation on an adapted resource that doesn't support it.

    Related work items

v3.0.0-preview.8 - 2024-06-19

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

Changed

  • Changed the Microsoft.DSC/PowerShell adapter to only handle PowerShell DSC Resources implemented as classes and remove the dependency on the PSDesiredStateConfiguration module. The Microsoft.Windows/WindowsPowerShell adapter continues to work with classic PSDSC resources. Neither adapter supports composite PSDSC resources. This change simplified the code and coincided with ensuring that the Microsoft.DSC/PowerShell adapter works correctly on Linux and macOS as well as Windows. This change also brought performance improvements to the adapter, speeding up resource invocation and discovery.

    Related work items

Added

  • Added the --what-if (-w) option to the dsc config set command. When you call dsc config set with the --what-if option, DSC doesn't actually invoke the resources to enforce the desired state. Instead, it returns the expected output for the command, showing the before and after state for each resource instance.

    The output for the dsc config set operation with the --what-if operation is the same as an actual configuration set operation, except that the metadata field executionType is set to WhatIf instead of Actual.

    By default, the generated output is synthetic, based on the results of the resources' test operation. Resources can define the whatIf property in their resource manifest to participate in what-if operations, reporting more specifically how they will change the system. For example, participating resources could indicate whether an actual set operation will require a reboot or whether the current user has the correct permissions to manage that resource instance.

    Participating resources have the WhatIf capability.

    Related work items

  • Added support for importer resources. These resources resolve external sources to a nested DSC Configuration document. The resolved instances are processed as nested resource instances.

    This required some updates to the schemas, all backwards-compatible:

    • Added a new resourceKind named Import.
    • Added the resolve command to resource manifests.
    • Added the new Resolve capability, returned in the output for the dsc resource list command when DSC discovers an importer resource.
    Related work items

  • Added the Microsoft.DSC/Include importer resource to resolve instances from an external configuration document. The resolved instances are processed as nested instances for the Microsoft.DSC/Include resource instance.

    You can use this resource to write smaller configuration documents and compose them as needed. For example, you could define a security baseline and a web server configuration separately, then combine them for a given application:

    $schema: &schema https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
resources:
# Group of included baseline configurations
- name: Baselines
  type: Microsoft.DSC/Group
  properties:
    $schema: *schema
    resources:
    - name: Security Baseline
      type: Microsoft.DSC/Include
      properties:
        configurationFile: security_baseline.dsc.yaml
        parametersFile:    security_baseline.parameters.yaml
    - name: Web Server Baseline
      type: Microsoft.DSC/Include
      properties:
        configurationFile: web_baseline.dsc.yaml
        parametersFile:    web_baseline.parameters.yaml
      dependsOn:
        - "[resourceId('Microsoft.DSC/Include', 'Security Baseline')]"

# application configuration instances, all depend on the baselines
- name: Application configuration
  type: MyApp/Settings
  properties:
    someSetting: someValue
  dependsOn:
    - "[resourceId('Microsoft.DSC/Group', 'Baselines')]"
    Related work items

  • Added caching for PowerShell Desired State Configuration (PSDSC) resources when using the Microsoft.DSC/PowerShell and Microsoft.Windows/PowerShell adapters. The adapters use the cache to speed up resource discovery. The performance improvement reduced the resource list time under tests from eight seconds to two seconds, and reduced invocation operation times by half.

    The adapters cache the resources in the following locations, depending on your platform:

    Adapter Platform Path
    Microsoft.DSC/PowerShell Linux $HOME/.dsc/PSAdapterCache.json
    Microsoft.DSC/PowerShell macOS $HOME/.dsc/PSAdapterCache.json
    Microsoft.DSC/PowerShell Windows %LOCALAPPDATA%\dsc\PSAdapterCache.json
    Microsoft.Windows/PowerShell Windows %LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json

    The adapters check whether the cache is stale on each run and refresh it if:

    • The PSModulePath environmental variable is updated.
    • Any module is added or removed from the PSModulePath.
    • Any related files in a cached PSDSC resource module has been updated since the cache was written. The adapter watches the LastWriteTime of module files with the following extensions: .ps1, .psd1, .psm1, and .mof.
    Related work items

  • Added the DSC.PackageManagement/Apt resource for managing software on systems that use the advanced package tool (APT). In this release, you can use the resource to:

    • Install the latest version of a package.
    • Uninstall a package.
    • Get the current state of a package.
    • Export every installed package as a DSC resource instance.
    Related work items
    • Issues: None.
    • PRs: #434

  • Added the Microsoft.DSC.Experimental/SystemctlService class-based PSDSC resource. It has the Get and Export capabilities. You can use it on Linux systems that manage services with SystemD and systemctl. In this release, it doesn't support setting services.

    Related work items
    • Issues: None.
    • PRs: #454

Fixed

  • Fixed the JSON Schema for exit codes in the resource manifest to support negative integers. Prior to this release, the DSC engine supported negative exit codes but the JSON Schema forbid them.

    Related work items

  • Fixed the behavior of the int() configuration function to error when given an input value other than a string or integer. Prior to this release, when you specified a number with a fractional part as input for the function, it coerced the input value to an integer representing the fractional part. Starting with this release, the int() function raises an invalid input error when the input value isn't a string or an integer.

    Related work items

  • Fixed the implementation to retrieve non-zero exit code descriptions for resource errors from the resource manifest, if defined. Prior to this release, these error descriptions weren't surfaced.

    Related work items

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:

    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

  • 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

  • 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

  • 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

  • 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

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

  • 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

  • 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:

    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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

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

  • 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

  • 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

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

  • 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

  • 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

  • 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

  • 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

  • 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

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

  • 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

  • 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

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

  • 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

  • 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

  • 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

  • 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

  • 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

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

  • 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

  • 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

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

  • 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

  • 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

  • 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

  • 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

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

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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

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

  • Using the registry find command no longer raises a panic error due to conflicting option definitions on the command.

    Related work items

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.