PowerShell CheatSheet – Get-Help

How to add an help section/function to your own powershell scripts. Here we are: you can add comment based help either to a script or to a function.
The addition of script help blocks that are compatible with the PowerShell “Comment Based Help” allow the user to run the command ‘Get-Help .\scriptname.ps1’ and display the help for the script.
Basically, this is a form of writing a comment block that works in conjunction with the Get-Help cmdlet that is included with PowerShell.

PS C:\> Get-help .\scriptname.ps1

NAME
    C:\scriptname.ps1

SYNOPSIS
    ScriptName - Script Purpose

SYNTAX
    C:\scriptname.ps1 [-Parameter1] <Object> [[-Parameter2] <Object>] [[-Parameter3] <Object>]
    [[-Parameter4] <Object>] [[-Parameter5] <Object>] [[-Parameter6] <Object>] [<CommonParameters>]

DESCRIPTION
    ScriptName - Script Purpose
    Script Description

RELATED LINKS
    Script related links
    Author link

REMARKS
    To see the examples, type: "get-help C:\scriptname.ps1 -examples".
    For more information, type: "get-help C:\scriptname.ps1 -detailed".
    For technical information, type: "get-help C:\scriptname.ps1 -full".

The best practice to follow is to ALWAYS start a script with the following lines (and adapt them for your script of course!):

<#
    .SYNOPSIS
        A brief description of the function or script. This keyword can be used
        only once in each topic.

    .DESCRIPTION
        A detailed description of the function or script. This keyword can be
        used only once in each topic.

    .PARAMETER  <Parameter-Name>
        The description of a parameter. You can include a Parameter keyword for
        each parameter in the function or script syntax.

        The Parameter keywords can appear in any order in the comment block, but
        the function or script syntax determines the order in which the parameters
        (and their descriptions) appear in Help topic. To change the order,
        change the syntax.
 
        You can also specify a parameter description by placing a comment in the
        function or script syntax immediately before the parameter variable name.
        If you use both a syntax comment and a Parameter keyword, the description
        associated with the Parameter keyword is used, and the syntax comment is
        ignored.

    .EXAMPLE
        A sample command that uses the function or script, optionally followed
        by sample output and a description. Repeat this keyword for each example.

    .INPUTS
        The Microsoft .NET Framework types of objects that can be piped to the
        function or script. You can also include a description of the input 
        objects.

    .OUTPUTS
        The .NET Framework type of the objects that the cmdlet returns. You can
        also include a description of the returned objects.

    .NOTES
        Additional information about the function or script.

    .LINK
        The name of a related topic. Repeat this keyword for each related topic.

        This content appears in the Related Links section of the Help topic.

        The Link keyword content can also include a Uniform Resource Identifier
        (URI) to an online version of the same Help topic. The online version 
        opens when you use the Online parameter of Get-Help. The URI must begin
        with "http" or "https".

    .COMPONENT
        The technology or feature that the function or script uses, or to which
        it is related. This content appears when the Get-Help command includes
        the Component parameter of Get-Help.

    .ROLE
        The user role for the Help topic. This content appears when the Get-Help
        command includes the Role parameter of Get-Help.

    .FUNCTIONALITY
        The intended use of the function. This content appears when the Get-Help
        command includes the Functionality parameter of Get-Help.

    .FORWARDHELPTARGETNAME <Command-Name>
        Redirects to the Help topic for the specified command. You can redirect
        users to any Help topic, including Help topics for a function, script,
        cmdlet, or provider. 

    .FORWARDHELPCATEGORY  <Category>
        Specifies the Help category of the item in ForwardHelpTargetName.
        Valid values are Alias, Cmdlet, HelpFile, Function, Provider, General,
        FAQ, Glossary, ScriptCommand, ExternalScript, Filter, or All. Use this
        keyword to avoid conflicts when there are commands with the same name.

    .REMOTEHELPRUNSPACE <PSSession-variable>
        Specifies a session that contains the Help topic. Enter a variable that
        contains a PSSession. This keyword is used by the Export-PSSession
        cmdlet to find the Help topics for the exported commands.

    .EXTERNALHELP  <XML Help File Path>
        Specifies the path to an XML-based Help file for the script or function.  

        In Windows Vista and later versions of Windows, if the specified path
        to the XML file contains UI-culture-specific subdirectories, Get-Help
        searches the subdirectories recursively for an XML file with the name
        of the script or function in accordance with the language fallback
        standards established for Windows Vista, just as it does for all
        XML-based Help topics. 

        For more information about the cmdlet Help XML-based Help file format,
        see "How to Create Cmdlet Help" in the MSDN (Microsoft Developer Network) 
        library at http://go.microsoft.com/fwlink/?LinkID=123415.
#>

The minimum is to use .SYNOPSIS, .DESCRIPTION, .PARAMETER (if there is) and .EXAMPLE

Leave a Reply

Scroll to Top