How to Debug a PowerShell Script

Powershell logo

Any script development usually requires troubleshooting which usually results in one of two approaches. Either manually set values ​​for the variables and output that data when running the script, or use debugging to set breakpoints to inspect the data before continuing or aborting. The ability to debug is built into PowerShell ISE and Visual Studio Code.

How does PowerShell debugging work?

Included with Windows PowerShell, PowerShell ISE has been the traditional reference environment for debugging PowerShell scripts. With a built-in menu for debugging and a graphical representation of breakpoints, it’s easy to get started. First of all, any script you debug should be registered. Then you will need to set breakpoints using one of the following three methods.

On the focused line, use the F9 key to set a breakpoint.
Right-click next to a line and choose Toggle Breakpoint to set a breakpoint.
Use Set-PSBreakPoint by specifying a corresponding row, variable, function, or text.

Once you’ve set a breakpoint, you can just start debugging by running the script with F5, or Debug → Run / Continue. Once the script hits the specified breakpoint, execution will be halted and you will need to do one of the following.

Climb over – Execute only the current instruction, stopping before the next instruction. If the current statement is a function or a script, complete the entire call before stopping.
Go in – Similar to Step Over, execute only the current instruction, stopping before the next instruction. Instead of running the whole function or script, if it is called, enter the call.
Go outside – If in a function, exit and go up a level if the function is nested. If in the main script, run until the end of the script or the next breakpoint, whichever occurs first. Ignored instructions are executed but not crossed.

When the script is stopped at a breakpoint, you can hover over a variable with the mouse cursor and see what the values ​​of a given variable are. Moreover, you can also use the command line to generate variables to see the current state. There are a few caveats to this. $ _, $ Input, $ MyInvocation, $ PSBoundParameters and $ Args will not work because they are automatic variables and are not debugged. One way to retrieve these values ​​is to assign them to an intermediate variable which can then be set for a breakpoint.

PowerShell Debugging in Visual Studio Code

Very similar to how PowerShell ISE works, Visual Studio Code adds several very useful debugging options. Additionally, VS Code allows you to easily debug with PowerShell 7.x while ISE is traditionally limited to Windows PowerShell. Using the same keyboard shortcuts as PowerShell ISE, you can quickly start debugging. Better yet, you now have the Debug Pane in VS Code, which consolidates much of the variable output and makes it easy to read a snapshot of all variable values ​​in your code.

Using VS Code Debugging

Just like PowerShell ISE, you can use F5 to start an interactive debugging session. Unlike ISE, VS Code offers a much better and more useful debugging experience. Not only do you get the traditional debugging console, indicated by the [DBG] prompt, but you have all the known variables and their output in the left debug pane. To improve navigation through debugging options, the top debug bar makes it easier to enter, exit, and pass breakpoints. Plus, you don’t have to save before you run!

the VS Code PowerShell Extension is necessary for it to work easily.

Using Commands Debugging Commands

Although debugging strictly from the command line is not sometimes the easiest operation, you can do it using the built-in debugging commands. There are a few built-in commands to make it easier for you.

Using the versatile Set-PSBreakPoint, you can quickly set a breakpoint which, when hit, will drop you into the debug command prompt. At this point, using the standard key combinations, you can quickly inspect the variables and continue or interrupt execution at this point.

Conclusion

Debugging doesn’t need to be difficult, and once you start using any of the methods above, you’ll find it built into your scripting development needs. Find out how you can get started with PowerShell debugging today!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.