• Scripting
• Windows PowerShell
• Help
• Updatable Help
• Online Help

Although the names are similar and often confused, the HelpUri and HelpInfoUri properties are very different. If you confuse them, the help for your PowerShell commands and modules won't work.

I've spent some time exploring the modules in PowerShell Gallery. While some are excellent (and I'll be blogging about those in the coming days), many have serious bugs that could have been discovered by running very simple tests.

Really simple tests. Not even Pester tests.

Just running Import-Module (tests the .psd1), Get-Command (Are all of my parameters, aliases, and functions exported?), and Get-Help (Does the help work?) on a machine other than the one on which the module was developed would help.

One of the most common, and most easily fixed, help bugs was confusing the HelpUri property of commands with the HelpInfoUri property of modules, so let's clear that up.

HelpUri: Online Help for a Command

The HelpUri property enables online help (Get-Help -Online) for a command. The property value is the URL (http or https) of the online help topic for a cmdlet, function, CIM command, or workflow. When a user runs Get-Help -Online, Get-Help opens the default browser to the HelpUri property value.

Well, almost. Actually, it's a bit more complicated. (For all of the details, see Supporting Online Help.)

Get-Help -Online gets the HelpUri URL value from two sources. If both are present, the value in the help file takes precedence.

• The URL of the first related link in the help file.

   

  PS C:\ > (Get-Help Get-Random).RelatedLinks
  Online Version: http://go.microsoft.com/fwlink/p/?linkid=293974

• The value of the HelpUri parameter of the Cmdlet class (or the HelpUri parameter of the CmdletBinding attribute of a function.

  

   

  PS C:\> (Get-Command Get-Random).HelpUri
  http://go.microsoft.com/fwlink/?LinkID=113446

 In this case, where both are present, Get-Help uses the value in the help file. You can test it. The cmdlet HelpUri value points to the PowerShell 5.0 doc. The help file HelpUri value points to the PowerShell 4.0 doc.

But, the important point is that the value of HelpUri is the URL of a web page, such as https://technet.microsoft.com/en-us/library/hh849905.aspx, or a page in a GitHub wiki, such as https://github.com/pester/Pester/wiki/Assert-VerifiableMocks, or a MarkDown file, such as https://github.com/PowerShell/PSScriptAnalyzer/blob/development/RuleDocumentation/AvoidTrapStatement.md.

Now, let's look at HelpInfoUri.

HelpInfoUri: Updatable Help for a Module

The HelpInfoUri property of modules enables updatable help for a module. HelpInfoUri is a module manifest key. Its value is the URL of the online directory that contains the HelpInfo XML file that configures updatable help for the module.

The updatable help CAB files can be stored in the same URL location (or any online location specified by the HelpContentUri element in the HelpInfo XML file), but the HelpInfoUri URL always points to the HelpInfo XML file parent directory. Unlike the HelpInfo property value, you can't browse to the HelpInfoUri location, because it links to a container, not a web page.

Also, the HelpInfoUri value must begin with http; https is not permitted.

To specify the HelpInfoUri value, set the HelpInfoUri key of the module manifest to a valid http or https value. For example, here's the Microsoft.PowerShell.Utility.psd1 file.

PS C:\> Import-PowerShellDataFile -Path (Get-Module Microsoft.PowerShell.Utility).Path

Name                           Value
----                           -----
Copyright                     © Microsoft Corporation. All rights reserved.
NestedModules                 {Microsoft.PowerShell.Commands.Utility.dll, Microsoft.PowerShell.Utility.psm1}
PowerShellVersion             3.0
CompanyName                   Microsoft Corporation
GUID                           1DA87E53-152B-403E-98DC-74D7B4D63D59
Author                         Microsoft Corporation
CLRVersion                     4.0
CmdletsToExport               {Format-List, Format-Custom, Format-Table, Format-Wide...}
HelpInfoURI                   http://go.microsoft.com/fwlink/?linkid=390787
ModuleVersion                 3.1.0.0

For more information about the HelpInfoUri key and its HelpInfo XML URL value, see Supporting Updatable Help.

They're Not the Same

HelpUri and HelpInfoUri are not the same and they're not interchangeable. However, several PowerShell Gallery modules have HelpInfoUri (updatable help) values that end in .htm or .md or resolve to a web page. These modules provide a false positive when detecting online help and updatable help. Also, when misused or reversed, Get-Help -Online, Update-Help, and Save-Help fail.

If you've confused them, be sure to update your commands or modules.

In PowerShell Gallery, we should test for an reject modules with these errors.

PSScriptAnalyzer, which runs a static analysis, can detect bad file name extensions, but this task is best left to a simple Pester test that can be run before the module is accepted into the PowerShell Gallery.

 
$Module = Get-Module -ListAvailable @{ModuleName = $ModuleName; RequiredVersion = $Version; GUID = $GUID }
if ( $Module.HelpInfoUri ) {
    Describe "Testing HelpInfoUri value" {
        { Invoke-WebRequest -Path $Module.HelpInfoUri } | Should Throw
    } 
}
foreach ($command in (Get-Command -Module $Module))
{
    if ($command.HelpUri) {   
Describe "Testing HelpUri value" {
        { Invoke-WebRequest -Path $command.HelpUri } | Should Not Throw
    }
}

It's a bit confusing, but I hope this helps!

June Blender is a technology evangelist at SAPIEN Technologies, Inc. and a Windows PowerShell MVP. You can reach her at This email address is being protected from spambots. You need JavaScript enabled to view it. or follow her on Twitter at @juneb_get_help.

• Prev
• Next