Debug-Runspace

Starts an interactive debugging session with a runspace.
Debug-Runspace [-Runspace*] <Runspace> [-Confirm] [-WhatIf] [<CommonParameters>]
Debug-Runspace [-Id*] <Int32> [-Confirm] [-WhatIf] [<CommonParameters>]
Debug-Runspace [-InstanceId*] <Guid> [-Confirm] [-WhatIf] [<CommonParameters>]
Debug-Runspace [-Name*] <String> [-Confirm] [-WhatIf] [<CommonParameters>]

The Debug-Runspace cmdlet 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.

Parameters
-Id <Int32>

  • This value is required

Specifies the ID number of a runspace. You can run Get-Runspace to show runspace IDs.

-InstanceId <Guid>

  • This value is required

Specifies a runspace by its instance ID, a GUID that you can show by running Get-Runspace.

-Name <String>

  • This value is required

Specifies a runspace by its name. You can run Get-Runspace to show the names of runspaces.

-Runspace <Runspace>

  • This value is required
  • Accepts pipeline input ByValue

Specifies a runspace object. The simplest way to provide a value for this parameter is to specify a variable that contains the results of a filtered Get-Runspace command.

-Confirm [<SwitchParameter>]

  • Default value is false

Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.

-WhatIf [<SwitchParameter>]

  • Default value is false

Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.

<CommonParameters>

This cmdlet supports the common parameters: Verbose, Debug,ErrorAction, ErrorVariable, WarningAction, WarningVariable,OutBuffer, PipelineVariable, and OutVariable.

Inputs

System.Management.Automation.Runspaces.Runspace

You can pipe the results of a Get-Runspace command to Debug-Runspace.

Examples
  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_isePS C:>Enter-PSSession -ComputerName "WS10TestServer"
       [WS10TestServer]:PS C:> Enter-PSHostProcess -Id 1152
       [WS10TestServer:][Process:1152]: PS C:UsersTestDocuments> Get-Runspace
       Id Name            ComputerName    Type          State         Availability
       -- ----            ------------    ----          -----         ------------
        1 Runspace1       WS10TestServer  Remote        Opened        Available
        2 RemoteHost      WS10TestServer  Remote        Opened        BusyPS C:>[WS10TestServer][Process:1152]: PS  
    C:UsersTestDocuments>  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. The first command runs 

    the Get-Process cmdlet on the remote computer, and then filters for Windows PowerShell host processes. The command debugs process ID 1152, the Windows PowerShell ISE host process.

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

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

    The firth command debugs an opened runspace that is running a script, TestWFVar1.ps1, by using the Debug-Runspace cmdlet, and identifies the runspace by its ID, 2, that uses the Id parameter. Because there’s a breakpoint in the script, the debugger opens.

Additional Notes
 Debug-Runspace works on runspaces that are in the Opened state. If a runspace state changes from Opened to 
 another state, that runspace is automatically removed from the running list. A runspace is added to the 
 running list only if it meets the following criteria.

 -- If it is coming from Invoke-Command; that is, it has an Invoke-Command GUID ID.

 -- If it is coming from Debug-Runspace; that is, it has a Debug-Runspace GUID ID.

 -- If it is coming from a Windows PowerShell workflow, and its workflow job ID is the same as the current 
 active debugger workflow job ID.
Related Links

Debug-Job
Get-Runspace
Get-Process
Enter-PSHostProcess
Enter-PSSession