PowerShell Logo Small

Debug-Runspace



This is the built-in help made by Microsoft for the command 'Debug-Runspace', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Starts an interactive debugging session with a runspace.

SYNTAX


Debug-Runspace [-Runspace] <Runspace> [-InformationAction {SilentlyContinue | Stop | Continue | Inquire | Ignore | Suspend}] [-InformationVariable [<System.String>]]
[-Confirm] [-WhatIf] [<CommonParameters>]
Debug-Runspace [-Id] <Int32> [-InformationAction {SilentlyContinue | Stop | Continue | Inquire | Ignore | Suspend}] [-InformationVariable [<System.String>]] [-Confirm]
[-WhatIf] [<CommonParameters>]
Debug-Runspace [-Name] <String> [-InformationAction {SilentlyContinue | Stop | Continue | Inquire | Ignore | Suspend}] [-InformationVariable [<System.String>]] [-Confirm]
[-WhatIf] [<CommonParameters>]
Debug-Runspace [-InstanceId] <Guid> [-InformationAction {SilentlyContinue | Stop | Continue | Inquire | Ignore | Suspend}] [-InformationVariable [<System.String>]]
[-Confirm] [-WhatIf] [<CommonParameters>]



Search powershellhelp.space

DESCRIPTION


Debug-Runspace starts an interactive debugging session with a local or remote active runspace. You can find a runspace that you want to debug by first running Get-Process to
find processes associated with Windows PowerShell, then Enter-PSHostProcess with the process ID specified in the Id parameter to attach to the process, and then Get-Runspace
to list runspaces within the Windows PowerShell host process.


After you have selected a runspace to debug, if the runspace is currently running a command or script, or if the script has stopped at a breakpoint, Windows PowerShell opens
a remote debugger session for the runspace. You can debug the runspace script in the same way remote session scripts are debugged.


You can only attach to a Windows PowerShell host process if you are an administrator on the computer that is running the process, or you are running the script that you want
to debug. Also, you cannot enter the host process that is running the current Windows PowerShell session; you can only enter a host process that is running a different
Windows PowerShell session. For example, if you are working in a PowerShell.exe session, you can’t enter the host process for that session, but you can enter the host
process of a running Windows PowerShell ISE session.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/?LinkID=403731
about_Debuggers
Get-Process
Enter-PSHostProcess
Get-Runspace
Debug-Job

REMARKS

<

Examples


Example 1: Debug a remote runspace

PS C:\>Get-Process –ComputerName WS10TestServer –Name *powershell*

Handles WS(K) VM(M) CPU(s) Id ProcessName
------- ----- ----- ------ -- -----------
377 69912 63 2.09 2420 powershell
399 123396 829 4.48 1152 powershell_ise

PS C:\> Enter-PSSession –ComputerName WS10TestServer

[WS10TestServer]:PS C:\> Enter-PSHostProcess –Id 1152

[WS10TestServer:][Process:1152]: PS C:\Users\Test\Documents> Get-Runspace

Id Name ComputerName Type State Availability
-- ---- ------------ ---- ----- ------------
1 Runspace1 WS10TestServer Remote Opened Available
2 RemoteHost WS10TestServer Remote Opened Busy

[WS10TestServer][Process:1152]: PS C:\Users\Test\Documents> Debug-Runspace –Id 2

Hit Line breakpoint on 'C:\TestWFVar1.ps1:83'

At C:\TestWFVar1.ps1:83 char:1
+ $scriptVar = "Script Variable"
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[Process:1152]: [RSDBG: 2]: PS C:\>>



In this example, you debug a runspace that is open on a remote computer, WS10TestServer. In the first line of the command, you run Get-Process on the remote computer, and
filter for Windows PowerShell host processes. In this example, you want to debug process ID 1152, the Windows PowerShell ISE host process.

In the second command, you run Enter-PSSession to open a remote session on WS10TestServer. In the third command, you attach to the Windows PowerShell ISE host process
running on the remote server by running Enter-PSHostProcess, and specifying the ID of the host process that you obtained in the first command, 1152.

In the fourth command, you list available runspaces for process ID 1152 by running Get-Runspace. You note the ID number of the Busy runspace; it is running a script that you
want to debug.

In the last command, you start debugging an opened runspace that is running a script, TestWFVar1.ps1, by running Debug-Runspace, and identifying the runspace by its ID, 2,
by adding the Id parameter. Because there’s a breakpoint in the script, the debugger opens.