Microsoft Windows PowerShell 3.0 First Look

To understand how to update the help, it makes sense to understand what the help is made out of. The help system is comprised of a collection of text- and XML-like files stored in the PowerShell installation directory or within module directories themselves. Long-winded topic discussions are stored simply in about_*.txt files within the PowerShell installation directory. These files are retrieved using Get-Help and specifying the full name or a distinguishable part of the title of the help topics, using the following command:

PS C:\> Get-Help Name about_Modules

The same command would work by just specifying modules as the Name parameter as follows:

PS C:\> Get-Help Name modules

Help that is directly related to cmdlet is stored within a unique format called Microsoft Assistance Markup Language (MAML). The entirety of cmdlet help is formatted into these files; including descriptions, examples, and detailed parameter explanations. The MAML help files are stored within the module directories themselves. The help system parses the different pieces of the MAML document, as you request them using the Get-Help cmdlet.

In the latest version of PowerShell, the help system can now download and install help from the Internet or from the file system. The improved help system now takes advantage of a new key that is a part of the module's manifest. This key, HelpInfoURI, points to the location of the updated help files. Module authors can specify this URI by using the New-ModuleManifest cmdlet or by editing the PSD1 manifest file for a module.

There are two new cmdlets that have been added to the help system. The Save-Help cmdlet is capable of downloading help files from the Internet and storing them packaged as a combination of XML and cabinet (CAB) files. These files can then be provided to Update-Help for installation. Update-Help is capable of both downloading help files from the Internet and installing them. It can consume the files downloaded by Save-Help as well and install them.

The Save-Help cmdlet downloads the help for modules and saves the modules to the local file system or share. As the cmdlet saves the help to the $PSHome\Modules directory, if an alternate path is not specified, you will need to be part of the administrators' group and run an elevated PowerShell command prompt by right-clicking and selecting Run As Administrator. The Save-Help cmdlet uses a HelpInfo XML file of a module to gather the correct URL for downloading the help files. When the help files are downloaded, they will be organized into a single HelpInfo XML file accompanied by several CAB files, one for each language. The CAB files contain the actual help documentation. You don't have to worry about extracting any of the data from the CAB file as the Update-Help cmdlet will do this for you.

The Save-Help cmdlet can specify an alternate path using the LiteralPath or DestinationPath parameters. The LiteralPath parameter will not expand wildcards. Note that the path will not be created by this cmdlet. The following command shows this:

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

You can download help for a single module as well. You cannot specify the help for a single cmdlet. To download help for a single module use the Module parameter as follows:

PS C:\> Save-Help -Module Microsoft.PowerShell.Core -DestinationPath C:\MyHelpDirectory

There is a restriction enforced by the Save-Help cmdlet which prevents you from downloading the help more than once in a 24-hour period. To bypass this you can use the Force parameter, as shown in the following command:

PS C:\> Save-Help -Module Microsoft.PowerShell.Core -Force -DestinationPath C:\MyHelpDirectory

The Update-Help cmdlet is responsible for installing help downloaded from the Internet or local folder or file share. By default, the Update-Help cmdlet will download files from the Internet and install them if they are out of date. If you run Update-Help without parameters it will update help for each module loaded into the current session. You will need to be part of the administrators' group and run as administrator, to update any of the core PowerShell modules, because they are stored in the system directory. This will update all currently loaded modules directly from the Internet if they are out of date. The following command can be used for this:

PS C:\> Update-Help

Alternatively, you can update help from a local folder or file share. The Update-Help cmdlet expects that these files are in the format that Save-Help creates. You will need to have both the HelpInfo XML file along with any CAB files in the specified folder or share. To invoke Update-Help in this way, you can use the LiteralPath or SourcePath parameters as shown in the following command:

PS C:\> Update-Help —SourcePath C:\MyHelpDirectory

Like the Save-Help cmdlet, the Update-Help cmdlet, by default, only allows you to download the help once per day. To bypass this you can use the Force parameter as follows:

PS C:\> Update-Help —Module Microsoft.PowerShell.Core —Force

Again, like the Save-Help cmdlet, the Update-Help cmdlet allows you to specify a particular module and culture when updating help. By default, the cmdlet will use the current culture. In this example, it would download and install the help for the Microsoft.PowerShell.Core module for the German culture, as follows:

PS C:\> Update-Help —Module Microsoft.PowerShell.Core UICulture de-DE

The cmdlet offers a Recurse parameter that will search the SourcePath directory, recursively, for HelpInfo XML and CAB files using the following commands:

PS C:\> Update-Help —SourcePath \\fileServer01\HelpFiles -Recurse

In addition to accepting strings for module names through the Module parameter, the cmdlet Update-Help and cmdlet Save-Help will accept PSModuleInfo objects through the InputObject parameter as well. This parameter accepts pipeline input. The Get-Module cmdlet returns PSModuleInfo objects. This allows you to use the two modules in unison and create a pipeline between the two. For example, you could get all the modules that are available and update them. This is shown in the following command:

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

In the same way, with Save-Help, you could save the help for all modules in a particular directory, as follows:

PS C:\> Get-Module —ListAvailable | Save-Help —DestinationPath C:\MyHelpDirectory

The Get-Help cmdlet has been updated with a simple usability feature. Microsoft added a progress indicator that is now present when searching for help on a particular cmdlet. Because the number of cmdlets and modules is growing exponentially, and the cmdlet discovery is expanding beyond the session (as you'll soon see), this subtle but necessary feature has been added, as shown in the following screenshot:

The auto-discovery cmdlet removes the need to load a module explicitly before calling cmdlets that it includes. For example, rather than performing the previous imports you could simply call it Get-Website as follows:

PS C:\>Get-Website

Right before execution of the Get-Website cmdlet, PowerShell imported the module for us. This is not the only circumstance where a cmdlet module will be automatically loaded. There are actually two other actions that will implicitly load a module. The first action is when attempting to load the help for a cmdlet using Get-Help as follows:

PS C:\> Get-Help Get-Website

Again this will load the module right before getting the help for the cmdlet. This is necessary because the module contains the help information, thus Get-Help requires that the module be loaded before reading the help. The last circumstance where a module will be implicitly loaded is when you use the Get-Command cmdlet to retrieve a CmdletInfo object using following command:

PS C:\> Get-Command Get-Website

Using a Get-Command call with a wildcard character will not load the module into the current session. The about_Modules help topic explains why. The following sentence supports this, which can be found at

http://msdn.microsoft.com/en-us/library/windows/desktop/hh847804.aspx.

Get-Command commands that include a wildcard character (*) are considered to be discovery, not use, and do not import any modules.

It is possible to modify how modules are auto-loaded in your PowerShell session. You can adjust the value of the PSModuleAutoLoadingPreference variable. The default value for this variable is All. All signifies that during any of the these actions the module containing the target cmdlet will be auto-loaded. The other two values are ModuleQualified and None. ModuleQualified loads modules only when a command is prefixed by the module name, as follows:

PS C:\> Get-Command "MyModule\MyCommand"

In any other circumstance the module will not be loaded. Setting PSModuleAutoLoadingPreference to None will turn off module auto-loading.

There is one other change that affects when modules are imported. In PowerShell 2.0, modules that relied on other modules, could specify the RequiredModules property and list the other modules that were required by the module. If the other modules were not already imported when the target module was being imported, an error would be shown and the module would not be imported successfully. This has changed in PowerShell 3.0. Instead of the primary module load failing immediately if the other modules are not loaded, an attempt to load all the dependent modules will be made before loading the target module.

This effectively alleviates the two pain points seen in the previous versions of PowerShell. The cmdlets can be used without having to load their modules. This reduces script dependencies and saves a bit of typing. In addition, it enables administrators to search for cmdlets and the help of cmdlets without having to know the details of where they are stored.

The cmdlet auto-discovery is a great new feature but has a few caveats that need to be understood when working with the new version of PowerShell. The first thing to note is that the help system searches the module directories in a specific order. The local user's module directory is the first to be searched, followed by the system module directory. This is very important to understand because PowerShell allows for functions to be overwritten. This means that it is possible to have two separate modules that contain those cmdlets. For example, if you have two virtual machine management modules, say HyperVModule and VirtualBoxModule, and they both have Get-VM cmdlet.

Here is an example of one of the module manifests:

#HyperVModule.psd1 – Module Manifest 

@{
ModuleVersion = '1.0'
GUID = '256c636c-7e77-493c-971e-fe16cfe0601c'
Author = 'Adam Driscoll'
CompanyName = 'Get-VM'
Copyright = '2011 Adam Driscoll'
Description = 'Test Hyper-V Module'
PowerShellVersion = '3.0'
#Some fields removed …
NestedModules = @('HyperVModule.ps1')
CmdletsToExport = 'Get-VM'
}

As you can see the module will export the cmdlet Get-VM. The CmdletsToExport property is what the system is evaluating to determine where cmdlets are stored during auto-discovery. Here is an example of one of the source files:

function Get-VM
{
    Write-Host "HyperVModule:Get-VM"
}

As you can see, we are a defining a function, Get-VM, which simply prints out the name of the module and the name of the cmdlet. In the case of the VirtualBoxModule, we have defined a very similar structure, except it will print out VirtualBoxModule:Get-VM rather than the string presented in the previous script snippet.

Imagine that the HyperVModule is stored in the local user module directory while VirtualBoxModule is stored in the system module directory. Typing Get-VM in the shell will then load the HyperVModule and execute that cmdlet.

Executing the Get-VM on the command line would now result in the following:

PS C:\> Get-VM
HyperVModule:Get-VM

To execute the other version of the cmdlet you will need to first load the VirtualBoxModule explicitly, and then execute the cmdlet as follows:

PS C:\> Import-Module VirtualBoxModule
PS C:\> Get-VM
VirtualBoxModule:Get-VM

The cmdlet auto-discovery is great when attempting to locate a particular cmdlet, but as seen previously it behaves differently when there are multiple cmdlets with one name.

Although this is an issue there are several ways to work around it. Even when both the cmdlets are loaded, it is still possible to fully qualify the name of the cmdlet we would like to execute. For example, if we wanted to execute the Get-VM cmdlet of VirtualBoxModule, we could do the following:

PS C:\> VirtualBoxModule\Get-VM
VirtualBoxModule:Get-VM

In addition to using the default fully qualified name, we could use the Prefix parameter of the Import-Module cmdlet as well. This allows us to change the prefix for the cmdlet. For example, we could define a new prefix for the VirtualBoxModule as follows:

PS C:\> Import-Module VirtualBoxModule -Prefix VBM
PS C:\> VBM\Get-VM
VirtualBoxModule:Get-VM

Another problem associated with this circumstance is attempting to find these cmdlets. Get-Command is not set up to find cmdlets beyond the first one it finds when there are no wildcards associated with the name. Once it locates the cmdlet it is looking for, it will simply stop looking and return that cmdlet. So executing the following will only return the HyperVModule version of Get-VM because it looks in the user module directory before looking in the system module directory:

PS C:\ Get-Command Get-VM
CommandType     Name                         ModuleName
-----------     ----                         ----------
Function        Get-VM                       HyperVModule

PS C:\ Users\Adam> Get-Module

ModuleType Name                      ExportedCommands
---------- ----                      ----------------
Manifest   HyperVModule              Get-VM
…

Notice that it has loaded the module after calling Get-Command. Although in most circumstances the Get-Command works in our favor, this time we were attempting to search for all the Get-VM cmdlets available to us. As you can see, the HyperVModule is now loaded into our session. In order to find the other cmdlet we need to get a bit more complex in the way we search the system. The following command will retrieve all the available modules and filter through each one of their exported commands, returning only modules that contain a Get-VM cmdlet:

PS C:\ > Get-Module -ListAvailable | Where-Object { $_.ExportedCommands.ContainsKey('Get-VM') }
Directory: C:\Users\Adam\Documents\WindowsPowerShell\Modules
ModuleType Name                      ExportedCommands
---------- ----                      ----------------
Manifest   HyperVModule              Get-VM

    Directory: C:\Windows\system32\WindowsPowerShell\v1.0\Modules

ModuleType Name                      ExportedCommands
---------- ----                      ----------------
Manifest   VirtualBoxModule          Get-VM

The reason the previous cmdlet works is that it does not actually force either of the modules to load into the session via cmdlet auto-discovery. Instead, internally it reads the manifest files and searches for cmdlet within those manifests and returns the corresponding modules. Instead of using such a complicated command it is possible to once again use the Get-Command cmdlet. Albeit, this example may not work in every circumstance, it will work for the previous example as follows:

PS C:\> Gt- Command Get-VM*
CommandType     Name        ModuleName
-----------     ----        ----------
Function        Get-VM      HyperVModule
Function        Get-VM      VirtualBoxModule

Because we used a wildcard in the call to Get-Command, the system did not use the auto-discovery cmdlet as explained earlier. The problem with this method is that it may find cmdlets simply starting with Get-VM in addition to the cmdlets we are actually searching for.

Another issue associated with cmdlet auto-discovery is that it can mask issues associated with the modules it is attempting to auto-load. If, for instance, I had incorrectly typed the NestedModule property in the HyperVModule manifest, I would receive an error while attempting to load the module with Import-Module, shown as follows:

#Notice I'm missing a close single quote
CompanyName = 'Get-VM

This is what happens when I attempt to load the module explicitly with the Import-Module cmdlet as follows:

PS C:\Users\Adam> Import-Module HyperVModule
Import-Module : The module manifest 'C:\Users\Adam\Documents\WindowsPowerShell\Modules\HyperVModule\HyperVModule.psd1'
could not be processed because it is not a valid PowerShell restricted language file. Please remove the elements that are not permitted by the restricted language

If I were now to attempt to call the Get-VM cmdlet, I would receive an error. Rather than continuing on to the next module that contains Get-VM, the VirtualBoxModule, PowerShell stops processing because of an error in the HyperVModule as follows:

PS C:\ > Get-VM
The term 'Get-VM' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

This is important to note for both duplicate cmdlet scenarios and for module development, as the issue will not be obvious. The cmdlet auto-discovery is a very helpful feature but understanding the few caveats associated with it are a fundamental part of using it.