How do I get help messages to appear for my Powershell script parameters?
PowershellPowershell 2.0Powershell Problem Overview
I have a powershell script (setup.ps1
), that we use as the entry point for our development environment setup scripts. It takes a parameter:
param(
[Parameter(Position=0,HelpMessage="The targets to run.")]
[Alias("t")]
[string[]]
$Targets = "Help"
)
When I run
PS > get-help .\setup.ps1 -detailed
in the parameters section, my help message doesn't appear:
PARAMETERS
-Targets <String[]>
What do I need to do to get my parameter help messages to display?
Powershell Solutions
Solution 1 - Powershell
You put a certain style of comment at the top of the file that can be decoded by the PowerShell help system. Here's an example:
<#
.SYNOPSIS
.
.DESCRIPTION
.
.PARAMETER Path
The path to the .
.PARAMETER LiteralPath
Specifies a path to one or more locations. Unlike Path, the value of
LiteralPath is used exactly as it is typed. No characters are interpreted
as wildcards. If the path includes escape characters, enclose it in single
quotation marks. Single quotation marks tell Windows PowerShell not to
interpret any characters as escape sequences.
.EXAMPLE
C:\PS>
<Description of example>
.NOTES
Author: Keith Hill
Date: June 28, 2010
#>
function AdvFuncToProcessPaths
{
[CmdletBinding(DefaultParameterSetName="Path")]
param(
[Parameter(Mandatory=$true, Position=0, ParameterSetName="Path",
ValueFromPipeline=$true,
ValueFromPipelineByPropertyName=$true,
HelpMessage="Path to ...")]
[ValidateNotNullOrEmpty()]
[string[]]
$Path,
[Alias("PSPath")]
[Parameter(Mandatory=$true, Position=0, ParameterSetName="LiteralPath",
ValueFromPipelineByPropertyName=$true,
HelpMessage="Path to ...")]
[ValidateNotNullOrEmpty()]
[string[]]
$LiteralPath
)
...
For more info see the help topic - man about_comment_based_help
.
Solution 2 - Powershell
Apparently if you have a help header defined, you can just use a remark (#) behind the parameter (in this example: #The targets to run.):
<#
.SYNOPSIS
.
.DESCRIPTION
.
.PARAMETER Path
The path to the .
.PARAMETER LiteralPath
Specifies a path to one or more locations. Unlike Path, the value of
LiteralPath is used exactly as it is typed. No characters are interpreted
as wildcards. If the path includes escape characters, enclose it in single
quotation marks. Single quotation marks tell Windows PowerShell not to
interpret any characters as escape sequences.
#>
Param(
[String]$Targets = "Help" #The targets to run.
)
Results in:
PS C:\> Get-help .\Setup.ps1 -Detailed
NAME
C:\Setup.ps1
SYNOPSIS
.
SYNTAX
C:\Setup.ps1 [[-Targets] <String>] [<CommonParameters>]
DESCRIPTION
.
PARAMETERS
-Targets <String>
The targets to run.
Solution 3 - Powershell
one just needs the <# .SYNOPSIS #>
part on top of the file to make it work and you can comment your params nicely inline:
<# .SYNOPSIS #>
param(
[String]$foo ## my 1st cool param
,[Switch]$bar ## my 2nd crazy switch
)
...
(checked with PS 5.1.14409.1018
)