DSC icon indicating copy to clipboard operation
DSC copied to clipboard

`_clobber` support for properties that are arrays and prepending vs appending

Open SteveL-MSFT opened this issue 7 months ago • 0 comments

Summary of the new feature / enhancement

Currently, _clobber only applies to the entirety of the settings. So if you only specify one setting and _clobber = true, then all other settings are removed (effectively reverting to defaults).

Note that _clobber is always false when not specified.

However, there are cases particularly working with properties that are arrays where you want to:

  • Append
  • Prepend
  • Remove

Proposed technical implementation details (optional)

We want to keep it simple for resource authors, so we don't want to inject DSC canonical properties like _clobber within the array. Instead, I think we can modify _clobber to accept a boolean or an array (since it doesn't make sense to clobber both the entire set of settings and not the array property):

# this will overwrite all the settings and only explicitly set 1 setting, the rest would revert to defaults
resources:
  - name: clobber example
    type: foo/bar
    properties:
      _clobber: true
      foo: bar

Specifying for an array property would look like:

# this will clobber array1 but not array2
resources:
  - name: clobber example
    type: foo/bar
    properties:
      _clobber:
        listedArrayProperties:
          - array1
      array1:
        - one
        - two
      array2:
        - three

In the case for prepend, append, and removing elements in an array, it may make sense to have them in the metadata section:

metadata:
  Microsoft.DSC:
    arrayProperties:
      prepend:
        - array1
      append:  # append is default when not specified and not clobber
        - array2
      remove:  # seems too forced to call this _exist, but maybe?
        - array3
resources:
  - name: array example
    type: foo/bar
    properties:
      array1:
        - addToFront
      array2:
        - addToEnd
      array3:
        - removeElement # should work like _exist, so no error if it already doesn't exist

It may make sense to allow for _clobber in metadata, but we would still need to support the current syntax, but both can't be specified.

SteveL-MSFT avatar May 08 '25 18:05 SteveL-MSFT