Atmosera

Single Stepping a PowerShell Pipeline

As I was building up a moderately complicated pipeline in PowerShell, I was having some trouble and really wished there was a way to single step the pipeline so I could see the state of each item as it was processed. I wasn’t sure this was possible, but it is and I thought others might find it helpful. The magic is in the super powerful Set-PSBreakpoint cmdlet.

Because Set-PSBreakpoint can create breakpoints on not only lines and variable reads/writes, but also commands, I thought I’d try setting a breakpoint in the PowerShell console on one of the commands in the pipeline and it worked great! In the example below I will set a breakpoint on the Get-ChildItem cmdlet and when the breakpoint is hit, use the command line debugger to step through parts of the pipeline (the ‘s’ command is step into)

PS C:Junk> Set-PSBreakpoint -Command Get-ChildItem
ID Script Line Command Variable Action
— —— —- ——- ——– ——
0 Get-ChildItem
PS C:Junk> Get-ChildItem *.exe | ForEach-Object { $_.Name }
Entering debug mode. Use h or ? for help.
Hit Command breakpoint on ‘Get-ChildItem’
At line:1 char:1
+ Get-ChildItem *.exe | ForEach-Object { $_.Name }
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS C:Junk>> s
At line:1 char:38
+ Get-ChildItem *.exe | ForEach-Object { $_.Name }
+ ~
[DBG]: PS C:Junk>> s
At line:1 char:40
+ Get-ChildItem *.exe | ForEach-Object { $_.Name }
+ ~~~~~~~
[DBG]: PS C:Junk>> s
Foo.exe
At line:1 char:48
+ Get-ChildItem *.exe | ForEach-Object { $_.Name }
+ ~
[DBG]: PS C:Junk>>

I love how the tildes show you exactly where you are in the pipeline. That makes it super easy to debug the pipeline. A little hint when single stepping pipelines is if you are setting a command breakpoint on something like Get-ChildItem, you’re going to hit it all the time. What I found works best is writing the commands in the ISE and pasting them into the console window where you want to debug.

For those of you that use the ISE most of the time, you have one problem. Here’s the same commands run in the ISE.

PS C:Junk> Set-PSBreakpoint -Command Get-ChildItem
ID Script Line Command Variable Action
— —— —- ——- ——– ——
0 Get-ChildItem
PS C:junk> Get-ChildItem *.exe | ForEach-Object { $_.Name }
Hit Command breakpoint on ‘Get-ChildItem’
Stopped at: Get-ChildItem *.exe | ForEach-Object { $_.Name }
[DBG]: PS C:junk>> s
Stopped at: Get-ChildItem *.exe | ForEach-Object { $_.Name }
[DBG]: PS C:junk>> s
Stopped at: Get-ChildItem *.exe | ForEach-Object { $_.Name }
[DBG]: PS C:junk>>

For whatever reason, the ISE does not show the tildes where you are in the pipeline. Fortunately, it’s not hard to find where you are because the $PSDebugContext variable’s InvocationInfo field has all the information about everything going on at that point in the debugger.

[DBG]: PS C:junk>> $PSDebugContext.InvocationInfo
MyCommand :
BoundParameters : {}
UnboundArguments : {}
ScriptLineNumber : 1
OffsetInLine : 40
HistoryId : 3
ScriptName :
Line : Get-ChildItem *.exe | ForEach-Object { $_.Name }
PositionMessage : At line:1 char:40
+ Get-ChildItem *.exe | ForEach-Object { $_.Name }
+ ~~~~~~~
PSScriptRoot :
PSCommandPath :
InvocationName :
PipelineLength : 0
PipelinePosition : 0
ExpectingInput : False
CommandOrigin : Internal
DisplayScriptPosition :

As you can see, the PositionMessage is the important data. In my ISE profile, I added the following function to make it easy to see where I’m at when single stepping a pipeline.

function cpo
{
if (test-path variable:/PSDebugContext)
{
$PSDebugContext.InvocationInfo.PositionMessage
}
}

Single stepping the pipeline isn’t super ninja magic like some of those PowerShell people do but this sure helped me figure out what was going on in my troublesome pipeline.

John Robbins