You want to use PowerShell's debugging commands through an interface more friendly than its *-PsBreakpoint cmdlets.

Use the Debug menu in the Integrated Scripting Environment to add and remove breakpoints, and manage debugging behavior when PowerShell reaches a breakpoint.

Figure 19.2. Debugging options in the Integrated Scripting Environment

The PowerShell Integrated Scripting Environment (ISE) gives you a rich set of interactive graphical debugging commands to help you diagnose errors in your scrpts. It exposes these through the Debug menu, and behaves like many other graphical debugging environments you may have experience with.

To set a breakpoint, first save your script. Then, select the "Toggle Breakpoint" menu item, the "Toggle Breakpoint" option that shows when you right-click in the left-hand margin of the ISE, or press F9. Once PowerShell hits that line in your script, it pauses to let you examine variables, script state, and whatever else interests you. To control the flow of execution, you can use the stepping commands: Step Over, Step Into, and Step Out.

Step Over continues to the next line of the script, executing (but not debugging into) any function calls that you come across. Step Into continues to the next line of the script, debugging into any function calls that you come across. If you are in a function, the Step Out command lets PowerShell complete execution of the function, and resumes debugging once the function completes.

One unique aspect of debugging in the ISE is that it builds its support entirely on the core debugging cmdlets discussed in Chapter 14, Debugging. Changes that you make from the debugging menu (such as adding a breakpoint) get immediately reflected in the cmdlets (such as listing breakpoints.) Likewise, breakpoints that you add or modify from the integrated command line show up in the user interface as though you had created them from the debug menu itself.

Unlike most graphical debugging environments, the PowerShell ISE makes it incredibly easy to investigate the dynamic state of your script while you are debugging it. For more information about how to investigate the state of your script while debugging, see the section called “Investigate System State While Debugging”.

You want to change the color scheme of the Integrated Scripting Environment, or colors used for syntax highlighting.

Review the properties of the $psISE.Options automatic variable, and customize the ones you want. For example, to give the output pane the same appearance as the PowerShell console:

$psISE.Options.OutputPaneBackgroundColor = "#012456"
$psISE.Options.OutputPaneForegroundColor = "#EEEDF0"
$psISE.Options.OutputPaneTextBackgroundColor = "#012456"

While working in the Integrated Scripting Environment (ISE), you might sometimes wonder, "Where is the Options dialog?"

The answer is that there isn't one. Instead, the ISE offers a wealth of configuration option through its $psISE automatic variable.

PS > $psISE.Options | Format-List


SelectedScriptPaneState       : Top
ShowToolBar                   : True
TokenColors                   : {[Attribute, #FFADD8E6], [Command, #FF0000FF], 
                                [CommandArgument, #FF8A2BE2], [CommandParameter
                                , #FF000080]...}
DefaultOptions                : Microsoft.PowerShell.Host.ISE.ISEOptions
FontSize                      : 12
FontName                      : Consolas
ErrorForegroundColor          : #FFFF0000
ErrorBackgroundColor          : #00FFFFFF
WarningForegroundColor        : #FFFF8C00
WarningBackgroundColor        : #00FFFFFF
VerboseForegroundColor        : #FF0000FF
VerboseBackgroundColor        : #00FFFFFF
DebugForegroundColor          : #FF0000FF
DebugBackgroundColor          : #00FFFFFF
OutputPaneBackgroundColor     : #FF012456
OutputPaneTextBackgroundColor : #FF012456
OutputPaneForegroundColor     : #FFEEEDF0
CommandPaneBackgroundColor    : #FFFFFFFF
ScriptPaneBackgroundColor     : #FFFFFFFF
ScriptPaneForegroundColor     : #FF000000
ShowWarningForDuplicateFiles  : True
ShowWarningBeforeSavingOnRun  : True
UseLocalHelp                  : True
CommandPaneUp                 : False

You can change these options as easily as you change any other automatic variable—by assigning new values to its properties (as shown in the solution.) To make these changes affect all of your ISE sessions, simply store them in the host-specific profile file for the ISE. To edit this file, simply type: ise $profile.CurrentUserCurrentHost.

In addition to user interface customization, the ISE also lets you customize the colors it uses for syntax highlighting. It exposes these settings through the $psISE.Options.TokenColors automatic variable. For example, to change the coloring of attributes (such as the [Parameter()] statement) to be more like regular types, type:

$psIse.Options.TokenColors["Attribute"] = $psIse.Options.TokenColors["Type"]

For more information about modifying your PowerShell profile, see the section called “Customize Your Shell, Profile, and Prompt”.

You want to create a new tab in the Integrated Scripting Environment that represents a connection to a remote computer.

Click the "New Remote PowerShell Tab" icon in the toolbar or File menu.

One of the features most requested for the PowerShell console application is support for multiple tabs and multiple sessions. As such, multi-tab support in the ISE is prominent—and gets a unique treatment.

To create a new tab that represents a local PowerShell session, simply click the "New PowerShell Tab" icon in the toolbar or File menu. If you want to connect to a remote computer instead, just click the "New Remote PowerShell Tab" menu or toolbar icon.

Once you've connected a remote PowerShell tab, interacting with a remote system is just like interacting with a local one. Prompts from the remote system show up like prompts from the local system, as do progress bars, credential requests, and PowerShell's other feedback mechanisms.

For more information about PowerShell Remoting, see Chapter 29, Remoting.

You want to customize the PowerShell ISE to add your own functionality and features.

Explore and modify properties of the $psISE automatic variable to interact with the ISE's object model. For example, to clean up trailing spaces from the script you are currently editing:

$psISE.CurrentFile.Editor.Text = 
    $psise.CurrentFile.Editor.Text -replace '(?m)\s+$',''

In addition to the features already available, the PowerShell ISE offers many additional customization opportunities through its object model. The object model exposes the nuts and bolts you need to create your own functionality—and makes it available through the $psISE automatic variable. the section called “Add an Item to the Tools Menu” demonstrates one aspect of the object model by showing how to add items to the Add-ons menu.

As with other .NET object models, the Get-Member and Format-List cmdlets are the keys to exploring the ISE's object model. At its first level, the object model gives you access to the current file, PowerShell tab, and ISE options:

PS > $psISE | Format-List


CurrentPowerShellTab : Microsoft.PowerShell.Host.ISE.PowerShellTab
CurrentFile          : Microsoft.PowerShell.Host.ISE.ISEFile
Options              : Microsoft.PowerShell.Host.ISE.ISEOptions
PowerShellTabs       : {PowerShell 1}

For example, the $psISE.CurrentFile.Editor variable provides programmatic access to the text and behavior of the current scripting pane:

PS > $psISE.CurrentFile.Editor | Get-Member

   TypeName: Microsoft.Windows.PowerShell.Gui.Internal.ScriptEditor
   
Name             MemberType Definition
----             ---------- ----------
PropertyChanged  Event      System.ComponentModel.PropertyChangedEventHandler...
Clear            Method     System.Void Clear()
EnsureVisible    Method     System.Void EnsureVisible(int lineNumber)
Equals           Method     bool Equals(System.Object obj)
Focus            Method     System.Void Focus()
GetHashCode      Method     int GetHashCode()
GetLineLength    Method     int GetLineLength(int lineNumber)
GetType          Method     type GetType()
InsertText       Method     System.Void InsertText(string text)
Select           Method     System.Void Select(int startLine, int startColumn,...
SetCaretPosition Method     System.Void SetCaretPosition(int lineNumber, int c...
ToString         Method     string ToString()
CaretColumn      Property   System.Int32 CaretColumn {get;}
CaretLine        Property   System.Int32 CaretLine {get;}
LineCount        Property   System.Int32 LineCount {get;}
SelectedText     Property   System.String SelectedText {get;}
Text             Property   System.String Text {get;set;}

By building on the object model, you can write tools to automatically process your scripts (commenting, uncommenting), script output, and more.

For more information about working with .NET objects, see the section called “Work with .NET Objects”.

You want to add your own menu items and shortcuts to the Integrated Scripting Environment.

Pick a display name, action, and (optional) shortcut, then add those to the $psISE.CurrentPowerShellTab.AddOnsMenu.Submenus collection:

$psISE.CurrentPowerShellTab.AddOnsMenu.Submenus.Add(
    "PowerShell Blog",
    { Start-Process http://blogs.msdn.com/PowerShell },
    "Control+Alt+B")

As part of its extensibility features, the PowerShell ISE gives you complete access to a sub-menu of your very own: the Add-ons menu.

To work with the Add-ons menu, access the $psISE.CurrentPowerShellTab.AddOnsMenu variable.

By default, menu items that get added have no shortcuts, so you must click them to activate them. To add a typical menu shortcut that becomes active once the Add Ons menu is active, put an underscore (_) character before the letter that you want to activate your menu item.

To define a hotkey available through the entire application, supply the keys as the third argument for the Add() method. If you don't want to assign a global hotkey, use $null as the third argument.

For more information about extending the ISE, see the section called “Extend ISE Functionality Through its Object Model”.