The most important thing to learn in PowerShell

Opinion alert!

Disclaimer: This is, of course, my opinion, but hey, its good stuff to know, so bear with me.

The help system

Give a man a fish and you feed him for a day; teach a man to fish and you feed him for a lifetime.

We’ve all heard that proverb, right? Well, you have now at least. It’s the idea of teaching someone how to help themselves in the hope that they will no longer need assistance for that particular problem. Believe it or not, this applies to PowerShell as well, except in this case I’d like to teach you how to use the help system!

Getting started

Using the help is fairly straightforward. There is a built in command:

Get-Help

Or even the aliases (x):

Help
Man

All you need to do is to give it the command or topic that you’d like to get help for. In this case I’m asking for the help for ‘Get-Process’:

Get-Help Get-Process

Now if you are following along in PowerShell, you just got a nice wall of text that is supposed to be helpful. Let’s break it down so you can both interpret it and eventually write your own help when you start building your own tools in PowerShell.

Get-Help output

As an example, here is the first section of output from Get-Help Get-Process

Get-Help Get-Process

NAME
    Get-Process

SYNOPSIS
    Gets the processes that are running on the local computer or a remote computer.


SYNTAX
    Get-Process [[-Name] <String[]>] [-ComputerName <String[]>] [-FileVersionInfo] [-Module] [<CommonParameters>]

    Get-Process [-ComputerName <String[]>] [-FileVersionInfo] -Id <Int32[]> [-Module] [<CommonParameters>]

    Get-Process [-ComputerName <String[]>] [-FileVersionInfo] -InputObject <Process[]> [-Module] [<CommonParameters>]

    Get-Process -Id <Int32[]> -IncludeUserName [<CommonParameters>]

    Get-Process [[-Name] <String[]>] -IncludeUserName [<CommonParameters>]

    Get-Process -IncludeUserName -InputObject <Process[]> [<CommonParameters>]

Name and Synopsis are self-explanatory, so let’s focus on the Syntax section.

Syntax’s syntax

Each instance of Get-Process in this context is a separate parameter set (x), meaning that each instance is a different way you can run Get-Process.

After the command itself, each word that is prefixed with a hyphen is a parameter, which is required unless it is enclosed in square brackets []. Each parameter is also potentially followed by the required input type unless the parameter is a switch, in which case no input is required for that parameter.

Lets break down the first syntax line:

Get-Process [[-Name] <String[]>] [-ComputerName <String[]>] [-FileVersionInfo] [-Module] [<CommonParameters>]

Here, the parameters are: ‘Name’, which is optional and a string, ‘ComputerName’, which is optional and a string, -FileVersionInfo, which is a switch, ‘Module’, which is a switch, and the ‘CommonParameters’, which we’ll get into.

If a parameter has a type, which ‘Name’ and ‘ComputerName’ both do, they are expected to be used by specifying the parameter and then following it with the expected input type. Like this:

Get-Process -Name PowerShell -ComputerName PC01

Looking at the last Get-Process syntax line:

Get-Process -IncludeUserName -InputObject <Process[]> [<CommonParameters>]

The parameter ‘IncludeUserName’ is a switch and required, ‘InputObject’ is a Process and is also required. To use this parameter set you would have to build a process object first. So maybe something like:

$Process = Get-Process powershell
Get-Process -IncludeUserName -InputObject $Process

That should return all the PowerShell process along with the username of the user that is running them.

Useful parameters

To get more information about the parameters and even examples for a command in PowerShell, we have the -Full parameter for Get-Help:

Get-Help Get-Process -Full

That will have PowerShell retrieve all the help data it has for Get-Process.

This is where I should mention that the Help alias of Get-Help will automatically display the output one page at a time. So lets try that again:

Help Get-Process -Full

Now you should be greeted by a reasonable amount of information. You can use the ‘Enter’ key to go line by line or the space bar to go page by page.

Scrolling through the output, it has a ‘Parameters’ section that will usefully give you information about each parameter. If a parameter is ambiguous, this should describe it in better detail.

My favorite section are the examples! This is where you can see the command in action the way the author meant it to be. This is especially useful if you are using a custom function written for a very specific purpose. To directly access the examples, you can also use the ‘Examples’ switch:

Help Get-Process -Examples

If you are a GUI person, you can check out the ‘ShowWindow’ switch as well, it will display the help as a window with search functionality.

Help Get-Process -ShowWindow

Lastly, for useful parameters in Get-Help, you can also look at the online version of the help, if the cmdlet supports it using the ‘Online’ switch. This will launch the help link in your default browser:

Help Get-Process -Online

Closing thoughts

Don’t ever run this command:

Get-Help Get-Help

It is the PowerShell help system’s equivalent of Googling Google.