Adding help for cmdlets in a MshSnapIn

Adding help for cmdlets in a MshSnapIn

Rate This
  • Comments 7

Now that you know how to create an MshSnapIn, you might want to add help content for all those cmdlets that you developed and get them displayed by “get-help” cmdlet.  To add help content you must know how a Monad Cmdlet Help file looks. See any of the *-Help.xml files in Monad installation directory for reference. I wont be describing the format of the help file in this blog (I will do that on some other day. In the mean time please use one of the *-Help.xml files for your reference).

When "add-mshsnapin XYZ.TestNameSpace.MyMshSnapIn" is run on the command-line, Monad engine will look for snapin information under registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSH\1\MshSnapIns\{Your_MshSnapIn_Key here}. This key will have information like ApplicationBase, AssemblyName, etc. The monad engine loads the assembly (and if everything succeeds), identifies all the cmdlets/providers that are defined in MshSnapIn assembly. Along with all the necessary information that is required, the engine will add a default help file name which is of format <MshSnapIn assembly name>.dll-Help.xml for every cmdlet/provider that is present in the MshSnapIn assembly.

Later when help engine tries to load help file for a cmdlet, the help engine looks for the help file relative to MshSnapIn “ApplicationBase” directory. Remember this ApplicationBase is added to the registry during MshSnapIn installation phase.

You can control the name of the help file ( infact you can have a separate helpfile for each of your cmdlets/providers ) by creating a Custom MshSnapIn

So here are the steps to add help content to your MshSnapIns:

Create a help file and name it as appropriate

(a) If your snapin is a general MshSnapIn (ie., deriving from System.Management.Automation.MshSnapIn) name it <your dll name>.dll-Help.xml

(b) If your snapin is a custom MshSnapIn (ie., deriving from System.Management.Automation.CustomMshSnapIn) name it according to the information you supplied with “public override Collection<CmdletConfigurationEntry> Cmdlets” property.

When your snapin is deployed make sure the help files are deployed to the same location relative to ApplicationBase.

If you follow the above steps, then “get-help <Your custom MshSnapIn cmdlet>” should display help for your cmdlets.

Hope this helps.

---

Krishna Vutukuri [MSFT]

Monad Development
Microsoft Corporation
This posting is provided "AS IS" with no warranties, and confers no rights.

 

[Edit: Monad has now been renamed to Windows PowerShell. This script or discussion may require slight adjustments before it applies directly to newer builds.]

Leave a Comment
  • Please add 6 and 6 and type the answer here:
  • Post
  • Hi,

    Could you please explain me more about writing more about writing help for cmdlet? Can we develop the content in a text pad for each cmdlet and finally develop a help.xml that can
    call all this text files? Will that work?
  • Hi Triguna;

    The help files are straight XML, so you can develop them in any editor you like.  

    For example, look at the file in your PowerShell installation directory, Microsoft.PowerShell.Commands.Management.dll-Help.xml.
  • > Could you please explain me more about writing more about writing help for cmdlet?

    Your wish is our command:

    http://blogs.msdn.com/powershell/archive/2006/09/14/Draft_Creating_Cmdlet_Help.aspx

    Jeffrey Snover [MSFT]
    Windows PowerShell/Aspen Architect
    Visit the Windows PowerShell Team blog at:    http://blogs.msdn.com/PowerShell
    Visit the Windows PowerShell ScriptCenter at:  http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx
  • Hi Guys,

    Thank You very much for publishing the essential information to create a cmdlet help.

    It is very useful.

    Thanks,

    Triguna Rao.

  • I'm getting an error when trying to load the help for my cmdlet. The info provided by the error does not really help me find the problem. How can I determine what the problem is?

    The error I'm getting is as follows:

    Get-Help: Error loading help content for <cmdlet> from file <help_file>. Details: <help_file>

    At line:1 char:9

    I copied the existing help for one of the PowerShell commands and modified it. My first line is just <?xml version="1.0" encoding="utf-8" ?>.

    Thanks,

    Peter.

  • Hi Peter, Where did you place the help file. Did you place the help file in your PSSnapin's Application base?

    -Krishna[MSFT]

    This posting is provided "as is" with no warranties.

  • Hi,

    If I install my snap-in into GAC, how can I tell powershell the location of my help file?

    thanks!

Page 1 of 1 (7 items)