How to write comment based Help in PowerShell?

PowerShellMicrosoft TechnologiesSoftware & Coding

In PowerShell when you create a complex script or function then it should be essential to create help for the end-users to easily understand your script functionality. Writing comment-based help or XML-based help, at the end is similar to Get-Help syntax for cmdlets or function which is the online version of help.

For Example, Just open the PowerShell console and run the command below.

Get-Help Get-WmiObject

And you can see the various help sections in the output like NAME, SYNOPSIS, SYNTAX, DESCRIPTION, PARAMETER, LINK. These are called Keywords. We can include all of them in the script of function manually to get the help. Whenever we use the help keyword, you need to use the dot (.) keyword before it.

When we write comment-based help, it should be inside the multiline comment box <# .. #>. You can also use single line comment # but for users who can easily read and understand it is recommended to put them inside the multiline comment box.

It is not necessary to use the syntax in capital letters but again for user's readability and to distinguish the keywords, we put them into CAPS letters.

Below is the structure of the command based help.

<#
   .HELP Keyword
      HELP content
#>

Let’s understand some necessary keywords one by one.

  • .SYNOPSIS − Brief description of the function or the script. This keyword can be used only once in the help section.

  • .DESCRIPTION − Detailed description of the function or the script. This keyword can be used only once in the help section.

  • .PARAMETER − It is for the brief description of the parameter. You need to write a new parameter keyword for each parameter. First, you need to write the parameter keyword and space the name of the parameter and in the next line, the content of the parameter.

  • .Example − A sample command describing the function or the script. You can also include the sample output. Multiple examples can be added with each new Example keyword.

  • .Notes − Additional information about the function or the script.

  • .Inputs − Description of the input object.

  • .Outputs − Description of the output object.

The above keywords included are the common keywords which help users to get enough idea about the function or script related help. There are also many other keywords you can include. To get more information about the keywords, use the help section for the about_comment-based_help.

get-help about_comment-based_help

Example

function Get-ColoredService{
   <#
      .SYNOPSIS
         Gets the colored output of the Services based on Status

      .DESCRIPTION
         Get-ColoredService will provide the colorful output based on the status of the service.
         If the Service is in Stopped status - Output will be Red
         If the service is in Running status - Output will be in Green

      .
   #>

}

When you check the help of the above function you will get the below output.

PS C:\WINDOWS\system32> Get-Help Get-ColoredService
NAME
   Get-ColoredService

SYNOPSIS
   Gets the colored output of the Services based on Status

SYNTAX
   Get-ColoredService []

DESCRIPTION
   Get-ColoredService will provide the colorful output based on the status of the service.
   If the Service is in Stopped status - Output will be Red
   If the service is in Running status - Output will be in Green

.
RELATED LINKS
REMARKS
   To see the examples, type: "get-help Get-ColoredService -examples".
   For more information, type: "get-help Get-ColoredService -detailed".
   For technical information, type: "get-help Get-ColoredService -full".

You can see the few help keywords (Name, Syntax, Description, Related Links, Remarks) are the default.

We will now create help with other keywords like parameter, inputs, outputs, example etc. Whatever you declare as a parameter in param block, the syntax will be shown for it as described in the below example.

function Get-ColoredService{
   <#
      .SYNOPSIS
         Gets the colored output of the Services based on Status

      .DESCRIPTION
         Get-ColoredService will provide the colorful output based on the status of the service.
         If the Service is in Stopped status - Output will be Red
         If the service is in Running status - Output will be in Green

      .PARAMETER ServiceName
         Specifies the path to the CSV-based input file.
      .EXAMPLE
         Get-ColoredService -ServiceName Spooler,WinRM
      .EXAMPLE
         Get-ColoredService -ServiceName *
      .INPUTS
         Input single or multiple services names
      .OUTPUTS
         Output of the services information in the table format
   #>

   [cmdletbinding()]
   param(
      [string[]]$ServiceName
   )

}

When you check the help of the above function, you can see the variable name in the Syntax.

PS C:\WINDOWS\system32> Get-Help Get-ColoredService -Full
NAME
   Get-ColoredService
SYNOPSIS
   Gets the colored output of the Services based on Status

SYNTAX
   Get-ColoredService [[-ServiceName] <String[]>] [<CommonParameters>]

DESCRIPTION
   Get-ColoredService will provide the colorful output based on the status of the service.
   If the Service is in Stopped status - Output will be Red
   If the service is in Running status - Output will be in Green
   
PARAMETERS
   -ServiceName <String[]>
      Specifies the path to the CSV-based input file.

      Required?                      false
      Position?                      1
      Default value
      Accept pipeline input?         false
      Accept wildcard characters?    false

   <CommonParameters>
      This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information,
see
      about_CommonParameters
(https:/go.microsoft.com/fwlink/?LinkID=113216).

INPUTS
   Input single or multiple services name


OUTPUTS
Output of the services information in the table format


   -------------------------- EXAMPLE 1 --------------------------

   PS C:\>Get-ColoredService -ServiceName Spooler,WinRM

   -------------------------- EXAMPLE 2 --------------------------

   PS C:\>Get-ColoredService -ServiceName *

RELATED LINKS
raja
Published on 18-Dec-2020 13:31:43
Advertisements