Handle empty path segment in `PSModulePath` for `Microsoft.Windows/WindowsPowerShell` adapter resource

[michaeltlombardi]

Summary of the new feature / enhancement

As a user, I want to use adapted PSDSC resources in DSC without getting confusing errors when trying to list resources because my PSModulePath environment variable contains any empty segments or ends with a trailing separator (;).

As identified in #1094, the Windows PowerShell adapter currently fails when trying to list adapted PSDSC resources when the PSModulePath contains any empty segments or ends with a trailing separator (;).

We should either update the adapter to munge the path and avoid this issue or define a semantic exit code for this failure state and provide useful information to the caller.

Proposed technical implementation details (optional)

Option 1: Munge PSModulePath

In this case, we should update the following lines for Invoke-DscCacheRefresh in win_psDscAdapter.psm1 from:

DSC/powershell-adapter/psDscAdapter/win_psDscAdapter.psm1

Line 80 in 4750f77

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

DSC/powershell-adapter/psDscAdapter/win_psDscAdapter.psm1

Line 262 in 4750f77

$m = $env:PSModulePath -split [IO.Path]::PathSeparator | ForEach-Object { Get-ChildItem -Directory -Path $_ -Depth 1 -ea SilentlyContinue }

To:

$m = $env:PSModulePath -split [IO.Path]::PathSeparator | 
    Where-Object -FilterScript {-not [string]::IsNullOrEmpty($_) } |
    ForEach-Object -Process {
        Get-ChildItem -Directory -Path $_ -Depth 1 -ErrorAction Ignore
    }

Or define a helper function to invoke in those locations instead, like:

function Get-ModuleDirectory {
    [CmdletBinding()]
    [OutputType([System.IO.DirectoryInfo])
    param()

    end {
        $env:PSModulePath -split [IO.Path]::PathSeparator | 
            Where-Object -FilterScript {-not [string]::IsNullOrEmpty($_) } |
            ForEach-Object -Process {
                Get-ChildItem -Directory -Path $_ -Depth 1 -ErrorAction Ignore
            }
        }
    }
}

And update the call sites to:

$m = Get-ModuleDirectory

This would obviate the error behavior for users.

Option 2: Define semantic exit code

In this case, we should update the manifest to define exit code 2 with descriptive text like:

{
    // elided manifest fields
    "exitCodes": {
        "0": "Success",
        "1": "Unhandled error",
        "2": "Malformed PSModulePath"
    }
}

Then, we should add a try {} catch {} construction to the win_psDscAdapter.psm1 wherever we use Get-DscResource and catch the specific case for this error. In the catch block, we should:

1. Emit a descriptive error message indicating the problem with PSModulePath (empty segment or trailing separator or both).
2. Exit with code 2.

Summary

I have a slight preference for intentionally handling the malformed PSModulePath over erroring. It's a failure state we can readily predict and avoid. It might be worth emitting a warning or info message indicating discovery of a malformed PSModulePath.

[Gijsreyn]

My preference goes to option 1, just chuck it up. It's a small change, and I'm happy to see you have already thought of the solution code. If you want me to hit up the PR, the helper function would be my pick. The name for me would be slightly different: Get-ValidModuleDirectory, or the inappropriate version Get-ModuleDirectoryMunged.