Export (0) Print
Expand All

Writing Help for Windows PowerShell Modules

Windows PowerShell modules can include Help topics about the module and about the module members, such as cmdlets, providers, functions and scripts. The Get-Help cmdlet displays the module Help topics in the same format as it displays Help for other Windows PowerShell items, and users use standard Get-Help commands to get the Help topics.

This document explains the format and correct placement of module Help topics, and it suggests guidelines for module Help content.

Types of Module Help

A module can include the following types of Help.

  • Cmdlet Help. The Help topics that describe cmdlets in a module are XML files that use the command help schema. For more information about writing cmdlet Help, see Writing Help for Windows PowerShell Cmdlets.

  • Provider Help. The Help topics that describe providers in a module are XML files that use the provider help schema. For information about writing provider Help files, see Writing Help for Windows PowerShell Providers.

  • Function Help. The Help topics that describe functions in a module can be XML files that use the command help schema or comment-based Help topics within the function, or the script or script module. For more information about comment-based Help, see about_Comment_Based_Help.

  • Script Help. The Help topics that describe scripts in a module can be XML files that use the command help schema or comment-based Help topics in the script or script module. For more information about comment-based Help, see about_Comment_Based_Help

  • Conceptual ("About") Help. You can use a conceptual ("about") Help topic to describe the module and its members and to explain how the members can be used together to perform tasks. Conceptual Help topics are text files with Unicode (UTF-8) encoding. The file name must use the about_<name>.help.txt format, such as about_MyModule.help.txt.

Placement of Module Help

The Get-Help cmdlet looks for module Help topic files in language-specific subdirectories of the module directory.

For example, the following directory structure diagram shows the location of the Help topics for the SampleModule module.

<ModulePath>
         \SampleModule
               \<en-US>
                     \about_SampleModule.help.txt
                     \SampleModule.dll-help.xml
                     \SampleNestedModule.dll-help.xml
               \<fr-FR>
                     \about_SampleModule.help.txt
                     \SampleModule.dll-help.xml
                     \SampleNestedModule.dll-help.xml

noteNote:
In the example, the <ModulePath> placeholder represents one of the paths in the PSModulePath environment variable, such as $home\Documents\Modules, $pshome\Modules, or a custom path that the user specifies.

Getting Module Help

When a user imports a module into a session, the Help topics for that module are imported into the session along with the module. You can list the Help topic files in the value of the FileList key in the module manifest, but Help topics are not affected by the Export-ModuleMember cmdlet.

You can provide module Help topics in different languages. The Get-Help cmdlet automatically displays module Help topics in the language that is specified for the current user in the Regional and Language Options item in Control Panel. In Windows Vista and later versions of Windows, Get-Help searches for the Help topics in language-specific subdirectories of the module directory in accordance with the language fallback standards established for Windows.

Beginning in Windows PowerShell 3.0, running a Get-Help command for a cmdlet or function triggers automatic importing of the module. The Get-Help cmdlet immediately displays the contents of the help topics in the module.

If the module does not contain help topics and there are no help topics for the commands in the module on the user’s computer, Get-Help displays auto-generated help. The auto-generated help includes the command syntax, parameters, and input and output types, but does not include any descriptions. The auto-generated help includes text that directs the user to try to use the Update-Help cmdlet to download help for the command from the Internet or a file share. It also recommends using the Online parameter of the Get-Help cmdlet to get the online version of the help topic.

Supporting Updatable Help

Users of Windows PowerShell 3.0 and later versions of Windows PowerShell can download and install updated help files for a module from the Internet or from a local file share. The Update-Help and Save-Help cmdlets hide the management details from the user. Users run the Update-Help cmdlet and then use the Get-Help cmdlet to read the newest help files for the module at the Windows PowerShell command prompt. Users do not need to restart Windows or Windows PowerShell.

Users behind firewalls and those without Internet access can use Updatable Help, as well. Administrators with Internet access use the Save-Help cmdlet to download and install the newest help files to a file share. Then, users use the Path parameter of the Update-Help cmdlet to get the newest help files from the file share.

Module authors can include help files in the module and use Updatable Help to update the help files, or omit help files from the module and use Updatable Help both to install and to update them.

For more information about Updatable Help, see Supporting Updatable Help.

Supporting Online Help

Users who cannot or do not install updated help files on their computers often rely on the online version of module help topics. The Online parameter of the Get-Help cmdlet opens the online version of a cmdlet or advanced function help topic for the user in their default Internet browser.

The Get-Help cmdlet uses the value of the HelpUri property of the cmdlet or function to find the online version of the help topic.

Beginning in Windows PowerShell 3.0, you can help users find the online version of cmdlet and function help topics by defining the HelpUri attribute on the cmdlet class or the HelpUri property of the CmdletBinding attribute. The value of the attribute is the value of the HelpUri property of the cmdlet or function.

For more information, see Supporting Online Help.

See Also



Show:
© 2014 Microsoft