How to enable Updatable Help for your PowerShell Module

How to enable Updatable Help for your PowerShell Module

Rate This
  • Comments 1

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

Leave a Comment
  • Please add 5 and 1 and type the answer here:
  • Post
  • Really cool post.  I have been using the Advanced Function Snippet in the POSH ISE to document help, which does an OK job.  Is there an easy tool to help create the psm1-Help.xml file?  I have over 60 cmdlets/functions, and doing this by hand would be extremely painful!

Page 1 of 1 (1 items)