If you are using or are just beginning to use PowerShell,
chances are that you’ve been on a few Google expeditions to learn how to use
the various commands available in PowerShell. While that is all well and good,
you should know that PowerShell itself is packed with very detailed Help that
can really be of assistance as you figure out how to put PowerShell to work.

For example, the Help in PowerShell provides detailed
descriptions and syntax for each command and includes examples as well as links
to more sources of information. However, all this information is locked away in
PowerShell’s command line interface. Fortunately, I have devised a system for
extracting and keeping track of the information packed into PowerShell, thus
making it more accessible. Let’s take a closer look.

 

Caveats

Keep in mind that in order to perform all of the techniques
shown in this article, you must have Windows PowerShell 3 or above installed on
your system. Windows 8 comes with Windows PowerShell 3, but if you are using
Windows 7, you will need to upgrade to
Windows PowerShell 3
.

Overview

In my PowerShell Help system technique, you’ll basically be
creating a set of specially named text files in a folder. By using the special
naming format I’ll show you, all of your files will be organized in such a way
that they are easy to keep track of, thus making it easier to find exactly what
you’re looking for when you need assistance.

Keep in mind that this system is designed to be created on
an as needed basis. You really won’t want to sit down and create Help files for
every single command in PowerShell at one time. In other words, you will want
to create a Help file when you are investigating and using a command for a
specific task. That way, when you are working with the command now and in the
future, the Help file will be readily available.

Preparation

Before we get started there are two things that you need to
do to prepare for your PowerShell Help system. The first thing that you need to
do is create a folder in which to store your files. On my example system, I
created a folder called PowerShell in the root directory of the C drive. Doing
so will make it easier to work from the command line, since you won’t have to
deal with long path names.

The second thing that you need to do is make sure that the
internal, command line version of the PowerShell help system is current. To do
so, navigate to your PowerShell folder in File Explorer. Pull down the File
menu in File Explorer and select Open Windows PowerShell | Open Windows
PowerShell as administrator, as shown in Figure
A. Of course, you’ll have to deal with the UAC prompt.

Figure A

You’ll need to open PowerShell as an administrator.

Once you are at the PowerShell prompt, type Update-Help and
press enter. When you do, PowerShell will download the newest help files for
PowerShell’s commands and then install them on your computer, as shown in Figure B. It will take a few minutes
for this download and installation process to occur.

Figure B

You can download and install the newest help files for
PowerShell.

Build a module list

PowerShell is literally packed with commands in the form of cmdlets,
scripts, and functions. That’s why I suggest that you begin creating your
PowerShell Help system with a list of the installed modules. You can think of
modules as categorical containers of commands. By starting with a list of
categorical containers, you’ll more easily be able to find the particular
command you are looking for.

To build a list of modules in PowerShell, type the following
command line at the PowerShell prompt:

Get-Module -ListAvailable | Format-Table Name, ModuleType > A_List_of_Modules.txt

If we break this command line down into its three pieces,
we’ll see that the main part of this command line lists all of the available
modules.

Get-Module -ListAvailable

This list is then piped into a formatting cmdlet that puts
the list into a table.

| Format-Table Name, ModuleType

The formatted table is then redirected to a text file.

> A_List_of_Modules.txt

Get a list of commands in a module

Once you have a list of all the available modules, you can
pick the module that you are interested in and find out what commands are in
that module. To do so, you’ll type the following command line at the PowerShell
prompt:

Get-Command -Module {module-name} | Format-Table Name, CommandType > Commands_in_{module-name}.txt

Where {module-name}
is the name of the module that you are interested in.

If we break this command line down into its three pieces,
we’ll see that the main part of this command line lists all of the commands in
the module.

Get-Command -Module {module-name}

This list is then piped into a formatting cmdlet that puts
the list into a table.

| Format-Table Name, CommandType

The formatted table is then redirected to a text file.

> Commands_in_{module-name}.txt

Create the Help file

Once you have a list of all the commands in a module, you
can pick the command that you are interested in and generate the text-based
Help file. To do so, you’ll type the following command line at the PowerShell
prompt:

Get-Help {command-name} > Help_for_{command-name}.txt

Where {command-name}
is the name of the command that you are interested in.

If we break this command line down into its two pieces,
we’ll see that the main part of this command line accesses the Help content.

Get-Help {command-name}

That content is then redirected to a text file.

> Help_for_{command-name}.txt

The results

Once you have created some of these files in your PowerShell
folder, you’ll begin to see how the file naming convention will organize your
PowerShell Help system. As you can see in Figure
C, the list of modules will be at the top of the folder, the list of
commands in the modules will be next, and the Help for each individual command
will be at the bottom.

Figure C

My file naming convention keeps the files neatly organized
in the folder.

When you open a Help file in Notepad or WordPad, as shown in
Figure D, you’ll see that each Help
file contains six sections of information about the command.

  • Name
  • Synopsis
  • Syntax
  • Description
  • Related Links
  • Remarks

Figure D

A Help file opened in WordPad.

The first four sections provide pretty basic information and
are self-explanatory; however, the last two sections offer further assistance.
In the Related links section, you’ll find a list of related commands that might
help you zero in on the operation you are attempting to make use of.

The Remarks section is of particular note as it will tell
you how to get even more information about the command. For instance, you’ll
find out how to get examples of the command being used as well as how to get more
detailed information about the command. You’ll also see that you can access the
online version of Help for a particular command. (Keep in mind that not all
commands have online Help that can be accessed from the PowerShell command
line.)

Using this technique, you can now construct your own, more
easily accessible, PowerShell Help system.