Summary of the new feature / enhancement

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

Note that _purge 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 _purge within the array. Instead, I think we can modify _purge 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:
      _purge: true
      foo: bar

Specifying for an array property would look like:

# this will purge array1 but not array2
resources:
  - name: purge example
    type: foo/bar
    properties:
      _purge:
        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 _purge in metadata, but we would still need to support the current syntax, but both can't be specified.