• Scripting
• Windows PowerShell

Applies to PowerShell Studio 2016 and PrimalScript 2016 and later.

I write lots of scripts — for production, for research, for testing, and for demonstrations. And, inevitably, I hit a bug. I'm actually relieved when I do, because no code is perfect and I'd rather find the bugs before my users do. In fact, I make sure the content in my test database is full of oddities so it's as close to the real world as possible.

When you are debugging with a large test sample, like a database or directory, the default line breakpoints are not sufficient. I can hit a line numerous times before I get to the condition that breaks it. And, I don't want to spend my time repeatedly banging on the F10 (step over) and F11 (step into) keys until I hit the offending condition.

In PowerShell Studio and PrimalScript, you can create and edit line, function, and variable breakpoints, and beyond that, you can set conditions for breaking. For example, I don't want to break on line 32 every time it runs. I want to break when the $ID variable has a value of 9999 or only when the Set-Widget function runs and $ID is 0.

Good old line breakpoints

Line breakpoints break just before the line of code with the breakpoint runs. Because most debuggers support line breakpoints, we're very accustomed to using them. But, they might not be most efficient, so before you use a line breakpoint, consider whether a function or variable breakpoint might be a better choice.

One of the nice things about line breakpoints is that they're easy to see. You can see the big red dot beside the breakpoint on line 24 in this image. But if you want to break when the Set-Maximum function runs — not just when it's called on line 24, consider a function breakpoint.

Use Function Breakpoints

A function breakpoint breaks right before the first line of code in the function runs. It actually breaks on the first curly brace in the function script block.

If the function has BEGIN, PROCESS, and END blocks, a function breakpoint breaks on the first curly brace of the BEGIN block, then on the first curly brace of the PROCESS block, and again on the first curly brace of the END block.

The breakpoint does not break on the function declaration — when PowerShell reads the function into memory. It breaks only on the function call — where the function actually runs. So, if you have defined a function in a script, but the function doesn't run, the function breakpoint is not triggered.

Also, by default, a function breakpoint breaks every time the function runs, which might be handy, depending on your use case.

• To set a function breakpoint in PowerShell Studio:
  Click Home and, in the Run group, click Breakpoints / Set Function Breakpoint or Edit Breakpoints.
  
  
  Select a function from the Function drop-down menu. You can also specify a file if you're debugging with multiple files in a module or project.
  
  
  You can't see the function breakpoint — there's no big red dot in your script — but it's effective.
  
  
  And, the Edit Breakpoints dialog box display shows that it's created and enabled.
  
  
  TIP : I always use the Edit Breakpoints dialog to create, enable, disable, and delete my breakpoints. It displays all of the breakpoints in the session and reminds when that I create a breakpoint twice, instead of changing a breakpoint. To create a function breakpoint in Edit Breakpoints, click the "cube+" icon in the upper left corner.

Use Variable Breakpoints

Variable breakpoints are my favorites. They break when the variable value is used ("read"), is changed ("write"), or either ("ReadWrite").

• To set a variable breakpoint:
  
  1. Click Home and, in the Run group, click Breakpoints / Set Variable Breakpoint.
     -or-
     In the Edit Breakpoints dialog, in the upper left corner, click the "square+" icon.
     
     
  2. Select a variable from the Variable drop-down menu.
     
     You can also type the variable name. Technically, you’re supposed to enter only the variable name without the ‘$’, but PowerShell Studio is wonderful, so if you forget and type the ‘$’, PowerShell Studio ignores it.
     
  3. From the Mode box, select Read (break whenever the variable value is read), Write (break when the variable value changes), or ReadWrite (both).

Like a function breakpoint, you won't see a big red dot in your script to indicate a variable breakpoint, but you can see it in the Edit Breakpoints dialog box. (See why I like that dialog so much?)

For example, in this script, a write-mode variable breakpoint on 'n' is triggered on line 26, when the value of $n changes to the next value in the $numbers array. But, it is not triggered on line 28, when $n is read, but not changed. If I need a different behavior, I can change the mode of the breakpoint to Read or ReadWrite.

Create conditional breakpoints

Variable and function breakpoints are very valuable, but conditional breakpoints are the extreme time-saver — an uber-breakpoint.

To set a conditional breakpoint:

• When creating or editing a breakpoint, enter a script block in the Action box.
• The Action value replaces the break in the breakpoint. That is, when the breakpoint event occurs and an Action is defined, Windows PowerShell runs the Action script block instead of breaking (not in addition to breaking). If you want it to break, use the Break keyword (see about_Break).

The value in the Action box is a script block that runs when the breakpoint is triggered.

The Action script block should be enclosed in curly braces, but PowerShell Studio is wonderful, so if you forget the curly braces, it adds them automatically. I like to type the curly braces, but it’s not necessary.

For example, this variable breakpoint breaks when the value of $n is changed to 4.

{ if ($n -eq 4) { break } }

In the Action script block, the 'n' variable is referred to as $n, just like it is in my script. I use the Break keyword in my script block to tell Windows PowerShell to break into the debugger when the condition is met.

When an Action is set, the variable breakpoint is still triggered every time the value of $n changes. But, the script does not break into the debugger. Instead, it runs the Action script block. If $n is not 4, the '{break}' in the Action doesn't occur and the script continues.

But when the variable breakpoint is triggered on a change in $n, and the value of $n is 4, the script breaks into the debugger.

You can set conditional function breakpoints, too. For example, this function breakpoint breaks into the debuggers only when the Get-DeviceID function is called with a parameter value of 'localhost'. Otherwise, it records the value of the ComputerName in a text file.

if ($ComputerName -eq 'localhost') { break } else { $ComputerName | Out-File .\Test.txt }

Conditional breakpoints are so powerful that, after a bit of experience, you'll use them all the time. Just remember to include the Break keyword if you want to break into the debugger.

June Blender is a technology evangelist at SAPIEN Technologies, Inc. and a Windows PowerShell MVP. You can reach her at This email address is being protected from spambots. You need JavaScript enabled to view it. or follow her on Twitter at @juneb_get_help.

• Prev
• Next