Idempotency and dsc executable default behavior

[jchancellor-ms]

Summary of the new feature / enhancement

The documentation seems to indicate that it is necessary to wrap the dsc executable in some other scripting language to manage idempotency.

As an automation user I want to write a desired state configuration file and then be able to run the dsc command repeatedly and only have the values set command run if any resource in the config returns non-compliant. (i.e the set action performs both a test and set as needed)

This allows me to include only the command/config action as a single step in a bootstrap script without having to manage the idempotency outside the resource. The resource definition should include get/set/test/schema and any error handling. This also eliminates the need for the developer to worry about how the resource provider does error handling, retry testing, and etc as the resource provider and the dsc executable should manage those elements.

Proposed technical implementation details (optional)

A sample config file will contain the resource type, version, and desired state details. (using the registry resource from the doc page)

`#example.dsc.config.yaml $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json resources:

• name: test_key type: Microsoft.Windows/Registry properties: keyPath: HKLM\Software\testkey\testproduct\1.0 valueName: testvalue valueData: String: testvalue`

when run for the first time and the key doesn't exist, the key and value will be created :

key doesn't exist

dsc set -config example.dsc.config.yaml

Script created the key

When run again the test will evaluate as true and no changes will take place. (no external wrapper script testing or handling will be necessary)

key does exist

dsc set -config example.dsc.config.yaml

Script exits without performing any actions as the test call succeeded

[michaeltlombardi]

@jchancellor-ms - The documentation you linked is for managing the registry with the dsc resource set command. The dsc resource set documentation states:

[!IMPORTANT] The dsc resource set command always invokes the set operation for the resource. Resources may, but aren't required to, implement logic that pretests an instance for the set operation.

This is different from how dsc config set works, where DSC always tests an instance, either synthetically or by invoking the test operation for the resource, and only invokes set for an instance if it's not in the desired state.

Command-based resources indicate whether they implement pretest for the set operation by defining the set.implementsPretest property in their resource manifest. If that property is defined as true, it indicates that the resource implements pretest. If set.implementsPretest is set to false or is undefined, the manifest indicates that the resource doesn't implement pretest.

If a resource indicates that it implements pretest, users should expect that the resource only modifies an instance during a set operation if the pretest shows that the instance isn't in the desired state.

If a resource doesn't implement pretest, users should expect that the resource always modifies an instance during a set operation.

For resources that don't implement pretest for the set operation, Microsoft recommends always calling dsc resource test against an instance to see whether it's in the desired state before invoking dsc resource set. This can help avoid accidental errors caused by resources that don't implement a fully idempotent set command.

What you're asking for is implemented with the dsc config set command. You can see an example of managing the registry with the dsc config * commands in Configure keys and values with Microsoft.Windows/Registry