Add a Write-Only / Parameter Attribute for the DscProperty attribute

[michaeltlombardi]

As an engineer responsible for using and integrating with DSC Resources, I want to be able to learn from the metadata about a DSC Resource's property if it can/should be passed to the resource but not expected to be returned from the resource.

There is, currently, no way in DSC to distinguish between values that can be passed to the Resource but not retrieved from it and those that can. The most common example of this type of property is a credential, but others typically exist to be used when a resource is created, to confirm boundaries, or to enforce set-time behavior.

The problem with not being able to distinguish between parameters (writable, not readable) and properties (writable and readable) surfaces particularly with integration tools. The only things those tools know about a DSC Resource is what the DSC Resource reports and, without a way to report that a value should not be expected to be read back, they have no way of knowing if something went silently wrong or a null value is correct behavior.

I propose that a new attribute be added to the list of existing attributes (Key, Mandatory, and NotConfigurable) for the [DscProperty()] attribute used to declare a class property as a DSC Resource property, called Parameter, NotReturnable, WriteOnly, or something similar (in descending preference order). This attribute should be used to declare that the property can be passed to a resource but never read back from it. It should be usable in conjunction with the existing Mandatory attribute.

While there is some nuance in whether or not there should be distinction at this level for whether the object can/should be passed to Get as well as Set and Test (e.g. a Force switch may not make sense for all three but a credential object might), that's worth considering more broadly and independent of the need for this information in the API surface of DSC Resources.

Contextual Examples

Install-Time Parameters

Examples of parameter properties used in creation are install switches and the location of source files when installing a package for the first time; there's no way to read these values back from an extant resource.

The SqlServerDsc/SqlRSSetup DSC Resource has numerous install switches - IAcceptLicenseTerms, SourcePath, SupressRestart, SourceCredential, ProductKey, ForceRestart, EditionUpgrade, VersionUpgrade, Edition, LogPath, and SetupProcessTimeout. These are runtime options that can't be read back from an installed instance but the API surface of a DSC Resource has no way to describe them as such - they're all listed as writable properties.

The Notes section of the implementation even calls out that ProductKey and Edition can't be returned from the system:

<#
    .NOTES
        The following properties are always returning $null because it's currently
        unknown how to return that information.
          - ProductKey
          - Edition
        The following properties always return $null on purpose. This could be
        changed in the future.
          - Action
          - SourceCredential
          - ForceRestart
          - EditionUpgrade
          - VersionUpgrade
          - LogPath
#>

Boundary Declaring Parameters

An example of parameter properties used as boundaries are version limiters - while a DSC Resource can report the current version of a DSC Resource, the minimum and maximum version boundaries exist as configuration options but not in the managed resource itself.

The PowerShellGet/PSModule DSC Resource (in v2) uses the RequiredVersion, MaximumVersion, and MinimumVersion DSC Properties (with the Write attribute) to determine the desired version range for a module, but the Get implementation simply passes these values from the caller to the output because they can't be retrieved from the system:

    $returnValue = @{
        Ensure             = 'Absent'
        Name               = $Name
        Repository         = $Repository
        Description        = $null
        Guid               = $null
        ModuleBase         = $null
        ModuleType         = $null
        Author             = $null
        InstalledVersion   = $null
        RequiredVersion    = $RequiredVersion
        MinimumVersion     = $MinimumVersion
        MaximumVersion     = $MaximumVersion
        Force              = $Force
        AllowClobber       = $AllowClobber
        SkipPublisherCheck = $SkipPublisherCheck
        InstallationPolicy = $null
    }

Behavior Enforcing Parameters

An example of enforcing set-time behavior is the use of a Force switch parameter (for non-class-based Resources) or boolean property (for class-based Resources).

The SqlServerDsc/SqlAGDatabase DSC Resource uses the Force parameter for Set operations to "ensure the specified database(s) are the only databases that are a member of the specified Availability Group." In the implementation, the return object for Get sets the Force property to $false and does not update it from the system (because it can't):

    $currentConfiguration = @{
        DatabaseName          = @()
        ServerName            = $ServerName
        InstanceName          = $InstanceName
        AvailabilityGroupName = ''
        BackupPath            = ''
        Ensure                = ''
        Force                 = $false
        MatchDatabaseOwner    = $false
        ReplaceExisting       = $false
        IsActiveNode          = $false
    }

Integration Example

I ran into this particularly when writing Puppet.Dsc and ended up having to maintain a utility function to check if a property was defined as a credential or its name matched a hard-coded list of properties which were never returned in a Get request, i.e.

  $KnownParameters = @(
    'Force'
    'JoinOU'
    'KeyUsage'
    'OID'
    'Purge'
    'Validate'
  )

  $Property.Name -in $KnownParameters -or $Property.ReferenceClassName -match 'Credential'

[kilasuit]

I like this idea and do think it would be a good addition 🙂