Understanding the PowerShell Cmdlet: Enable-RunspaceDebug

Welcome back to Wahmans PowerShell Blog! Today we’re diving into an advanced debugging tool in PowerShell: Enable-RunspaceDebug. This cmdlet is a powerful asset when debugging scripts that run across multiple runspaces. Let’s break down what it does and go through some hands-on examples from beginner to advanced use.

What is Enable-RunspaceDebug?

The Enable-RunspaceDebug cmdlet enables debugging on all runspaces within the current session. This ensures that breakpoints are preserved even if no debugger is attached at the time the breakpoint is hit. Once a debugger is attached, execution will break as expected.

It is especially useful when dealing with background jobs, workflows, or parallel executions in PowerShell, where runspaces execute code separately from the main session.

Syntax

Enable-RunspaceDebug [-BreakAll] [-Enabled] []

Example 1: Basic Usage with a Breakpoint

If you have a breakpoint set in a script running in a background runspace, use Enable-RunspaceDebug to ensure it’s recognized.

# Set a script breakpoint
Set-PSBreakpoint -Script './test.ps1' -Line 3

# Enable runspace debugging
Enable-RunspaceDebug -Enabled

# Start background job
Start-Job -ScriptBlock { . ./test.ps1 }

This ensures that when the background job runs test.ps1, your breakpoint on line 3 will trigger when a debugger is attached.

Example 2: Debugging a Runspace with Manual Breaks

Use Enable-RunspaceDebug in conjunction with Set-PSBreakpoint and a custom runspace to catch problems in parallel script blocks.

# Define script
$script = {
    "Start of script"
    Start-Sleep -Seconds 1
    "End of script"
}

# Set breakpoint on line 2 of script (Start-Sleep line in this case/problem context)
Set-PSBreakpoint -Script $script -Line 2

# Enable runspace debugging
Enable-RunspaceDebug -Enabled

# Start the runspace remotely
$ps = [powershell]::Create().AddScript($script)
$job = $ps.BeginInvoke()

Example 3: Using -BreakAll to Pause All Debug Targets

To break on all runspaces immediately, use the -BreakAll switch. This stops all PowerShell activity across runspaces until you attach a debugger manually.

# Enable with global break
Enable-RunspaceDebug -BreakAll

# Now, spawn jobs or processes freely
Start-Job -ScriptBlock { "Running in job..." }

All runspaces (including this new job) will be paused, waiting for debugger attachment.

Example 4: Advanced – Debugging Workflow ScriptBlocks

Workflows create multiple runspaces under the hood. Let’s say you’re debugging a composite workflow step:

workflow Test-Workflow {
    InlineScript {
        "Inside InlineScript"
        $x = 2 + 2
    }
}

# Set a breakpoint in the script line inside workflow
Set-PSBreakpoint -ScriptBody { $x = 2 + 2 } -Line 1

# Enable debugging for all runspaces
Enable-RunspaceDebug -Enabled

# Trigger the workflow
Test-Workflow

This will ensure that even in the inner runspaces created by workflows, the debugger will catch and retain your breakpoints.

Conclusion

Enable-RunspaceDebug can be an essential component when troubleshooting complex PowerShell environments where background processing, runspaces, or workflows are involved. Using this cmdlet allows you to ensure breakpoints are honored and helps uncover nuanced issues in concurrent code.

Happy scripting, and I will see you in the next post!

Wahmans Powershell Blog

Enable-RunspaceDebug