Debugging in Windows PowerShell

Downloads
125694.zip

If you ever tried your hand at writing a PowerShell script, you likely had to spend some time debugging it. Bugs are an inevitable part of life when you're trying to tell a computer something to do. On the surface, PowerShell doesn't seem to offer much in the way of debugging assistance. In this short guide, I'll tell you about some of the basic techniques for debugging and some practices that can help keep the bugs at bay.

Although PowerShell doesn't have any kind of one-line-at-a-time graphical debugger built in, there are free and commercial third-party tools that do. Editors such as Quest Software's PowerGUI, Idera's PowerShellPlus, and SAPIEN Technologies' PrimalScript all use different techniques to trick PowerShell into running your script one line at a time, showing you what a script's variables contain and generally making debugging easier. However, unless you know what debugging is all about, these tools don't make you a more effective debugger.

Before you start debugging, you need to know what you're looking for—in other words, what is a bug? There are two distinct types.

 

Bug Type One: Fat Fingers

The first type of bug is a simple syntax error. A typo. An operator malfunction. Fat fingers. Pick a term. You'll find these bugs relatively easy to spot because PowerShell will hurl an error in your direction, complete with the number of the line that contains the error. However, if you're using Notepad, knowing the line number won't help because it doesn't display line numbers. For this reason, you should stop using Notepad and use PowerGUI, which is free, or a commercial script editor instead.

Commercial script editors offer more than just line numbering, and some of their features can help prevent fat-finger bugs. Chief among these capabilities is syntax highlighting, which is nothing fancier than making your script code turn colors. But the key is that things only turn the right color when they're spelled correctly. So, if you're using a syntax-highlighting editor, start becoming familiar with the colors it uses for command names, variables, literal strings, and so forth. If they aren't turning the right color as you type, you missed something. Go back and look carefully for the problem.

If you do miss something, PowerShell will be more than willing to tell you about it. Pay attention to error messages. I can't tell you how often I see admins struggling to fix something, simply because they're not reading the error message. When they see that red text hit the screen, they go into a bit of a panic and just start trying different things. But the error message is telling you what line of code has the problem, and most of the time it's even telling you what the problem is. So just slow down a bit, read carefully, comprehend what the error is saying, and see if you can spot the problem.

A good script editor can provide further help by asking PowerShell to run a sort of preflight checklist on your script. This feature is typically called live syntax checking. The editor can then call your attention to simple errors right away, before you even run the script. Some use a red underline (like Microsoft Word's spell-check feature); others use different visual indicators.

Finally, adopt some best practices to keep yourself out of trouble. Format your code nicely so that constructs are indented and their curly braces line up, as in

Function Get-Something<br>\\{<br>  # Code here<br>\\}

rather than messy code like this

Function Get-Something \\{ # Code here \\}

The first example is easier to read and easier to verify that there's an opening and closing brace. When you start nesting constructs, it's easy to miss a closing brace when code is set up like the second example.