Exploring the Get-Runspace Cmdlet in PowerShell

Welcome back to Wahmans Powershell blog! Today we’re talking about a powerful diagnostic tool for managing and understanding how PowerShell is running under the hood: Get-Runspace.

Get-Runspace is a cmdlet that lets you inspect the currently active runspaces in a PowerShell host process. If you’ve ever wondered how PowerShell tasks are being managed in parallel or looked into performance tuning your scripts, this cmdlet is for you.

What is a Runspace?

Think of a runspace as a separate thread of execution in PowerShell. When you use background jobs or the threading APIs, new runspaces are created. These runspaces are isolated and operate independently of one another.

Why Use Get-Runspace?

This tool is invaluable when debugging hangs, concurrency issues, or checking on the status of background tasks.

Let’s dive into 4 usage examples – from beginner to advanced:

1. Basic: Checking the current runspace

This is the simplest use case, showing the current default runspace of your PowerShell session:

Get-Runspace

2. Intermediate: Creating and inspecting multiple runspaces

You can use the [runspacefactory]::CreateRunspace() method to create multiple runspaces and then check their state:

$rs1 = [runspacefactory]::CreateRunspace()
$rs1.Open()
$rs2 = [runspacefactory]::CreateRunspace()
$rs2.Open()

Get-Runspace | Format-Table Id, State, Availability

3. Intermediate/Advanced: Using runspaces with PowerShell instances

Combine runspaces with the [powershell] class to run code asynchronously:

$runspace = [runspacefactory]::CreateRunspace()
$runspace.Open()

$ps = [powershell]::Create()
$ps.Runspace = $runspace
$ps.AddScript({ Start-Sleep -Seconds 5; 'Completed' }) | Out-Null
$ps.BeginInvoke()

Get-Runspace | Format-List

4. Advanced: Monitoring for hung runspaces and cleaning them up

Sometimes you’ll have runspaces that get stuck. You can write a monitoring script to detect and clean them:

$stuck = Get-Runspace | Where-Object { $_.Availability -ne 'Available' -and $_.State -eq 'Opened' }

foreach ($rs in $stuck) {
    Write-Host "Closing stuck runspace ID: $($rs.Id)"
    $rs.Close()
}

Conclusion

Get-Runspace is a key tool for anyone diving into multithreading in PowerShell or needing to debug complex automation workflows. Knowing what’s running—and how it’s running—lets you write more efficient and reliable scripts.

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