Update PSAdapters to automatically convert streams to DSC traces

[SteveL-MSFT]

PR Summary

Automatically convert PS streams to DSC traces:

• Write-Host and Write-Information is INFO
• Write-Warning is WARN
• Write-Error is ERROR
• Write-Debug is TRACE (since we can't be certain raw information isn't written) and must be explicitly Write-Debug -Debug
• Write-Verbose is DEBUG (seemed too noisy to be INFO) and must be explicitly Write-Verbose -Verbose

The main changes:

• wrap the previous main code in powershell.resource.ps1 in a scriptblock that gets executed in a runspace so streams can be captured
• set $VerbosePreference and $DebugPreference to silentlycontinue as it was generating too much noise in the traces, docs should state that either resources set those preferences variables to continue or explicitly use Write-Verbose -Verbose or Write-Debug -Debug
• since HadErrors is true if anything is written to stderr, it just gets traced but ignored. Instead, a script is seen as failed if the Error stream had any records. This means that resources need to use -ErrorAction Ignore instead of -ErrorAction SilentlyContinue, this change was made throughout the adapter
• removed use of Write-DscTrace in adapter and support modules have it write to the PS streams instead
• use $env:DSC_TRACE_LEVEL to determine which streams to actually listen to
• have the support modules emit objects and handle conversion to JSONLines in the resource script
• created new StreamResource class resource to validate conversion
• many tests were updated to include -Because with the tracelog to help identify why they broke
• updated the powershell.dsc.yaml example to use PS resources implicitly instead of explicitly

PR Context

Fix #423

[Copilot]

Pull request overview

This pull request implements automatic conversion of PowerShell streams to DSC traces, addressing issue #423. The core change introduces an event-driven mechanism that captures PowerShell output streams (Error, Warning, Information, Verbose, Debug) and converts them to corresponding DSC trace levels (error, warn, info/trace, debug, trace).

Changes:

• Refactored powershell.resource.ps1 to use async PowerShell execution with Register-ObjectEvent for stream capture
• Removed Write-DscTrace function from psDscAdapter modules and replaced with native PowerShell stream cmdlets (Write-Error, Write-Warning, etc.)
• Updated modules to set ErrorActionPreference='Stop' and use -Verbose/-Debug flags consistently
• Added StreamResource test class and comprehensive streaming tests to validate the conversion
• Simplified powershell.dsc.yaml example by removing nested WindowsPowerShell adapter structure
• Updated existing tests to accommodate JSON-formatted trace output

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
adapters/powershell/psDscAdapter/powershell.resource.ps1	Major refactoring to implement async PowerShell execution with event-based stream capture and conversion to DSC traces
adapters/powershell/psDscAdapter/win_psDscAdapter.psm1	Removed custom Write-DscTrace function, replaced with native Write-Error/Warning/Verbose/Debug, added ErrorActionPreference='Stop'
adapters/powershell/psDscAdapter/psDscAdapter.psm1	Same changes as win_psDscAdapter.psm1 - removed Write-DscTrace, using native streams
adapters/powershell/Tests/powershellgroup.resource.tests.ps1	Added comprehensive streaming tests for all trace levels, updated ClearCache test to suppress stderr
adapters/powershell/Tests/powershellgroup.config.tests.ps1	Updated tests to capture trace output for better diagnostics, changed assertions for JSON-formatted traces
adapters/powershell/Tests/win_powershell_cache.tests.ps1	Changed FileContentMatchExactly to -BeLike to accommodate JSON-formatted trace messages
adapters/powershell/Tests/TestClassResource/0.0.1/TestClassResource.psm1	Added StreamResource test class that emits various stream types for testing
adapters/powershell/Tests/TestClassResource/0.0.1/TestClassResource.psd1	Exported StreamResource in DscResourcesToExport array
dsc/examples/powershell.dsc.yaml	Simplified example by removing nested WindowsPowerShell adapter structure

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[michaeltlombardi]

A couple of notes from a design/spec perspective:

• I would prefer that we map Write-Information to INFO rather than DEBUG given that the PowerShell documentation for Write-Information states:

  Starting in Windows PowerShell 5.0, Write-Host is a wrapper for Write-Information. This allows you to use Write-Host to emit output to the information stream. This enables the capture or suppression of data written using Write-Host while preserving backwards compatibility.

  It's fairly common in community code to use Write-Information to provide non-critical information to a user that maps relatively well to the INFO stream. Few cmdlets emit to the information stream and it's generally less noisy than the verbose stream.

• I expect the change requiring authors to use Ignore instead of SilentlyContinue to break some relatively large number of existing DSC Resources. We may need to only treat terminating errors as failures for PowerShell resources or make this an option somehow.

  For example, I did a quick search in the source for a few DSC Community PSDSC modules:

  • SqlServerDsc
  • ActiveDirectoryDsc
  • ComputerManagementDsc

[SteveL-MSFT]

I’m not satisfied with the detection if the resource failed, so perhaps treat all records in error stream as non-terminating and only have unhandled exception as failure?

[michaeltlombardi]

I think unhandled exceptions as failure makes sense. This would still bubble up the error messages from those commands in existing resources without causing the operation for a resource to fail (and thus halt a configuration operation).

Then resource authors can clean up their implementation to avoid surfacing erroneous error messages or we can define an option to only surface unhandled exceptions or whatever makes sense.

[SteveL-MSFT]

I'll make these changes:

• Information goes to info
• Errors in the error stream will be written as warning (this may still be a bit noisy due to people commonly using SilentlyContinue
• unhandled exceptions will be written as Error and result in a failure

[michaeltlombardi]

Errors in the error stream will be written as warning (this may still be a bit noisy due to people commonly using SilentlyContinue

Is it possible to emit error messages without failing an operation? I thought that whether a non-adapted resource emitted error messages was separate from whether we considered an operation to have failed (e.g. emitting errors but exiting 0 still reports as a successful operation, it just also had errors).

If you can emit error-level messages with exit code 0 by design then I would prefer that non-terminating errors still bubble up to DSC and higher order tools as error rather than warning. In the future, when we support options for adapters and extensions, I think it would make sense to let users decide whether to bubble up non-terminating errors as error messages or warning messages.

If the presence of error messages causes DSC to consider a resource operation as a failure even when the exit code is 0 then I think emitting non-terminating errors as warnings is coherent with the current design.

Otherwise the proposed changes all look good to me.

[SteveL-MSFT]

@michaeltlombardi yes, error messages are not considered fatal, only the exit code. I guess I was trying to cover for "badly written" resources too much that will spew errors implicitly. However, it's probably better to trace every ErrorRecord as an error trace and leave it to resource authors to clean up their code. Since both Error and Warning are, by default, displayed, it doesn't change much to shift non-terminating errors as warnings.

So new plan:

• just pass-through PS ErrorRecords as error traces and accept it'll be noisy at first (specifically the SilentlyContinue usage as I don't believe I can determine it was intended to be silent)
• Write-Information goes to info trace
• unhandled exception is the only way to indicate a fatal error which results in the PSAdapter exiting with non-zero exit code
• resource authors must still use Write-Verbose -Verbose and Write-Debug -Debug

[SeeminglyScience]

Suggested change

	exit
	return

Shouldn't technically cause any issues currently but might if this runspace is ever passed a host. Also just may cause confusion from readers

[SeeminglyScience]

Suggested change

	$description = $module.Description.split("`r`n")[0]
	$description = ($module.Description -split '\r?\n')[0]

Feel free to ignore, I know it's just white space changes. Also not necessary if you know with certainty that the source will always be CRLF.

[SeeminglyScience]

Hmm maybe I'm missing something, is the 1 capturable somewhere? Is this still in the same [PowerShell]::Create().AddScript( statement or did I miss where that ended?

[SeeminglyScience]

Suggested change

	$traceQueue.Enqueue(@{ info = $EventArgs.ItemAdded.MessageData.ToString() })
	$traceQueue.Enqueue(@{ info = [string]$EventArgs.ItemAdded.MessageData })

MessageData can be null. Should be exceedingly rare, but might as well cast instead.

[SeeminglyScience]

Suggested change

	while (-not $asyncResult.IsCompleted) {
	# This while loop with sleep must remain so that registered object events
	# can take over the pipeline thread.
	while (-not $asyncResult.IsCompleted) {

Optional comment to avoid someone trying to swap to a blocking wait in the future

[SeeminglyScience]

Suggested change

	foreach ($psd1 in Get-ChildItem -Recurse -Filter "$($moduleFolder.Name).psd1" -Path $moduleFolder.fullname -Depth 2 -ErrorAction Ignore) {
	foreach ($psd1 in Get-ChildItem -Recurse -Filter "$($moduleFolder.Name).psd1" -LiteralPath $moduleFolder.fullname -Depth 2 -ErrorAction Ignore) {

-Filter doesn't have an equivalent but if the module name itself has a wildcard character then it'll probably break at a lot of places

[SeeminglyScience]

Suggested change

	$methods = $ResourceType.GetMember(
	'Export',
	[System.Reflection.MemberTypes]::Method,
	[System.Reflection.BindingFlags]'Public, Instance')

very optional nit

[SeeminglyScience]

Suggested change

	return [System.Collections.Generic.List[DscResourceInfo]]::new()
	return

Definitely optional nit. Since it's a function, returning an empty enumerable will be the same as not returning anything.

[SeeminglyScience]

Suggested change

	Write-Debug -Debug ("Detected stale cache entry '$($_.Name)'")
	Write-Debug -Debug "Detected stale cache entry '$($_.Name)'"

There's a few of these and I don't want to litter the PR with a bunch of suggestions all related to this. It's definitely not important, but the grouping expression can be omitted for an expandable string expression.

[SeeminglyScience]

Suggested change

	$m = $env:PSModulePath -split [IO.Path]::PathSeparator | % { Get-ChildItem -Directory -Path $_ -Depth 1 -ErrorAction Ignore }
	$m = $env:PSModulePath -split [IO.Path]::PathSeparator | % { Get-ChildItem -Directory -LiteralPath $_ -Depth 1 -ErrorAction Ignore }