Debugging: How to debug a PowerShell script
Debugging is the process of finding and resolving issues within a computer program (software). In this article, I will be discussing some steps that you can employ to debug and fix issues in your PowerShell script. Kindly take a look at some articles on PowerShell that I have created. How to automate Windows Update with PowerShell and Task Scheduler, how to install Microsoft PSWindowsUpdate module Silently (unattended) mode.
Debugging pauses the execution code and runs the code either line by line or in whatsoever fashion you desire. The Debug-Process cmdlet attaches a debugger to one or more running processes on a local computer. This cmdlet attaches the debugger that is currently registered for the process.
Reasons to debug a script by a System Administrator
Here are a few reasons, why a System Administrator would decide to debug a script
- To troubleshoot the errors and to help determine the cause of an error and have it fixed.
To see how code runs and understand it better, especially if you are not the one who wrote it in the first place. - To debug a PowerShell script, follow the steps below. Before you start debugging, you must set one or more breakpoints. You cannot set a breakpoint unless the script is saved.
Now you want to set one or more breakpoints by selecting the line of code where you want to place the breakpoint and then right-click on “Toggle Breakpoint” or press F9. I am using this script from the Windows Update Policy for this demonstration.
A breakpoint is a designated spot in a script where you would like the operation to pause so that you can examine the current state of the variables and the environment in which your script is running.
Once your script is paused by a breakpoint, you can run commands in the Console Pane to examine the state of your script.
Run the code by pressing F5 or make a call to the script and the code will run as usual until it reaches a breakpoint that will switch to debugging mode and we can go through the code to debug it.
We can continue line by line by pressing F11 “Step Into” as shown in the image below. If the current statement is a function or a script call, then the debugger steps into that function or script, and we can continue debugging in that function.
PowerShell debugging tasks
To fully leverage and understand the debugging functionality of PowerShell, let’s review some of its debugging tasks as shown below.
| Task | Description | Shortcut |
|---|---|---|
| Step Into | Executes the current statement and then stops at the next statement. If the current statement is a function or script call, then the debugger steps into that function or script, otherwise it stops at the next statement. | Press F11 or, on the Debug menu, click Step Into, or in the Console Pane, type S and press ENTER. |
| Step Over | Executes the current statement and then stops at the next statement. If the current statement is a function or script call, then the debugger executes the whole function or script, and it stops at the next statement after the function call. | Press F10 or, on the Debug menu, click Step Over, or in the Console Pane, type V and press ENTER. |
| Step Out | Steps out of the current function and up one level if the function is nested. If in the main body, the script is executed to the end, or to the next breakpoint. The skipped statements are executed, but not stepped through. | Press SHIFT+F11, or on the Debug menu, click Step Out, or in the Console Pane, type O and press ENTER. |
| Continue | Continues execution to the end, or to the next breakpoint. The skipped functions and invocations are executed, but not stepped through. | Press F5 or, on the Debug menu, click Run/Continue, or in the Console |
Debugging a PowerShell script
Note: Here are some additional tasks that can be performed while debugging your PowerShell script.
Remove All Breakpoints: If you think you might want to use it again, consider disabling the Breakpoint instead.
Disable All Breakpoints: Disabling a breakpoint does not remove it; it turns it off until it is enabled. To disable a specific line breakpoint, right-click the line where you want to disable a breakpoint, and then click Disable Breakpoint.
List breakpoints: Displays all breakpoints in the current Windows PowerShell session.
If we want to remove the breakpoint click on that line of code and press F9. Basically, F9 is to turn on and off the breakpoint on the line where is a cursor or mouse point.
Note: Debugging in the ISE is great because you can use keyboard shortcuts to set breakpoints on various lines of code. When you hit that breakpoint, it shows up in the ISE, making it easier to tell where you are. The following table lists the keyboard shortcut.
Other tools
There are many other tools out there, but I will mention a few.
1. PS Script Analyzer
PSScriptAnalyzer provides script analysis and checks for potential code defects in the scripts by applying a group of built-in or customized rules on the scripts being analyzed. See this guide for more information on “How to perform PowerShell syntax check with PSScriptAnalyzer“.
Note: I do not recommend the manual download of PS Script Analyzer, as the file won’t be unpacked, and won’t include any dependencies. You can simply use the command below by copying and pasting to install this package using PowerShellGet.
Install-Module -Name PSScriptAnalyzer -RequiredVersion 1.11.0
2: Pester
Pester is a test framework for PowerShell. It provides a language that allows you to define test cases, and the Invoke-Pester cmdlet to execute these tests and report the results.
I hope you found this blog post helpful. Please let me know in the comment session if you have any questions.
