Automatically handle messages from PSDSC resources

[michaeltlombardi]

Summary of the new feature / enhancement

As a PSDSC resource author and DSCv3 user, I want the PowerShell adapter in DSCv3 to be able to automatically handle message stream objects from PSDSC resource invocations, so that I can see the messages in trace output.

Currently, any messages other than errors thrown by the DSC Resource get swallowed instead of bubbled up to the caller.

Proposed technical implementation details (optional)

In the adapter, we're using the Invoke() method on the adapter module to invoke the appropriate DSC operation on a resource:

DSC/powershell-adapter/psDscAdapter/powershell.resource.ps1

Line 116 in 9ee037a

$actualState = $psDscAdapter.invoke( { param($op, $ds, $dscResourceCache) Invoke-DscOperation -Operation $op -DesiredState $ds -dscResourceCache $dscResourceCache }, $Operation, $ds, $dscResourceCache)

The Invoke-DscOperation function handles invoking the DSC Resource depending on its implementation details. It also handles writing JSON errors and exiting for DSC from the invocation, like when a user specifies a script-based PSDSC resource on a Linux machine:

DSC/powershell-adapter/psDscAdapter/psDscAdapter.psm1

Lines 228 to 232 in 9ee037a

	if ($IsLinux) {
	$trace = @{'Debug' = 'ERROR: Script based resources are only supported on Windows.' } | ConvertTo-Json -Compress
	$host.ui.WriteErrorLine($trace)
	exit 1
	}

I think we could write a small handler that uses stream redirection to capture all emitted stream messages, converts them to JSON¹, and bubbles them up to DSC before continuing. Something like:

filter Resolve-InvocationOutput {
    [cmdletbinding()]
    param(
        [Parameter(ValueFromPipeline = $true)]
        [psobject[]]$Output
    )

    foreach ($o in $Output) {
        switch ($o.GetType().FullName) {
            'System.Management.Automation.WarningRecord' {
                Write-JsonMessage -Level Warning -Message $o.Message
            }
            'System.Management.Automation.ErrorRecord' {
                Write-JsonMessage -Level Error -Message $o.Exception.Message
            }
            'System.Management.Automation.VerboseRecord' {
                Write-JsonMessage -Level Info -Message $o.Message
            }
            'System.Management.Automation.InformationRecord' {
                Write-JsonMessage -Level Info -Message $o.MessageData.ToString()
            }
            'System.Management.Automation.DebugRecord' {
                Write-JsonMessage -Level Trace -Message $o.Message
            }
            default {
                $o
            }
        }
    }
}

$invokeParams = @{
  Method     = $Operation
  ModuleName = $cachedDscResourceInfo.ModuleName
  Name       = $cachedDscResourceInfo.Name
  Property   = $property
}
# Invoke-DscResource only ever returns one object for output, so use
# Select-Object after resolving the invocation output to ensure that
# $invokeResult is the actual output from the command.
$invokeResult = Invoke-DscResource @invokeParams *>&1 |
    Resolve-InvocationOutput |
    Select-Object -First 1
# continue as normal

This would automatically plumb messages from PSDSC resources up to DSC without requiring resource authors to use any special code in their resources - they just emit messages to the appropriate streams and the adapter bubbles them up in the way that DSC expects.

Here I'm mapping the PowerShell output streams to the DSC trace levels as described in the following table:

PowerShell output stream	DSC trace level
Success	-
Error	Error
Warning	Warning
Information	Info
Verbose	Info
Debug	Trace

Footnotes

1. See Define semantic exit codes for the PowerShell adapters #421 for the definition of the helper function for emitting JSON messages from the adapter ↩

[theJasonHelmick]

Thank you @michaeltlombardi -- The DSC WG has reviewed and approved this proposal