Data Structure
Networking
RDBMS
Operating System
Java
MS Excel
iOS
HTML
CSS
Android
Python
C Programming
C++
C#
MongoDB
MySQL
Javascript
PHP
Physics
Chemistry
Biology
Mathematics
English
Economics
Psychology
Social Studies
Fashion Studies
Legal Studies
- Selected Reading
- UPSC IAS Exams Notes
- Developer's Best Practices
- Questions and Answers
- Effective Resume Writing
- HR Interview Questions
- Computer Glossary
- Who is Who
How to write comment based Help in PowerShell?
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
390 Views
