Editing and Debugging Scripts with PowerShell 2.0's Integrated Scripting Environment

Downloads
104713.zip

In the first version of Windows PowerShell, Microsoft didn't provide an integrated development environment (IDE) for PowerShell. In PowerShell 2.0, the PowerShell team filled that gap by adding a PowerShell IDE called the Integrated Scripting Environment (ISE). It provides an easy-to-use interface for editing and debugging scripts.

Figure 1 shows the ISE window, and Table 1 describes the elements labeled in Figure 1. The ISE window is divided into three panes by default:

• The script pane (element F) is the ISE's script editor. You can open multiple files and switch between them easily. When you open more than one file, each file gets its own tab. The script editor colorizes script code to help you identify syntax errors, automatically indents lines of code, and provides Tab-key command and path completion for paths, cmdlets, and cmdlet parameters.
• The output pane (element G) shows the output from PowerShell scripts and commands executed in the ISE.
• The command pane (element I) is an interactive PowerShell prompt.

Floating the mouse cursor over the toolbar buttons displays the buttons' functions in pop-up tooltips. The ISE's shortcut keys aren't shown in the toolbar button tooltips, but they are displayed in the menus.

All of PowerShell's Help topics are available in the ISE. Press F1 to access them. If you position the cursor on a cmdlet name, pressing F1 will open the PowerShell Help file to that cmdlet's Help page.

Navigating the ISE

The tabs at the top of the script pane represent open script files. When you start a new script (select File, New or press Ctrl+N) or open an existing script (select File, Open or press Ctrl+O), the ISE adds a new script tab (element D) to the top of the script pane.

In addition to script tabs, you can also open a new PowerShell tab (element C), which appears above the script tabs, as shown in Figure 1. Each PowerShell tab represents a new PowerShell instance, or execution environment, inside the ISE. This means that variables, functions, and aliases that you create in one PowerShell tab aren't visible when you switch to a different PowerShell tab. (Opening a new PowerShell tab is like starting a new powershell.exe console instance.) You open a new PowerShell tab by selecting File, New PowerShell Tab or by pressing Ctrl+T. Note that when only one PowerShell tab is open, it's not shown.

You can adjust the ISE's three panes several different ways using the View menu:

• You can select Show Script Pane Top (or press Ctrl+1) to move the script pane to the top of the ISE window. This is the default configuration.
• You can select Show Script Pane Right (or press Ctrl+2) to move the script pane to the right half of the ISE window.
• You can select Show Script Pane Maximized (or press Ctrl+3) to hide the command and output panes, maximizing the screen real estate for editing scripts.
• You can select Hide Script Pane (or press Ctrl+R) to hide the script pane, making more room for the command and output panes. Clicking the button next to element E in Figure 1 will also hide the script pane.
• You can select Command Pane Up to move the command pane above the output pane. This option doesn't have a keyboard shortcut, but clicking the button next to element H in Figure 1 will also move the command pane up.

Opening and Editing Scripts

There are four ways you can open a PowerShell script for editing in the ISE:

1. Choose Open on the File menu (or press Ctrl+O) and select a PowerShell script from the Open dialog box.
2. Use the mouse to drag and drop a PowerShell script onto an ISE window or shortcut icon.
3. Right-click on the PowerShell script in Windows Explorer and choose Edit.
4. Use the psEdit command (which is actually a predefined function) in the command window and specify the path and filename to the script. For example, the command

 psEdit C:\Scripts\TestScript.ps1

loads the file TestScript.ps1 into a new script tab. An error will appear in the output pane if the file doesn't exist.

 You can open multiple scripts in the ISE using any of these four techniques. Each script will open in its own script tab. Table 2 lists the keystroke commands available in the ISE's script editor.

Running Scripts or Selected Code

Once a PowerShell script is loaded into the script pane, you can run it by choosing Run on the File menu or by pressing the F5 key. PowerShell will run the script as if you typed the script's filename in the command pane and pressed Enter. If you want to run only a portion of a script, select the code you want to run and choose Run Selection on the File menu or press F8. PowerShell will execute the code you've selected as if you entered it in the command pane. In both cases, the output appears in the output window.

Debugging Scripts

The ISE lets you debug PowerShell scripts from its easy-to-use interface. Debugging is the process of suspending a PowerShell script as it's running so you can identify and correct problems in the code. To debug a script in the ISE, load it into the ISE's script pane, set one or more breakpoints that suspend the script, and examine the values of variables while the script is suspended to determine the cause of the problem.

For example, MathTest.ps1 in Listing 1 is a script with a single function called math-power that contains a logic error.

Listing 1: MathTest.ps1
 
# Raises a positive whole number to a power.
function math-power(\\[Int\\] $number, \\[Int\\] $power) \\{
  if ($power -eq 0) \\{
    1
  \\}
  else \\{
    $result = $number
    for ($i = 1; $i -le $power; $i++) \\{
      $result *= $number
    \\}
    $result
  \\}
\\}

math-power 2 2  # Should output 4.

I'll use this script to demonstrate how to use the ISE's debugging capabilities. To follow along, download MathTest.ps1 by clicking the Download the Code Here button near the top of the page and save the 104713.zip file on your machine. After you've extracted MathTest.ps1, follow these steps:

1. Open MathTest.ps1 in the script pane by using one of the four techniques described in the "Opening and Editing PowerShell Scripts" section. Press F5 to run the script. The math-power function is supposed to raise a positive whole number to a specified power. In this case, it's raising the whole number of 2 to the second power. However, notice that the result is 8 instead of 4, so there's obviously something wrong with the function.
2. Move the cursor to the first line of the function (line 3) and press F9 (or choose Toggle Breakpoint on the Debug menu). A breakpoint is a portion of code, usually a line, that suspends the script as it's running. The ISE will highlight the line with a dark red background to indicate a breakpoint is set on it.
3. Press F5 (or choose Run/Continue on the Debug menu) to run the script. The ISE will suspend the script on the breakpoint line, which will be highlighted with a dark yellow background, as Figure 2 shows. Notice how the prompt in the command pane changes to >>> and the output pane indicates that a breakpoint has been hit. While a script is suspended, you can float the mouse pointer over a variable to display the current value of that variable.
   
4. Press the F11 key (or choose Step Into on the Debug menu). The F11 key causes the debugger to step to the next line in the script. Because the $power variable isn't zero, the next line in the script is line 7, where the $result variable is set to $number.
5. Continue pressing F11 until the ISE pauses on line 11, where it returns the $result variable. Examine the value of the $i variable by floating the mouse pointer over it, as shown in Figure 3. You've found the logic flaw: The for loop has iterated three times instead of two. Press F5 to finish running the script, and the output pane shows the result of 8.
   
6. Correct the bug by changing the initial assignment of the $i variable in the for loop to 2 instead of 1 and save the script. Go to line 3, press F9 to disable the breakpoint, and press F5 to run the script again. It now outputs the value 4 as it should. (The 104713.zip file includes the corrected version of the script, CorrectedMathTest.ps1.)

The debugger is much more useful with larger scripts that have many variables, but this example should help you get started with using this helpful tool.

Add the ISE to Your Toolkit

The ISE is a truly valuable PowerShell enhancement. I've provided only a cursory overview of its script editor and debugger. I recommend that you add the ISE to your PowerShell toolkit by downloading PowerShell 2.0. This version is installed with Windows 7 and Windows Server 2008 R2, so you don't need to install PowerShell 2.0 separately if you're using those OSs. If you have Server 2008, Windows Server 2003, Windows Vista, or Windows XP SP3, you need to install the Windows Management Framework Core package from http://support.microsoft.com/kb/968930. Depending on your OS, you might also need to install .NET Framework 2.0 SP1 (for PowerShell 2.0) and .NET Framework 3.0 (for the ISE).