Overview of Windows PowerShell 3.0

Working with the help options

One of the first commands to run when opening Windows PowerShell for the first time is the Update-Help cmdlet. This is because Windows PowerShell does not ship help files with the product. This does not mean that no help presents itself—it does mean that help beyond simple syntax display requires an additional download.

A default installation of Windows PowerShell 3.0 contains numerous modules that vary from installation to installation depending upon the operating system features and roles selected. In fact, Windows PowerShell 3.0 installed on Windows 7 workstations contains far fewer modules and cmdlets than are available on a similar Windows 8 workstation. This does not mean all is chaos, however, because the essential Windows PowerShell cmdlets—the core cmdlets—remain unchanged from installation to installation. The difference between installations is because additional features and roles often install additional Windows PowerShell modules and cmdlets.

The modular nature of Windows PowerShell requires additional consideration when updating help. Simply running Update-Help does not update all of the modules loaded on a particular system. In fact, some modules may not support updatable help at all—these generate an error when you attempt to update help. The easiest way to ensure you update all possible help is to use both the module parameter and the force switched parameter. The command to update help for all installed modules (that support updatable help) is shown here:

Update-Help -Module * -Force

The result of running the Update-Help cmdlet on a typical Windows 8 client system is shown in Figure 1-1.

Figure 1-1 Errors appear when attempting to update help files that do not support updatable help.

One way to update help and not to receive a screen full of error messages is to run the Update-Help cmdlet and suppress the errors all together. This technique appears here:

Update-Help -Module * -Force -ea 0

The problem with this approach is that you can never be certain that you have actually received updated help for everything you wanted to update. A better approach is to hide the errors during the update process, but also to display errors after the update completes. The advantage to this approach is the ability to display cleaner errors. The UpdateHelpTrackErrors.ps1 script illustrates this technique. The first thing the UpdateHelpTrackErrors.ps1 script does is to empty the error stack by calling the clear method. Next, it calls the Update-Help module with both the module parameter and the force switched parameter. In addition, it uses the ErrorAction parameter (ea is an alias for this parameter) with a value of 0. A 0 value means that errors will not be displayed when the command runs. The script concludes by using a For loop to walk through the errors and displays the error exceptions. The complete UpdateHelpTrackErrors.ps1 script appears here.

UpdateHelpTrackErrors.ps1
$error.Clear()
Update-Help -Module * -Force -ea 0
For ($i = 0 ; $i -lt $error.Count ; $i ++)
  { "'nerror $i" ; $error[$i].exception }

Once the UpdateHelpTrackErrors script runs, a progress bar displays indicating the progress as the updatable help files update. Once the script completes, any errors appear in order. The script and associated errors appear in Figure 1-2.

Figure 1-2 Cleaner error output from updatable help generated by the UpdateHelpTrackErrors script.

You can also determine which modules receive updated help by running the Update-Help cmdlet with the -verbose parameter. Unfortunately, when you do this, the output scrolls by so fast that it is hard to see what has actually updated. To solve this problem, redirect the verbose output to a text file. In the command that follows, all modules attempt to update help. The verbose messages redirect to a text file named updatedhelp.txt in a folder named fso off the root.

Update-Help -module * -force -verbose 4>>c:\fso\updatedhelp.txt

Windows PowerShell has a high level of discoverability; that is, to learn how to use PowerShell, you can simply use PowerShell. Online help serves an important role in assisting in this discoverability. The help system in Windows PowerShell can be entered by several methods. To learn about using Windows PowerShell, use the Get-Help cmdlet as follows:

Get-Help Get-Help

This command prints out help about the Get-Help cmdlet. The output from this cmdlet is illustrated here:

NAME
    Get-Help

SYNOPSIS
    Displays information about Windows PowerShell commands and concepts.


SYNTAX
    Get-Help [[-Name] <String>] [-Category <String>] [-Component <String>] [-Full
    [<SwitchParameter>]] [-Functionality <String>] [-Path <String>] [-Role
    <String>] [<CommonParameters>]

    Get-Help [[-Name] <String>] [-Category <String>] [-Component <String>]
    [-Functionality <String>] [-Path <String>] [-Role <String>] -Detailed
    [<SwitchParameter>] [<CommonParameters>]

    Get-Help [[-Name] <String>] [-Category <String>] [-Component <String>]
    [-Functionality <String>] [-Path <String>] [-Role <String>] -Examples
    [<SwitchParameter>] [<CommonParameters>]

    Get-Help [[-Name] <String>] [-Category <String>] [-Component <String>]
    [-Functionality <String>] [-Path <String>] [-Role <String>] -Online
    [<SwitchParameter>] [<CommonParameters>]

    Get-Help [[-Name] <String>] [-Category <String>] [-Component <String>]
    [-Functionality <String>] [-Path <String>] [-Role <String>] -Parameter <String>
    [<CommonParameters>]

    Get-Help [[-Name] <String>] [-Category <String>] [-Component <String>]
    [-Functionality <String>] [-Path <String>] [-Role <String>] -ShowWindow
    [<SwitchParameter>] [<CommonParameters>]


DESCRIPTION
    The Get-Help cmdlet displays information about Windows PowerShell concepts and
    commands, including cmdlets, providers, functions, aliases and scripts.

    Get-Help gets the help content that it displays from help files on your
    computer. Without the help files, Get-Help displays only basic information
    about commands. Some Windows PowerShell modules come with help files. However,
    beginning in Windows PowerShell 3.0, the modules that come with Windows
    PowerShell do not include help files. To download or update the help files for
    a module in Windows PowerShell 3.0, use the Update-Help cmdlet. You can also
    view the help topics for Windows PowerShell online in the TechNet Library at http:
    //go.microsoft.com/fwlink/?LinkID=107116

    To get help for a Windows PowerShell command, type "Get-Help" followed by the
    command name. To get a list of all help topics on your system, type "Get-Help
    *".

    Conceptual help topics in Windows PowerShell begin with "about_", such as
    "about_Comparison_Operators". To see all "about_" topics, type "Get-Help
    about_*". To see a particular topic, type "Get-Help about_<topic-name>", such
    as "Get-Help about_Comparison_Operators".

    You can display the entire help topic or use the parameters of the Get-Help
    cmdlet to get selected parts of the topic, such as the syntax, parameters, or
    examples. You can also use the Online parameter to display an online version of
    a help topic for a command in your Internet browser.

    If you type "Get-Help" followed by the exact name of a help topic, or by a word
    unique to a help topic, Get-Help displays the topic contents. If you enter a
    word or word pattern that appears in several help topic titles, Get-Help
    displays a list of the matching titles. If you enter a word that does not
    appear in any help topic titles, Get-Help displays a list of topics that
    include that word in their contents.

    In addition to "Get-Help", you can also type "help" or "man", which displays
    one screen of text at a time, or "<cmdlet-name> -?", which is identical to
    Get-Help but works only for cmdlets.

    For information about the symbols that Get-Help displays in the command syntax
    diagram, see about_Command_Syntax http://go.microsoft.com/fwlink/?LinkID=113215.
    For information about parameter attributes, such as Required and Position, see
    about_Parameters http://go.microsoft.com/fwlink/?LinkID=113243.


RELATED LINKS
    Online Version: http://go.microsoft.com/fwlink/?LinkID=113316
    Get-Command
    Get-Member
    Get-PSDrive
    about_Command_Syntax
    about_Comment_Based_Help
    about_Parameters

REMARKS
    To see the examples, type: "Get-Help Get-Help -examples".
    For more information, type: "Get-Help Get-Help -detailed".
    For technical information, type: "Get-Help Get-Help -full".
    For online help, type: "Get-Help Get-Help -online"

The good thing about help with the Windows PowerShell is that it not only displays help about cmdlets, which you would expect, but it also has three levels of display: normal, detailed, and full. Additionally, you can obtain help about concepts in Windows PowerShell. This last feature is equivalent to having an online instruction manual. To retrieve a listing of all the conceptual help articles, use the Get-Help about* command, as follows:

Get-Help about*

Suppose you do not remember the exact name of the cmdlet you wish to use, but you remember it was a get cmdlet? You can use a wildcard, such as an asterisk (*), to obtain the name of the cmdlet. This is shown here:

Get-Help get*

This technique of using a wildcard operator can be extended further. If you remember that the cmdlet was a get cmdlet, and that it started with the letter p, you can use the following syntax to retrieve the desired cmdlet:

Get-Help get-p*

Suppose, however, that you know the exact name of the cmdlet, but you cannot exactly remember the syntax. For this scenario, you can use the -examples argument. For example, for the Get-PSDrive cmdlet, you would use Get-Help with the -examples argument, as follows:

Get-Help Get-PSDrive -examples

To see help displayed one page at a time, you can use the Help function. The Help function passes your input to the Get-Help cmdlet, and pipelines the resulting information to the more.com utility. This causes output to display one page at a time in the Windows PowerShell console. This is useful if you want to avoid scrolling up and down to see the help output.

This formatted output is shown in Figure 1-3.

Figure 1-3 Using Help to display information one page at a time.

Getting tired of typing Get-Help all the time? After all, it is eight characters long. The solution is to create an alias to the Get-Help cmdlet. An alias is a shortcut keystroke combination that will launch a program or cmdlet when typed. In the “Creating an alias for the Get-Help cmdlet” procedure, you will assign the Get-Help cmdlet to the G+H key combination.

Creating an alias for the Get-Help cmdlet

1. Open Windows PowerShell by choosing Start | Run | Windows PowerShell. The PowerShell prompt will open by default at the root of your Documents folder.

2. Retrieve an alphabetic listing of all currently defined aliases, and inspect the list for one assigned to either the Get-Help cmdlet or the keystroke combination G+H. The command to do this is as follows:

   Get-Alias sort

3. After you have determined that there is no alias for the Get-Help cmdlet and that none is assigned to the G+H keystroke combination, review the syntax for the New-Alias cmdlet. Use the -full argument to the Get-Help cmdlet. This is shown here:

   Get-Help New-Alias -full

4. Use the New-Alias cmdlet to assign the G+H keystroke combination to the Get-Help cmdlet. To do this, use the following command:

   New-Alias gh Get-Help