Live with help (Simple)

In Windows PowerShell – prerequisites, we have gone through different facets that we can use in Windows PowerShell. There are a few features, such as discoverability, object orientation, and easy transition to scripting, that make this language incomparable and make it stand out from others.

One of the best and crucial functions of Windows PowerShell is its discoverability. The Windows PowerShell engine itself holds a strongly embedded help system that provides precise information to the users regarding various aspects such as getting the CMDLET description, syntax, and examples.

The help system is enabled with the dynamic search capability; you can use any random keyword to surf any CMDLETs (commands are known as CMDLETs—pronounced as commandlets). It is not limited to CMDLETs; it also avails "about help system" and help information of functions and modules. In Version 3.0, there has been a lot of enhancements in the help system structure.

Getting ready

In the previous versions, if we install WMF in our machine, it will install the help system available with that WMF package at the time of installation. We do not have any way to update our help system later; the only way is to reinstall the WMF package with the latest updates.

To overcome this issue, the Windows PowerShell team has introduced two new CMDLETs in Version 3.0 to update the help system: Update-Help and Save-Help.

If you are installing WMF 3.0 on your operating system for the first time or running fresh operating system as Windows Server 2012 or Windows 8, by default, Windows PowerShell v3.0 will not have any help system embedded into it. You need to manually update the help system to utilize the discoverability feature in the Windows PowerShell v3.0 console.

How to do it...

1. Use the Update-Help CMDLET, without any parameters, to update the help filesystem for all current sessions and all the modules installed in a PSModulePath location.

   To run the Update-Help CMDLET, you must be a member of the administrative group and start the PowerShell console using the Run as administrator option. Also, your computer should be able to connect to the Internet. If not, you can specify the filesystem directory by placing updated help files in it using Save-Help. The Update-Help CMDLET downloads the latest help files for Windows PowerShell core modules and installs them on your local computer.

   You can use the Get-Help CMDLET immediately after the Update-Help CMDLET to access the updated filesystem. You need not restart your machine to put these changes in effect.

   PS C :\> Update-Help
   

2. The module parameter name is used to provide multiple module names in a comma-separated list for updating the help system; whereas UICulture is used to specify the language in which you want your help files to be updated.

   PS C :\> Update-Help -Module Microsoft.PowerShell* -UICulture en-US
   

   The preceding command statement updates help files for all module names starting with Microsoft.PowerShell in the English language.

   Tip

   If you want to update the help system automatically when you launch the console, specify the Update-Help CMDLET in your Windows PowerShell profile.

   The Windows PowerShell profile is a simple profile.ps1 script which runs at the start of each PowerShell console instance. By default, the Update-Help CMDLET only runs once a day on a single computer. It is not necessary that all modules would support updatable help.

3. The following command statement would list all the modules that support updatable help:

   PS C :\> Get-Module -ListAvailable | Where HelpInfoUri
   

   Use the Force parameter name to override the once-per-day limitation of version checking and the 1 GB per module limit.

   PS C :\> Update-Help –Module * -Force
   

   The preceding command statement attempts to update help files unconditionally for all modules installed in your computer, including those that do not support updatable help systems.

   PS C :\> Get-Module | Update-Help
   

   You can also pipe the Get-Module CMDLET output to Update-Help. It updates the help files of all the modules in current sessions.

How it works…

If your computer is not directly connected to the Internet and you want to update the help system, there is one CMDLET introduced in Version 3.0 called Save-Help.

The Save-Help CMDLET downloads and saves the latest help files to the specified filesystem directory. You can carry these help files into removable devices or copy them into the network file share location. This CMDLET will be useful in installing updated help files on multiple computers by downloading help files once on a single computer and storing them in a shared location.

Also, to run the Save-Help CMDLET, you must be a member of the administrative group and start the PowerShell console using the Run as administrator option. Save-Help saves the downloaded help files in cabinet (.cab) files in the destination directory. The saved help files consist of a help information (HelpInfo XML) file and a cabinet (.cab) file for each module installed in a PSModulePath location.

PS C :\> Save-Help -DestinationPath C:\UpdatedHelp

The preceding command statement downloads and saves updated help files for all the modules in the UpdatedHelp directory in a local computer's C:.

The DestinationPath parameter name needs to specify the destination directory in which we wish to place all the downloaded help files.

PS C :\> Save-Help -Module Microsoft.PowerShell* -DestinationPath \\FileSrv001\UpdatedHelp

The preceding command statement downloads updated help files for module names that start with Microsoft.PowerShell and stores them in the \\FileSrv001\UpdatedHelp directory.

PS C :\> Update-Help -SourcePath \\FileSrv001\UpdatedHelp -Credential PSDomain\PSAdmin

The preceding command statement updates the help system from the specified shared location and domain administrator credential. It prompts for the administrator password and updates the help system offline.

If you want to update the help system for multiple computers in a single click, use the following command:

PS C :\> Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock {Update-Help -SourcePath \\FileSrv001\UpdatedHelp -Credential PSDomain\PSAdmin}

Using the preceding command statement, Invoke-Command runs the given ScriptBlock parameter on all the remote computers specified in Servers.txt. The remote computers must be able to access the file share instead of using the Internet.

With the beginning of Windows PowerShell 4.0, Save-Help can also save help files for the modules that are installed on remote computers. It works as described:

PS C :\> $session = New-PSSession -ComputerName PSTest

The preceding command statement creates a remote PowerShell session on the PSTest remote computer.

PS C :\> $modlist = Get-Module -PSSession $session –ListAvailable

Then, using the session object created by running the previous command statement, it retrieves the list of modules that are installed on the PSTest remote computer.

PS C :\> Save-Help -Module $modlist -DestinationPath \\FileSrv001\UpdatedHelp

Finally, it downloads and saves the help files for the modules that are fetched in the previous command statement. We can use the Update-Help CMDLET again to install help files on multiple computers from a centralized file share.

There's more…

There are a few tricks using which we can effectively leverage the discoverability feature within the Windows PowerShell console. This section discusses a few among those.

How you discover the commands

Once your help system is updated, you can choose any dumb keyword and start demanding to the Windows PowerShell console. Let's say I want to know all the information about the log keyword.

PS C :\> Get-Help *log*

The following screenshot describes search results for the log keyword:

It will list out all the CMDLETs, functions, and help files that contain the log keyword. You can pick any one of them and start discovering further help. For example, I want to check the help of Get-EventLog.

PS C :\> Get-Help Get-EventLog

It throws an output listing information specific to the Get-EventLog CMDLET, such as Name, Synopsis, Syntax, Description, and Related links.

Ask for help

There are a number of tricks by which you can surf through the help content in a short time.

PS C :\> Get-Help about*

The preceding command will list out all the about help topics covering aliases operators, arrays, functions, methods, remote, scripts, variables, and many more.

For example, the following command gives all the detailed information about new features included in Windows PowerShell Version 3.0:

PS C :\> Get-Help about_Windows_PowerShell_3.0

The ShowWindow parameter

Sometimes, it could be boring to refer help files into the blue Windows PowerShell console for a long time. To overcome this, we have the –ShowWindow parameter that comes with the Get-Help CMDLET supported in Version 3.

PS C :\> Get-Help Get-Command –ShowWindow

It provides a graphical view of the help files and opens in another window with search capabilities.