Microsoft

Quick Tip: Create an easily accessible PowerShell 3.0 Help system

Make help for PowerShell more accessible with a method devised for extracting and tracking information in the built-in system.

PSHlp_Intro_Image_9-16-2013.png
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

PSHlp Fig A.png

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

PSHlp Fig B.png

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

PSHlp Fig C.png

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

PSHlp Fig D.png

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.

About

Greg Shultz is a freelance Technical Writer. Previously, he has worked as Documentation Specialist in the software industry, a Technical Support Specialist in educational industry, and a Technical Journalist in the computer publishing industry.

4 comments
penguin80
penguin80

You really don't need to create all those .txt files.  Powershell  3.0 added another parameter to the get-help cmdlet that will open a separate window with all the pertinent help information for the -full parm

 get-help {Command Name} -showwindow

 This method also gets the updates when you do update-help where you would have to recreate the affected txt files.

Craig_B
Craig_B

If you use this method you may want to use the -full switch, which will give you all information in the Help file, including Examples.

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

Mark W. Kaelin
Mark W. Kaelin moderator

Do you take advantage of PowerShell in Windows? Could you use a simpler way to access help files?

Greg Shultz
Greg Shultz

@Craig_BYes, using the -full switch will give you everything.

For the purposes of this article, I chose to use the basic listing so that I could show the contents in a screen shot as well as illustrate the availability of the additional options.

Did you find this to be a useful tip?

Editor's Picks