PowerShell Pipeline
Exploring PowerShell, Part 2: Learn the Commands Using Get-Help
Get a wealth of command information quickly with Get-Help.
More on This Topic:
Our next stop on our exploration of using PowerShell involves learning more about what Get-Help can do for you. When you are attempting to figure out a command might work or just need to see what some of the parameters are along with their expected type, you will usually end up typing something like this:
Get-Help Get-Process
The result is a wealth of knowledge that appears on your screen to assist with seeing what the command has for parameters. You can also check out the description as well as related links to this particular command.
[Click on image for larger view.] Figure 1. Help text for Get-Process.
Just from this we can tell what the command does based on the description and as I mentioned before, are able to view all of the parameters and its expected type to supply to the parameter as an argument.
But we aren't going to stop there! There are more things that we can do with Get-Help to dive deeper into what a command can do. Want to see an example of what a command can do? Just use the –Examples switch and depending on the command that you want to see, you will be shown multiple variations of examples of how to use the command.
Get-Help Get-Process -Examples
[Click on image for larger view.] Figure 2. 3 of 8 examples for Get-Process.
What you have here are just a handful of examples that are available for Get-Process that show you various ways of which you can use this command. Some examples are very simple while others can show more complex examples.
If you want to know more about a particular parameter, you can specify –Parameter <parameter name> and you will be showed more detailed information about that parameter. This will show you a description about the parameter as well as some other metadata which can help to determine how you can use it.
Get-Help Get-Process -Parameter Name
[Click on image for larger view.] Figure 3.
Here we can see that the Name parameter accepts arguments by propertyname and is not a mandatory parameter (Required? = false). We also have more information about what this parameter is used for and how you can use it as well.
If you want to see everything that is in the help system for a command, you can throw down –Full and you will in fact get the full help.
This gives you everything plus the kitchen sink. I am talking about being showed the detailed information about each parameter, a more complete description as well as other various items such as the expected output type of the command.
About* Help Files
Besides the help files for cmdlets and functions, there are also about_ files which give you a bunch of information about topics such as data types, parameter attributes as well PowerShell remoting and profiles. For a list of all of the about* help files, just run the following code:
Get-Help about
Pretty much anything you want to know can be found in these files. The next you want to learn about something such as operator precedence, you can search the about topic.
[Click on image for larger view.] Figure 4.
Help File a Day
For a little fun, if you wanted to have a "help file a day" to help learn more from the files, you can fun the following command to get a random help file to look at.
(Get-Random -InputObject (Get-Help about*)) | Get-Help -ShowWindow
Just run this whenever you want and you can learn something new or just get a refresher on something that you might already know.
Updating the Help System
Starting with PowerShell V3, you no longer get the help files right off the bat. In an effort to provide the most up to date help available for a command, you now have to download the help files to your local machine in order to view the information. This is great for systems that always have network access but can become a little more of a challenge with systems that do not have access to the Internet. This is the price you pay for having up to date help files. Luckily, the process to update the files isn't exactly difficult and can be accomplished based on the situation.
Updating from the Internet
First we will take care of the machine that has a connection to the Internet. For this we will use Update-Help and specify some parameters to show that we want to update the help on all modules by specifying a wildcard value. Depending on your firewall or some sort of proxy, you may want to also specify –UseDefaultCredentials.
Update-Help -Module * -UICulture en-us -Verbose -ErrorAction SilentlyContinue
Figure 3. Updating the help from the Internet
[Click on image for larger view.] Figure 5. Updating the help from the Internet.
After a couple of minutes, all of my help has been updated. If it's the first time, then you now officially have help for your commands! If this isn't the first time, well now you have the most up to date help available for your commands. So either way, it is a big plus!
Updating from Another System
Let's assume that you do not have access to the Internet for all of your systems and you want all of your computers to have access to the help files. As long as you have some system that can reach out to the Internet, you can ensure that all of the systems have up to date help files. We can do this using a couple of cmdlets: Save-Help and Update-Help.
Using Save-Help on an Internet connected system will allow us to download the help files and save those onto the local system.
New-Item -Path C:\PowerShellHelp -Type Directory
Save-Help -DestinationPath C:\PowerShellHelp -Module * -Verbose
[Click on image for larger view.] Figure 6. Saving help files for non-Internet connected systems.
We can verify that we actually have help files.
[Click on image for larger view.] Figure 7.Verification of help files downloaded.
Now from one of our systems which does not have an Internet connection, we can make use of Update-Help and point to the location of the system that has the help files.
Update-Help -Module * -SourcePath \\boe-pc\PowerShellHelp -Recurse -Verbose
To completely automate this task, we can set up a scheduled task to download the files:
#Code needed to save the help files
$Code = "Save-Help -DestinationPath C:\PowerShellHelp -Module *"
#Ensure it runs at specified time and day
$Trigger = New-ScheduledTaskTrigger -DaysOfWeek Saturday -At '12:00 AM' -Weekly
$Principal = New-ScheduledTaskPrincipal -UserId "Network Service" -RunLevel Highest -LogonType Interactive
$Action = New-ScheduledTaskAction -Execute "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" `
-Argument "-Command &{$($Code)}"
$Setting = New-ScheduledTaskSettingsSet
#Create the task with all of the proper configurations
$Task = New-ScheduledTask -Action $Action -Trigger $Trigger -Settings $Setting -Principal $Principal
#Complete the scheduled job creation
Register-ScheduledTask -InputObject $Task -TaskName "PowerShellDownloadHelp"
And then on our other systems, we can set up a task to update the help from our share location.
#Code needed to save the help files
$Code = "Update-Help -SourcePath \\boe-pc\PowerShellHelp -Module * -Recurse"
#Ensure it runs at specified time and day
$Trigger = New-ScheduledTaskTrigger -DaysOfWeek Saturday -At '6:00 AM' -Weekly
$Principal = New-ScheduledTaskPrincipal -UserId "Network Service" -RunLevel Highest -LogonType Interactive
$Action = New-ScheduledTaskAction -Execute "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" `
-Argument "-Command &{$($Code)}"
$Setting = New-ScheduledTaskSettingsSet
#Create the task with all of the proper configurations
$Task = New-ScheduledTask -Action $Action -Trigger $Trigger -Settings $Setting -Principal $Principal
#Complete the scheduled job creation
Register-ScheduledTask -InputObject $Task -TaskName "PowerShellUpdateHelp"
And now you can sit back and not have to worry about your help files being out of date the next time you need them!
With that, we have looked at how we can use the help system in PowerShell to assist us in tracking down commands, examples and even other subjects. Not only that, but now we have automated our downloading and updating of the help system so we can have those updated the next time we need them.
About the Author
Boe Prox is a Microsoft MVP in Windows PowerShell and a Senior Windows System Administrator. He has worked in the IT field since 2003, and he supports a variety of different platforms. He is a contributing author in PowerShell Deep Dives with chapters about WSUS and TCP communication. He is a moderator on the Hey, Scripting Guy! forum, and he has been a judge for the Scripting Games. He has presented talks on the topics of WSUS and PowerShell as well as runspaces to PowerShell user groups. He is an Honorary Scripting Guy, and he has submitted a number of posts as a to Microsoft's Hey, Scripting Guy! He also has a number of open source projects available on Codeplex and GitHub. His personal blog is at http://learn-powershell.net.