PowerShell Basics: Take Advantage of the PowerShell Integrated Scripting Environment

If you've been using Windows PowerShell for a while, you already know what a valuable tool it can be for working with information from a wide range of sources. At times, however, PowerShell's command shell can seem somewhat clunky, if not outright annoying. Simple operations such as copying, pasting, and moving lines of code can turn into cumbersome processes that are often more difficult than re-entering the code from scratch.

To counter the command shell's limitation, developers often use a second program concurrently with PowerShell. For example, they might use Notepad's text editing capabilities to prepare the code before pasting it into the console window or a source code editor like Notepad++ to take advantage of more advanced features, including auto-completion, multi-document tabs, and syntax outline regions. Yet, as handy as these tools are, you're still jumping between multiple interfaces to get the job done.

That's where the PowerShell Integrated Scripting Environment (ISE) comes in. The PowerShell ISE is a host application that lets you write and edit your scripts as you would in a text editor and run your scripts as you would in a command shell. The PowerShell ISE provides you with the flexibility of both worlds in a single graphical environment that is easy to use and includes lots of extras, such as syntax coloring, debugging capabilities, context-sensitive help, and much more.

Be aware, however, that not all versions of the ISE are created equal. The first version, PowerShell ISE 2.0, was released shortly after PowerShell 2.0 came out. ISE 2.0 provides basic functionality, but it is a pared-down version compared to what the ISE is today.

With the release of PowerShell 3.0 came PowerShell ISE 3.0, which includes many of the features now touted as ISE drawing cards, such as auto-save, snippets, IntelliSense, and add-on tools. Because ISE 2.0 lacks so many of these features, I'll focus on version 3.0 only. But keep in mind that PowerShell ISE 4.0 is just around the corner. Microsoft plans to ship it—along with PowerShell 4.0—with the release of Windows 8.1 and Windows Server 2012 R2. (For a list of Windows OSs and their default PowerShell ISE versions, see the TechNet article "Windows PowerShell Integrated Scripting Environment (ISE).") Based on what I've seen so far, there doesn't appear to be any significant changes between the PowerShell ISE 3.0 and PowerShell ISE 4.0 interfaces.

The best part about the PowerShell ISE, regardless of the version, is that it's free and is installed automatically with PowerShell. So there's little reason not to start using the tool today. You just need to know how all the pieces fit together and where to begin—then you'll be ready to go.

The PowerShell ISE Interface

It takes little time to become familiar with the main components of the PowerShell ISE interface. The ISE window is divided into three panes:

Figure 1 shows the three panes displayed in the PowerShell ISE window. The Script Pane is at the top, the Console Pane is at the bottom, and the Add-on Tools Pane is to the right. However, you can control whether and where the panes are displayed by selecting the appropriate option in the View menu. In addition, the Add-ons menu provides you with more options for displaying add-ons. The PowerShell ISE window also includes several other menus and options for managing and editing your PowerShell scripts, most of which are self-explanatory.

Figure 1: Exploring the Three Main Panes of the PowerShell ISE Window

The Script and Console Panes you see in Figure 1 are considered a single PowerShell tab. When you open the PowerShell ISE, only one PowerShell tab is displayed. However, you can open additional PowerShell tabs, and within each one, you can open Script and Console Panes. For example, Figure 2 shows the PowerShell ISE window with three open PowerShell tabs, with the first tab being the active one.

Figure 2: Working with Multiple Tabs in the PowerShell ISE Window

The Script Pane can itself contain multiple tabs, each with its own script file. For example, in Figure 2, notice that there are four script files open in the Script Pane and each script file is assigned to its own tab. The Console Pane shows part of the results from running the commands in the first script file. If you were to run a command in one of the other script tabs, those results would be added after the existing results in the Console Pane, unless you were to clear the console. (All script tabs in a PowerShell tab share a common Console Pane.) But if you were to go to a different PowerShell tab, the Console Pane would be its own instance, pointing to either the local computer or a remote one. In other words, you can think of each PowerShell tab as a connection to a particular computer. By default, that computer is the local one.

Customizing the PowerShell ISE Interface

The PowerShell ISE provides a number of options for customizing the interface. You can access these options by pointing to the Tools menu and clicking Options. When the Options dialog box appears, it opens to the Colors and Fonts tab, as shown in Figure 3. Here you can set the colors and fonts used in the Script and Console Panes. You'll find you can be fairly specific in terms of how you want to color various language elements in the Script and Console Panes.

Figure 3: Customizing PowerShell ISE Colors and Fonts

In addition, you can select a theme that defines the color and font settings. This saves you the trouble of having to set colors individually, assuming a theme meets your needs.

Whichever approach you use to select the colors, once you've made your selections, you can apply the changes immediately. Those changes should then, in theory, persist when you restart the PowerShell ISE. Unfortunately, the PowerShell ISE can be a bit buggy when selecting the background colors for the Console Pane. When you restart the PowerShell ISE, you might find that the background colors aren't quite what you expected.

For this reason, you might consider using a script to modify the settings and save that script to one of the profile files. For example, you might use the following script to change the background color of the Console Pane:

$psISE.Options.ConsolePaneBackgroundColor = 'white'

This script calls the Options property associated with the $psISE variable. This built-in PowerShell variable returns the object Microsoft.PowerShell.Host.ISE.ObjectModelRoot. The object's Options property lets you access the various options that control the appearance and behavior of the PowerShell ISE window. In this case, you're accessing the ConsolePaneBackgroundColor option and setting its value to white.

You can easily retrieve a list of the current settings and their values by running the command:

$psISE.Options

From there, you can write the necessary script to set your colors and fonts. For details about the $psISE.Options property, see the TechNet article "The ISEOptions Object."

Once you understand how to use the $psISE.Options property to customize the PowerShell ISE interface, you might want to persist your settings so they're automatically applied when you start the PowerShell ISE. To do so, you can add your scripts to one of the profile files, as mentioned earlier. But be aware that not all the profile files used for the PowerShell ISE are the same as those used for the PowerShell command shell. You might need to create and edit these files separately from the regular profile files. For a good overview of how to create and edit a PowerShell ISE profile file, see the TechNet article "How to Create Profiles in Windows PowerShell ISE."

In addition to configuring the colors and fonts used in the PowerShell ISE, you can configure a number of other options on the General Settings tab of the Options dialog box, which is shown in Figure 4. Here you can configure settings related to the Script Pane behavior, IntelliSense, and other aspects of the PowerShell ISE window. Alternatively, you can use the $psISE.Options property to configure these settings.

Figure 4: Customizing PowerShell ISE Property Settings

Scripting in the PowerShell ISE

Let's get to the fun part of the PowerShell ISE: the actual scripting. Although many of the editing features are available in both the Script and Console Panes, it's the Script Pane that keeps most administrators smiling. From there, you can do just about everything, including running all or part of a script. With that said, there's still plenty to like about the Console Pane.

One fun feature available in both panes is context-sensitive help. To access this feature, you just need to place your cursor within a cmdlet's text and click F1. This launches a separate window that provides details about the cmdlet, including its syntax, the parameters it supports, and examples that show the cmdlet in action. For instance, Figure 5 shows the Help file that's displayed for the Get-Service cmdlet. If you were to scroll down this window, you would find numerous details about the cmdlet, in addition to what's shown in the figure.

Figure 5: Accessing the Context-Sensitive Help File for the Get-Service Cmdlet

Note, however, that the context-sensitive help system doesn't always get it right. Suppose you're creating a foreach control flow statement. If you place your cursor in the foreach keyword, the system displays the Help file for the ForEach-Object cmdlet, not the foreach control flow statement. Even so, the feature works well in most cases. It can save you a lot of time by getting the information you need right when you need it.

Another great PowerShell ISE feature is IntelliSense, an auto-completion window that pops up when you start typing the name of a cmdlet, parameter, parameter value, file, or folder. What is displayed depends on the context of your command.

When the IntelliSense window appears, you can scroll to the PowerShell language element you're looking for and easily insert it into your script. For example, Figure 6 shows the IntelliSense window that appears when you type get-s. In this case, there are three possible cmdlets from which to choose. If one of those cmdlets is the one you want, you simply select it and it's automatically inserted into your script.

Figure 6: Working with IntelliSense

It's helpful to know about the colors used for the various types of language elements in the PowerShell ISE. For example, notice the many different colors used in the Script Pane in Figure 7. Commands are green, variables are red, cmdlets are blue, and so on. The Console Pane also displays language elements in color when you first type them in your script—that is, until you run your code. Then everything reverts to the base color. The colors shown in Figure 7 are the PowerShell ISE default settings, but as noted earlier, you can modify them to fit your preferences.

Figure 7: Exploring Color-Coded Keywords

In Figure 7, you might have noticed that the Script Pane includes regions, which are also referred to as outline views. Regions are those sections of code preceded by a vertical line, and at the top of the line is a plus or minus sign. If you click that sign, you can collapse or expand that section of code. For example, the first region in Figure 7 starts with the #region tag and ends with the #endregion tag. Everything within that region can be collapsed into a single line that can be expanded at any time. Regions are available only in the Script Pane.

The PowerShell ISE supports two types of regions: user-defined regions and system-set regions (i.e., regions set by the PowerShell ISE). The user-defined regions start with the #region tag and end with the #endregion tag. You simply add the tags and include any other details you want after the tag. Administrators typically include details with only the #region tag. For instance, the first #region tag in Figure 7 includes the label variables.

In addition to user-defined regions, the PowerShell ISE automatically defines regions for expressions in curly brackets that are part of statements such as if and foreach. In Figure 7, you can see two system-set regions. The first one starts directly beneath the first line of the if statement (line 12). The second one starts directly beneath the first line of the foreach statement (line 17). As this example shows, regions can be embedded in each other.

Figure 8 shows how the system-set regions appear when they're collapsed. As you can see, regions provide an easy way to look at your script's big picture to better ensure that its logic is correct. If you want to re-expand any of the regions, you simply click the plus sign.

Figure 8: Working with Regions in PowerShell Scripts

Another valuable feature in the PowerShell ISE is a collection of snippets—short pieces of PowerShell code that you can use as templates when developing your scripts. You can even add your own snippets to the collection.

Figure 9: Accessing Code Snippets from Within the PowerShell ISE

To add a snippet to a script, you simply position your cursor where you want to insert the code and press Ctrl+J. This launches a pop-up window that lists the available snippets. You can then scroll through the list, select the snippet you want, and view its code. For example, Figure 9 shows the code for the do-while snippet. If it's the code you want, you just need to double-click the snippet in the pop-up window to insert the code in your script. As you can see in Figure 10, the basic components of the do-while statement are inserted. It's up to you to fill in the blanks.

Figure 10: Inserting a Code Snippet in a Script

Now let's look at one more aspect of scripting in the PowerShell ISE. As noted earlier, the Commands add-on is included with the PowerShell ISE and is displayed in the Add-on Tools Pane. In Figure 10, notice that the Commands add-on lists all available PowerShell commands. You can pare down the list by searching for commands based on a specific module, a specific name, or both.

Figure 11: Working with the Commands Add-On

However, the Commands add-on does more than just list the available commands. If you select a specific command, you'll be provided with options for constructing, running, inserting, and copying it, as shown in Figure 11. In this case, the Get-Service cmdlet is selected. Notice that three tabs are displayed. Each tab corresponds to a syntax form available to the cmdlet. Within each tab, you can select parameters or specify their values. In other words, you have a graphical interface for building commands, which is an especially useful feature if you're not familiar with a particular command or if you're new to PowerShell altogether. Once you've built your command, you can run it, insert it into the Console Pane, or copy it so you can paste it wherever you want.

Debugging Scripts in the PowerShell ISE

The PowerShell ISE provides a set of tools to help you debug your code in the Script Pane. Basically, you set one or more breakpoints within your script, then run the script. When the processor reaches the first breakpoint, it pauses until you choose to continue. At each breakpoint, you can examine the values stored in the variables at the time you hit the breakpoint. This can help ensure that your code's logic is working as expected and the variable values are what you expect them to be.

To set a breakpoint, you position your cursor on the line where you want to stop your code's execution. You then right-click the line and click Toggle Breakpoint. Any lines set as breakpoints are highlighted, as shown in Figure 12. In this case, two breakpoints have been set: one at line 18 and one at line 26.

Figure 12: Setting Breakpoints in a Script

If you now press F5, the script will start running and will continue to run until it reaches the first breakpoint. At this time, the highlight will change colors, as shown in Figure 13. In addition, the cursor in the Console Pane will be preceded by [DBG] to show you're in debugging mode and you'll receive a message indicating where you've hit the breakpoint.

Figure 13: Debugging a Script in the PowerShell ISE

To continue running the script, click F5 again and the PowerShell ISE will pick up where it left off. It will run until it hits the next breakpoint. However, if a breakpoint is inserted within a control flow statement, such as the foreach statement shown in Figure 13, the script will stop at the same breakpoint until the statement iterates through every item in the collection. For example, if you look at the Console Pane shown in Figure 14, you'll see that the script stopped at the same break point four times, indicating that there were four items in the initial foreach collection ($svcs1). From there, the script continued to the next breakpoint at line 26, which is where the script was stopped.

Figure 14: Iterating Through Breakpoints When Debugging a Script

Whenever you hit a breakpoint, you can examine the contents of any variable at that moment. You need only hover your cursor over a variable name, and the current values are displayed, as shown in Figure 15. In this case, the PowerShell ISE is displaying the $svcs2 variable's contents, which are the services that aren't running. If you were to look at the contents of the $svc variable, you'd find the name of only one service.

Figure 15: Reviewing Variable Values When Debugging a Script

The World of the PowerShell ISE

The PowerShell ISE includes numerous features that you can use to help streamline your development efforts. This tool also supports additional features that I haven't covered here, such brace matching, error indication, Unicode support, zoom capabilities, and the ability to automatically save open scripts.

Although I've only touched upon the PowerShell ISE features, you should have a good idea of the potential that the PowerShell ISE holds. Given that Microsoft provides the PowerShell ISE for free with your PowerShell installation, you have little to lose by trying it out. And you might even find you have a whole lot to gain.