Debug-Runspace: Dive Into PowerShell Debugging Like a Pro

Welcome back to Wahmans Powershell Blog! Today we’re focusing on a lesser-known but incredibly powerful cmdlet: Debug-Runspace. If you’ve ever worked with background jobs, runspaces, or multithreading in PowerShell, you know that debugging can be tricky. Debug-Runspace allows you to interactively debug code within a running runspace, giving you the power to pause execution, inspect variables, and step through the code.

According to Microsoft:

Starts an interactive debugging session with a runspace.

That’s a simple description for a cmdlet that can give you detailed insight into your running threads of execution. In this post, we’ll explore how to use Debug-Runspace in four examples, progressing from a beginner level to more advanced scenarios.

1. Debugging a Simple Background Job (Beginner)

Let’s start with a basic example where we launch a job and then attach the debugger to that runspace.

Start-Job -ScriptBlock {
    1..5 | ForEach-Object {
        Write-Output "Iteration $_"
        Start-Sleep -Seconds 2
    }
} | Out-Null

$runspace = Get-Runspace | Where-Object { $_.RunspaceStateInfo.State -eq 'Running' }
Debug-Runspace -Id $runspace.Id

This script launches a background job and then uses Get-Runspace to find the active runspace. With Debug-Runspace, you step into the job and can observe or alter what’s happening.

2. Inspecting Variables in a Suspended Runspace (Intermediate)

Sometimes a script may hang or take longer than expected. Here’s how you can inspect its state.

$runspacePool = [runspacefactory]::CreateRunspacePool(1,1)
$runspacePool.Open()

$ps = [powershell]::Create()
$ps.RunspacePool = $runspacePool
$ps.AddScript({
    $i = 42
    Start-Sleep -Seconds 30
}).BeginInvoke()

Start-Sleep -Seconds 5
$runspace = Get-Runspace | Where-Object { $_.RunspaceStateInfo.State -eq 'Running' }
Debug-Runspace -Id $runspace.Id

Once inside the debugger session, you can type $i and see that it equals 42. This gives you a peek into the variables inside the runspace at that specific point in time.

3. Stepping Through a ScriptBlock in a Thread Job (Advanced)

When using thread jobs with the ThreadJob module, you can also attach a debugger if needed.

Import-Module ThreadJob

$job = Start-ThreadJob -ScriptBlock {
    $msg = "Hello from thread job!"
    Start-Sleep -Seconds 10
    Write-Output $msg
}

Start-Sleep -Seconds 1
$runspace = Get-Runspace | Where-Object { $_.RunspaceStateInfo.State -eq 'Running' }
Debug-Runspace -Id $runspace.Id

This works similarly to standard jobs, although the mechanism under the hood is different. Keep in mind that depending on how you start your job, the availability of the runspace to attach to may vary.

4. Debugging Parallel Tasks with ForEach-Object -Parallel (Expert)

Starting from PowerShell 7, we’ve had built-in support for parallel execution. Here’s how to sneak into one parallel task’s execution context:

$scriptBlock = {
    param($instance)
    $x = "Parallel instance $instance"
    Start-Sleep -Seconds (Get-Random -Min 2 -Max 5)
    Write-Output $x
}

1..5 | ForEach-Object -Parallel $scriptBlock -ThrottleLimit 2

# In another session or with a pause before completion:
$runspace = Get-Runspace | Where-Object { $_.RunspaceStateInfo.State -eq 'Running' }
Debug-Runspace -Id $runspace.Id

Parallel processing is powerful but tricky to debug. With Debug-Runspace, you can finally get visibility into these runspaces and understand the code flow better.

Wrap-Up

Debug-Runspace is one of those hidden gems in PowerShell that can save you hours when diagnosing or reverse-engineering issues in asynchronous or parallel code. Whether you’re new to multithreading or diving into complex automation scripts, this tool belongs in your debugging arsenal.

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

Debug-Runspace