Overview of Windows PowerShell 5.0

Working with the help options

One of the first commands to run when you are opening Windows PowerShell for the first time is the Update-Help cmdlet. This is because Windows PowerShell does not include help files with the product, as of Windows PowerShell version 3. 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 5.0 contains numerous modules that vary from installation to installation, depending upon the operating system features and roles selected. In fact, Windows PowerShell 5.0 installed on Windows 7 workstations contains far fewer modules and cmdlets than are available on a similar Windows 10 workstation. This does not mean that 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 you are updating help. Simply running Update-Help does not update all of the modules loaded on a particular system. In fact, some modules might not support updatable help at all—these generate an error when you attempt to update help. The easiest way to ensure that you update all possible help is to use both the -Module parameter and the -Force switch parameter. The command to update help for all installed modules (those that support updatable help) is shown here.

Update-Help -Module * -Force

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

One way to update help and not receive a screen full of error messages is to run the Update-Help cmdlet and suppress the errors altogether. This technique is shown 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 empty the error stack by calling the clear method. Next, it calls the Update-Help module with both the -Module parameter and the -Force switch parameter. In addition, it uses the -ErrorAction parameter (ea is an alias for this parameter) with a value of 0 (zero). 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 by displaying the error exceptions. The complete UpdateHelpTrackErrors.ps1 script is shown here.

UpdateHelpTrackErrors.ps1

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

When the UpdateHelpTrackErrors script runs, a progress bar is shown, indicating the progress as the updatable help files update. When the script is finished, any errors appear in order. The script and associated errors are shown in Figure 1-2.

You can also determine which modules receive updated help by running the Update-Help cmdlet with the -Verbose switch 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 Windows PowerShell, you can simply use Windows 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] [-Functionality <String[]>] [-Path <String>] [-Role <String[]>]
    [<CommonParameters>]

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

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

    Get-Help [[-Name] <String>] [-Category <String[]>] [-Component <String[]>]
    [-Functionality <String[]>] [-Path <String>] [-Role <String[]>] -Online
    [<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
    [<CommonParameters>]


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

    To get help for a Windows PowerShell command, type "Get-Help" followed by the
    command name, such as: Get-Help Get-Process. To get a list of all help topics
    on your system, type: Get-Help *. 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.

    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.

    To get help for a Windows PowerShell provider, type "Get-Help" followed by the
    provider name. For example, to get help for the Certificate provider, type:
    Get-Help Certificate.

    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 commands.

    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 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. To get the online version of a help topic, use the Online parameter,
    such as: Get-Help Get-Process -Online. You can read all of the help topics
    beginning at: http://go.microsoft.com/fwlink/?LinkID=107116.

    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.

    Get-Help can get help topics for all supported languages and locales. Get-Help
    first looks for help files in the locale set for Windows, then in the parent
    locale (such as "pt" for "pt-BR"), and then in a fallback locale. Beginning in
    Windows PowerShell 3.0, if Get-Help does not find help in the fallback locale,
    it looks for help topics in English ("en-US") before returning an error message
    or displaying auto-generated help.

    For information about the symbols that Get-Help displays in the command syntax
    diagram, see about_Command_Syntax. For information about parameter attributes,
    such as Required and Position, see about_Parameters.

    TROUBLESHOOTING NOTE: In Windows PowerShell 3.0 and 4.0, Get-Help cannot find
    About topics in modules unless the module is imported into the current session.
    This is a known issue. To get About topics in a module, import the module,
    either by using the Import-Module cmdlet or by running a cmdlet in the module.


RELATED LINKS
    Online Version: http://go.microsoft.com/fwlink/p/?linkid=289584
    Updatable Help Status Table (http://go.microsoft.com/fwlink/?LinkID=270007)
    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 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 want 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 cmdlet you’re looking for.

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 switch parameter. For example, for the Get-PSDrive cmdlet, you would use Get-Help with the -Examples switch parameter, as follows.

Get-Help Get-PSDrive -examples

To view 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 view the help output.

This formatted output is shown in Figure 1-3.

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 entered. 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 | PowerShell. The Windows PowerShell prompt opens by default at the root of your user 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 switch parameter 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