February 4th, 2014

How to enable Updatable Help for your PowerShell Module

PowerShell Team
PowerShell Team

PowerShell 3.0 lets the user update Help content on a per module basis. In this article, I will explain how you can enable this for your own PowerShell module.

Prerequisites: Have a new (script/binary) module, help content for the cmdlets of the module, and a server where the help content is located. For this particular exercise I will be using a script module.

Here is how my module is organized:

C:\Users\frangom\Documents\WindowsPowerShell\modules\TestModule\TestModule.psm1

C:\Users\frangom\Documents\WindowsPowerShell\modules\TestModule\TestModule.psd1

TestModule.psm1 is my script module. There, I defined the name of help file.

TestModule.psd1 is the module manifest for my module. The HelpInfoURI field is the address where the help content for this module is located.

On the server site, we have:

  • The .cab file which contains the dll-Help.xml or the psm1-Help.xml file
  • The HelpInfo.xml file.

The .cab file must be named as follows:

ModuleName_ModuleGUID _UI-Culture_HelpContent.cab

where:

ModuleName: The name of the module (same as the module manifest file).

ModuleGUID: The module GUID as referenced in the module manifest.

UI-Culture: The four letter hyphenated UI culture abbreviation (en-US, fr-FR, de-DE, etc.).

HelpContent: Indicates that this cab contains the help content file.

For example:

TestModule_d03c1cf3-f738-48a3-b845-5ead46a52671_en-US_HelpContent.cab

Similarly, the HelpInfo file must adhere to the following naming convention:

ModuleName_ModuleGUID_HelpInfo.xml

where:

ModuleName: Name of the module (same as the module manifest file).

ModuleGUID: Module GUID as referenced in the module manifest.

HelpInfo: Indicates that this is the help info file.

For example:

TestModule_d03c1cf3-f738-48a3-b845-5ead46a52671_HelpInfo.xml

File content of the HelpInfo.xml file:

<?xml version="1.0" encoding="utf-8"?>

<HelpInfo xmlns="http://schemas.microsoft.com/powershell/help/2010/05">

  <HelpContentURI>http://www.mysite.com/PSHelpContent/</HelpContentURI>

  <SupportedUICultures>

     <UICulture>

       <UICultureName>en-US</UICultureName>

       <UICultureVersion>3.2.15.0</UICultureVersion>

     </UICulture>    

  </SupportedUICultures>

</HelpInfo>

Note: The HelpContentURI (in yellow) should point to a container.

Place these two files in the server folder PSHelpContent, e.g., \\mysite\c$\Inetpub\wwwroot\PSHelpContent\

How to Test Updatable Help for Your Module

# First, make sure updatable help works using the -SourcePath

Update-Help -Module TestModule -SourcePath \\mysite\c$\Inetpub\wwwroot\PSHelpContent\ -Force

 

# After that, you can use without the -SourcePath which will connect to the site defined in 

# the module manifest, HelpInfoURI = ‘http://www.mysite.com/PSHelpContent/’

Update-Help -Module TestModule -Force

For more information on Supporting Updatable Help, please visit http://go.microsoft.com/fwlink/?LinkId=391422.

Cheers,

Francisco Gamino

PowerShell Test Team

Author

PowerShell Team
PowerShell Team

PowerShell is a task-based command-line shell and scripting language built on .NET. PowerShell helps system administrators and power-users rapidly automate tasks that manage operating systems (Linux, macOS, and Windows) and processes.

0 comments

Discussion are closed.