Function Help Cannot Share a Cmdlet Help File

PowerShell Team

In Windows PowerShell 2.0, you can write help topics for functions, scripts, and modules, just as you do for cmdlets and providers. In fact, as a best practice, you should always include help topics for all shared PowerShell items.

 And we make it easy. For functions and scripts, you can write comment-based help topics right in the script or function (see about_Comment_Based_Help) or you can write XML-based help topics that use the same schema as cmdlet help topics. .To do so, just add the .ExternalHelp comment keyword to the function or script followed by the path and name of the XML file that contains the help topic.

However, the XML-based help topics for functions and scripts must be in their own XML file. You can put XML-based topics for functions and scripts in the same file. But you cannot put the XML-based help topics for functions and scripts in the same file with XML-based help topics for cmdlets and providers. If you combine the topic types, Get-Help will find only the function/script help topics or only the cmdlet help topics, but not both. This limitation might be fixed in the future, but combined-type XML files do not work property in Windows PowerShell 2.0.

Unfortunately <blush/>, we included an example of this error in Windows PowerShell 2.0. Try this:

·        Start a new Windows PowerShell session. (Type: powershell).

·        Type: get-help Disable-PSRemoting -full

·        Read it. Great info. Really.

·        Now, type get-help Enable-PSRemoting -full

·        Hmmm. Not much.

It works in reverse, too.

·        Start a new Windows PowerShell session. (Type: powershell).

·        Type: get-help Enable-PSRemoting -full

·        Read it. Great info. Really.

·        Now, type get-help Disable-PSRemoting -full

·        Hmmm. Not much.

The problem is that the help topic for the Disable-PSRemoting function (yes, it’s a function) is in the System.Management.Automation.dll-Help.xml file, along with the help topics for all of the cmdlets in the System.Management.Automation.dll file, including Enable-PSRemoting.. So, if your first Get-Help call in the session is for a function or script in that file, you can get help only for functions and scripts in the file. If your first Get-Help call in the session is for a cmdlet, you get only cmdlet help in that file.

We’re working on ways to fix and prevent this, but you can be smarter and avoid it in the first place. I’ll be updating the about_Comment-Based_Help file online and our SDK topics creating help files. In the meantime, be sure to create separate XML files for your help topics.

June Blender [MSFT], Windows PowerShell Documentation

Guangfa Lu [MSFT], Windows PowerShell Test

Get Windows PowerShell Help Online:  http://go.microsoft.com/fwlink/?LinkID=107116 

PowerShell Team PowerShell Team, PowerShell

Follow