Getting help

Help is never far away in PowerShell Core and, in this section, you'll learn how to utilize the help to your benefit.

Getting ready

In order to follow this recipe, you should have completed the installation of PowerShell Core for your operating system.

How to do it...

Please perform the following steps:

1. Open PowerShell Core.
2. Type the Get-Help cmdlet and hit Enter. The cmdlet displays help about the help system.

3. Use the -? parameter with any cmdlet, for example, Start-Process -?. Notice the output after this cmdlet. You can see the syntax of the cmdlet, as well as some additional remarks:

4. Type the Get-Help Start-Process -Parameter FilePath command. Note the output at that point. Only help for the FilePath parameter is returned. From the output, you can see that the parameter is mandatory, has two aliases, and doesn't like pipeline input:

5. Type the Get-Help Start-Process -Full command. You can notice in the output that indeed no help files have been downloaded yet.

6. Type the Update-Help -Scope CurrentUser command to download all current help content.
7. Examine the folder contents of $home\Documents\PowerShell\Help in Windows and ~/.local/share/powershell in Linux.
8. Type the Update-Help -Module CimCmdlets -UICulture ja-jp,sv-se command. Notice that not all modules provide localized help content—the content in en-us should be available for most modules, however.
9. Now that the help content has downloaded, try Get-Help Start-Process -Full again.
10. Notice that now the full content is available, allowing you to get additional information about a cmdlet.

How it works...

The help system of PowerShell Core can be used to update help files from the internet or from a CIFS share. Without updated help content, the help system always displays the name and syntax of a cmdlet as well as detailed parameter help for all parameters of a cmdlet.

In order to update help for modules on the local system, Update-Help will examine all modules in the PSModulePath environmental variable in order to find all modules that have the HelpInfoUri property set. It'll try to resolve the URI, which should point to a browsable website where it will then look for an XML file called <ModuleName>_<ModuleGuid>_HelpInfo.xml. Inside this XML file, the location of a cabinet file (*.cab) is stored, which will then be used to download the actual content.

With the new Scope parameter introduced in PowerShell Core, all help content will be placed in the personal user folder, for example, C:\Users\<UserName>\Documents\PowerShell, instead of a system-wide folder that would require administrative privileges, for example, C:\Program Files\PowerShell.

The Update-Help cmdlet will only download new content once per day if the cmdlet is called. In order to download the content more frequently, you can use the Force parameter.

There's more...

Help content can also be hosted on-premises by using the Save-Help cmdlet and distributing the content. On Windows systems, a group policy setting can be found that can control the default path for Update-Help as well. This setting is in Administrative Templates | Windows Components | System | Windows PowerShell. This setting is only valid for Windows PowerShell. Regardless of the edition, the Update-Help cmdlet supports the SourcePath parameter to specify from where the help content will be downloaded.

In order to provide your own help content properly, have a look at the PowerShell module, PlatyPS. This module makes it very easy to generate help content for your own modules, package it to the correct format, and much more.

PlatyPS supports markdown help, enabling you to write help content in a very easy way that feels more natural than creating large and complex MAML files.

See also

• Help overview: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_updatable_help?view=powershell-6
• PowerShell module to generate help content: https://github.com/powershell/platyps