Disclaimer: This is, of course, my opinion which is why this landed itself in the Soap Box. 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!
Using the help is fairly straightforward. There is a built in command:
Or even the aliases (x):
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’:
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.
As an example, here is the first section of output from
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.
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
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.
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
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
Don’t ever run this command:
It is the PowerShell help system’s equivalent of Googling Google.