Add support for passing properties to Invoke-DscResource as JSON

[michaeltlombardi]

As an integrations engineer and operator, I want to be able to pass a JSON object to Invoke-DscResource without having to manually translate between datatypes.

Context

As an engineer responsible for integrating with DSC, I had to write and maintain a translation layer between my software's hash table syntax and PowerShell's for input; for output, we can rely on converting to JSON in PowerShell and from JSON in the calling language, but the support for JSON input was relatively lacking, particularly given the need to cast values to the appropriate data types.

In order to build the hash table to splat on Invoke-DscResource, I needed to first inspect the user-specified properties for credentials to create, then do the same for CIM instances, and then assemble the parameter block (snippets below). Only then could I hand the assembled parameter block off to Invoke-DscResource.

While this was doable it was a lot of work and similar practices are necessary by any other integrating vendors to transform the key-value pairs for a DSC Resource's configuration items in their own DSL (or from YAML or JSON) to valid values.

Creating Credentials

Source. Creating credentials required using a private function in PowerShell to create a just-in-time credential object to pass in the parameter hash. Credentials had to be handled first in case they were needed by CIM instances.

Creating CIM Instances

Source. Similarly to credentials, though much more complex, CIM instances needed to be created directly before the parameter block could be assembled, working from most-nested instance to least so they could be created.

Creating the Parameter Block

Source. Finally, assembling the parameter block required metaprogramming to cast values to the correct PowerShell type effectively so they could be used by the DSC Resource; neither DSC nor the DSC Resources themselves had any way to transform incoming values beyond attempting a simple cast (which would fail for the majority of non-simple types).

Proposal

I propose that Invoke-DscResource be updated so that a user could get JSON somehow and pipe it to Invoke-DscResource or pass it directly with a parameter (such as JsonProperties). For example:

# These commands would be theoretically identical
$InvocationJson | Invoke-DscResource -Method Get -Name Foo -ModuleName Bar
Invoke-DscResource -Method Get -Name Foo -ModuleName Bar -JsonProperties $InvocationJson

This would require some way to handle casting the values appropriately and returning a sensible error when they can't be; but given a requirement to type all of the DSC Resource properties, this seems possible, though it may require special handlers for data types which can't be simply cast (such as credentials).

Special handlers might look similar to argument transformers more generally.

Two possible implementations are:

1. Invoke-DscResource looks to find the appropriate DSC Resource based on the specified Name and ModuleName parameters before attempting to munge the JSON data into the correct types for the DSC Resource. With the move away from CIM instances, this should be doable but probably requires a dedicated function in PSDesiredStateConfiguration, like Resolve-DscProperty (struggled to find a good name for this given the existence of ConvertFrom-Json). At that point, all of the data types should be known (or loadable and then known).
2. Invoke-DscResource looks to find the appropriate DSC Resource based on the specified Name and ModuleName parameters and uses a special constructor for that DSC Resource which expects to receive either an arbitrary string of JSON or a single object (as returned from ConvertFrom-Json) and is then responsible for transforming the data itself.

The primary difference between these approaches from my perspective is that the latter approach is likely more future-proof but places the burden largely on the individual DSC Resource authors (and means that users will need to inspect each DSC Resource to see if it supports their needs).

I think in the long run that while distributing this responsibility to DSC Resource authors might be convenient, it will lead to a worse overall experience for users, vendors, and authors compared to implementing the functionality in PSDesiredStateConfiguration itself.