Using Conditional Breakpoints in PowerShell Scripts

Posted on June 18, 2015 by Jeff Hicks in PowerShell with 0 Comments

At Microsoft Ignite I participated in a PowerShell Q&A session, where someone asked how to use conditional breakpoints in PowerShell for a script, so that processing would break only when a condition was met. Usually this sort of thing is done with a variable. For example: if $X is greater than 10, then break. At the time, I couldn’t give him the exact steps, because I develop my scripts and tools in such a way that my debugging needs are minimal. But when I got a chance I cracked open PowerShell, so I could explain the process to all of you.

You should know that you can work with breakpoints directly in the PowerShell console. You are not limited to the PowerShell ISE. A breakpoint is a user-defined trigger that pauses pipeline processing and drops you into a debug mode. The cmdlet you use to create this breakpoints is Set-PSBreakpoint. As you look at help, you will see there are a few ways to use this cmdlet. We’re going to work with variables.

The Set-PSBreakpoint cmdlet in Windows PowerShell. (Image Credit: Jeff Hicks)

The Set-PSBreakpoint cmdlet in Windows PowerShell. (Image Credit: Jeff Hicks)

The variable parameter will be the name, without the $. The mode defaults to Write access.

PowerShell will trigger the break just before the variable is updated. And finally the action parameter is a scriptblock of PowerShell commands that you want to run when the breakpoint is reached. This is where the conditional magic happens. To demonstrate, let’s do a simple test in the console. First, define the breakpoint.

I haven’t told PowerShell to do anything other than watch when $i is updated.

As soon as PowerShell tries to write to $i, it goes into debug mode.

Entering debug mode in Windows PowerShell. (Image Credit: Jeff Hicks)

Entering debug mode in Windows PowerShell. (Image Credit: Jeff Hicks)

Notice the prompt change. I can run just about any command I want here and even look at the value of $i. Type a ‘?’ to see help.

Help information for debugging in Windows PowerShell. (Image Credit: Jeff Hicks)

Help information for debugging in Windows PowerShell. (Image Credit: Jeff Hicks)

When you are ready to continue, type ‘c’ or ‘continue’. Now let’s get conditional. First, I’ll remove all my breakpoints, so I can start over.

Next, I’ll define my conditional scriptblock, which can be as complex as you need it to be.

In my case, I’m telling PowerShell that if $i is greater than 5, then go into debug mode. I’ll set the breakpoint with this action and test it out.

PowerShell hit the variable breakpoint. (Image Credit: Jeff Hicks)

PowerShell hit the variable breakpoint. (Image Credit: Jeff Hicks)

Sponsored

PowerShell kept running until the condition was met. This was testing directly in the console. Let’s take another step and watch a variable in one of my functions. Again, I’ll remove the existing breakpoints.

Here’s the function I want to debug.

The function will write disk information to the pipeline if the percentage of free spaced is less than or equal to a threshold, which defaults to 20 percent. I want to add a conditional breakpoint for any computer where the percentage is less than or equal to 50 percent. The variable is what I am using in the function.

I’m going to test with a list of servers.

As soon as the condition is met, I enter debug mode, where I can do all the checking I need.

Obviously you need to have access to the command’s source code to know what variable name to use. Let’s remove the breakpoint, and try again with a script.

My script defines a function to list all non-administrative shares for a list of computers.

I want to set a breakpoint so that if the count of $d, the non-admin shares, is greater than or equal to 3, then I’ll drop into debug mode.

There is no specific line in the script that I want to debug, just the variable.

I run the script and hit the breakpoint.

Excellent. This is just what I expected, and hopefully you realize that this isn’t too complicated. However, if you are using the PowerShell ISE, all you can do is set a breakpoint on a given line.

Debugging in the PowerShell ISE. (Image Credit: Jeff Hicks)

Debugging in the PowerShell ISE. (Image Credit: Jeff Hicks)

You could manually type the same commands I’ve just demonstrated in the PowerShell ISE, but that takes too long. Instead I wrote an add-on for the PowerShell ISE that will let you create a conditional breakpoint.

When you run this function, it will add a menu shortcut under the Add-Ons menu.

In my function, I want to set a conditional breakpoint on $computer, so I select the variable name. Don’t include the $ sign.

The function displays an input box, where I can create the condition that will go into the if statement. My function assumes you aren’t doing anything other than breaking if the variable meets some condition.

In my case, I enter this:

Here you do need the $ sign with variable name. My function created a breakpoint in the ISE.

get-psbreakpoint cmdlet in Windows PowerShell. (Image Credit: Jeff Hicks)

get-psbreakpoint cmdlet in Windows PowerShell. (Image Credit: Jeff Hicks)

Sponsored

Now I can run the script in the ISE and when I get to one of my domain controllers, I’ll drop into debug mode.

As you can see, the script runs normally until my condition is met. From here I can use the debug menu in the ISE to disable or remove the breakpoints.

Conditional breakpoints are actually quite interesting. True, they can help with debugging a script or function, but I also like how they all me to step through my script interactively. If you found this useful, I hope you’ll let me know. I’d also like to know what else keeps you from creating killer PowerShell tools.

Sponsored

Tagged with , ,