I have been creating several PowerShell cmdlets over the last few days. The cmdlets are all compiled into an assembly for deployment purposes. One of the requirements has been to provide external help files that can be modified. Here are some quick lessons learned about the help files.

  1. Naming of the help file is important – It needs to follow this convention.  <AssemblyName>.dll-Help.xml
    I had to dig deep in the documentation to find this out.  Don’t forget to put -Help in the name.
  2. XML follows MAML schema.  MSDN provides some help as to all the parts on the schema, however, the best way is to pull a sample xml help file from the PowerShell directory on your local system and modify accordingly.  I used this file for understanding (Microsoft.PowerShell.Commands.Management.dll-Help).
  3. Understand where the file needs to be located to be found by PowerShell.  By default it is the following powershell directories ($home\Documents\Modules, $pshome\Modules). 

An exciting thing I learned, is that the help files support the standard localization patterns as the .net framework.

Here are some references to help you on your way.

http://msdn.microsoft.com/en-us/library/dd878343(VS.85).aspx (Writing PowerShell Modules)

  http://blogs.msdn.com/b/powershell/archive/2006/09/14/draft-creating-cmdlet-help.aspx

Advertisements