How to properly use PowerShell help

I. Introduction

Whether online or in the console, PowerShell help is indispensable for obtaining information on the operation of a cmdlet, a method, etc., and for obtaining examples of its use. In this chapter, we'll look at how to use PowerShell help effectively.

When using PowerShell, there's bound to come a time when you'll get stuck on using a cmdlet. Perhaps you don't understand how a parameter works, which parameters are mandatory and so on. In that case, you need help.

When you're looking for help with PowerShell command-line administration or PowerShell scripting, there are several sources of information to choose from.

• The following PowerShell cmdlets : Get-Command, Get-Help and Get-Member
• The official Microsoft documentation dedicated to PowerShell, available on this page.
• Internet tutorials, especially those available on IT-Connect, as they can provide additional examples of use.

When you're more comfortable with PowerShell, you can also rely on artificial intelligence, such as GitHub Copilot or ChatGPT. But, to be able to interpret and adapt the proposals of these AI tools, a good grounding in PowerShell is recommended.

III. PowerShell and Get-Command

Do you need to perform an action, but don't know the name of the corresponding PowerShell command? Or perhaps you can't remember the exact name of the command you used last time... "Get-Command can help.

This cmdlet, which we've already used, is used to obtain a list of commands available on the local machine. It's particularly useful when used with the wildcard character (the asterisk), as it enables a keyword search.

Imagine you want to restart your computer in PowerShell, but you've forgotten the name of the command. You don't know whether it's "Reboot-Computer", "Shutdown-Computer" or "Restart-Computer". With "Get-Command", you can search for the keyword "Computer":

Get-Command *Computer*

In the command output, we can see the "Restart-Computer" cmdlet. Interesting stuff!

Does this cmdlet, present in the "Microsoft.PowerShell.Management" module, meet our needs? In other words, does it allow you to restart your computer? Although everything suggests that it does, let's find out.

II. PowerShell and Get-Help

A. Getting help with a PowerShell cmdlet

PowerShell's "Get-Help " cmdlet lets you consult the help for each cmdlet, based on information stored locally on your machine. It will help you find out more about the purpose of a cmdlet, its parameters, and provide examples of its use.

Let's take the "Restart-Computer" cmdlet as an example:

Get-Help -Name Restart-Computer
# ou
Get-Help Restart-Computer

We can see that the command returns a help file consisting of several sections: SYNOPSIS, SYNTAX, DESCRIPTION, etc. It reads: "Restarts the operating system on local and remote computers". It reads:"Restarts the operating system on local and remote computers".- Now we know for sure: the "Restart-Computer" cmdlet is used to restart a computer.

It's also possible to get help via"Get-Help", using this syntax :

<Cmdlet name> -?
# Par exemple :
Restart-Computer -?

If you're not happy with the help returned by default and would like to display more information, you can use the various parameters offered by "Get-Help" :

• Get examples of use (returns examples only) :

Get-Help Restart-Computer -Examples
# or 
Restart-Computer -? -Examples

Being able to access usage examples from the PowerShell console is very practical:

• Get the detailed view, with description, parameters and examples of use:

Get-Help Restart-Computer -Detailed
# or 
Restart-Computer -? -Detailed

• Get full help, with description, parameters (and how they work), examples, and objects accepted as input and output:

Get-Help Restart-Computer -Full
# or 
Restart-Computer -? -Full

B. Ask for Microsoft Learn online help

Consulting help from the PowerShell console is all very well, but it's not always very pleasant: the help for some cmdlets is very long. In this case, it's best to rely on online help, accessible from a web browser. . Note that Microsoft documentation includes a help page dedicated to each PowerShell cmdlet!

To access this help, you can use your favorite search engine. Generally speaking, a Google search simply on the cmdlet name will bring up the corresponding page in the official documentation as the first result.

Alternatively, and this is worth knowing, you can use the "Get-Help" cmdlet so that it takes you directly to the help page corresponding to your query:

Get-Help Restart-Computer -Online

In fact, the"-Online" parameter will open the help page with your browser. So you don't need to search for the page yourself.

This help page contains the same sections as the local help, with description, syntax, parameters, examples... In fact, you have direct access to the complete help (equivalent to the"-Full" parameter). The Microsoft Learn site is a must for PowerShell help.

In addition, on the left, you can select your PowerShell version : this allows you to display the help that corresponds to the version you're using (this is important, as a cmdlet can evolve from one version to another).

If you need further help using "Get-Help" itself, use this command:

Get-Help Get-Help

III. Update local help

Please note that the local PowerShell help returned by the "Get-Help" cmdlet may be out of date or incomplete. Indeed, in some cases, the result returned by this command will be empty! This means that PowerShell has not found local help for the cmdlet in question.

Microsoft has thought of everything, since the "Update-Help" cmdlet is used to update local help. It will download the latest help files and store them locally on your machine.

To update all the help, which can be quite time-consuming, simply run the cmdlet without any parameters:

Update-Help

You can update the help for a specific module by specifying its name:

Update-Help -Module <nom du module>
# Example 
Update-Help -Module Microsoft.PowerShell*

Finally, the "Update-Help" cmdlet can retrieve help files from a network location (network share accessible via a UNC path) using the"-SourcePath" parameter. This provides a local source for updating help on a set of machines. This implies downloading the help files beforehand using the"Save-Help" cmdlet.

For further information, please consult the help for these two cmdlets:

Get-Help Update-Help
Get-Help Save-Help

Bear in mind that the online help provided by Microsoft is the most up-to-date version.

Note : since PowerShell 6.0, you must be an administrator to update the help. Otherwise, you must specify the operation scope with the"-Scope" parameter introduced in PowerShell 6.1.

IV. Conclusion

Now you can consult the help for a PowerShell cmdlet, either from the console or from Microsoft documentation. The "Get-Member" cmdlet mentioned in the introduction to this chapter will be studied in the next chapter of this course.