PowerShell has a very robust online help capabilities. These abilities are extended to you, the user, when you are creating functions and scripts. You may have functions that you load as part of your profile or that you have created as part of a customized module. To do this is very simple. Take a look at the function below.
This function simply outputs what you put into it. Let’s add some help functionality to it.
To do this, we need to add a block comment section immediately after the Function declaration line. Block comments are normal comment statements. The difference is that instead of every line starting with ‘#’, we start with ‘<#’. You can type as many lines as you want and all of them will be considered comments until you end the comment block with ‘#>’.
We add the help by adding these lines.
.SYNOPSIS
Provides a brief statement of what this function or script does.
.DESCRIPTION
This is a more detailed explaination of the script or function.
.PARAMETER parameter
This will descript the purpose of each parameter. Add addition .PARAMTER lines for multiple parameters
.EXAMPLE
Provide one or more examples by adding more .EXAMPLE lines.
.INPUTS
This is the list of Microsoft .NET Framework objects that can be piped to this function.
.OUTPUTS
The .NET Framework type of object that is returned from this function or cmdlet.
.NOTES
Any additional information about this function or cmdlet.
You can read about these, and more attributes of the help file by executing this line in PowerShell: help About_ comment_based_help
Let’s add a help file and see the results.
Here is the help file if we execute Get-Help WriteText –Full
Function WriteText {
Param (
[parameter(Mandatory=$True,ValueFromPipeline=$True)]$InputValue `
= (Read-Host 'Please provide an input value: '))
BEGIN {}
PROCESS{
Write-Host $InputValue
}
END {}
}
This function simply outputs what you put into it. Let’s add some help functionality to it.
To do this, we need to add a block comment section immediately after the Function declaration line. Block comments are normal comment statements. The difference is that instead of every line starting with ‘#’, we start with ‘<#’. You can type as many lines as you want and all of them will be considered comments until you end the comment block with ‘#>’.
We add the help by adding these lines.
.SYNOPSIS
Provides a brief statement of what this function or script does.
.DESCRIPTION
This is a more detailed explaination of the script or function.
.PARAMETER parameter
This will descript the purpose of each parameter. Add addition .PARAMTER lines for multiple parameters
.EXAMPLE
Provide one or more examples by adding more .EXAMPLE lines.
.INPUTS
This is the list of Microsoft .NET Framework objects that can be piped to this function.
.OUTPUTS
The .NET Framework type of object that is returned from this function or cmdlet.
.NOTES
Any additional information about this function or cmdlet.
You can read about these, and more attributes of the help file by executing this line in PowerShell: help About_ comment_based_help
Let’s add a help file and see the results.
Function WriteText {
<#
.SYNOPSIS
Writes what you give it.
.DESCRIPTION
This function displays the input that it was provided.
.PARAMETER $InputValue
Accepts String or integer values.
.EXAMPLE
WriteText "Hello World"
.EXAMPLE
WriteText -InputValue "Hello World"
#>
Param (
[parameter(Mandatory=$True,ValueFromPipeline=$True)]$InputValue `
= (Read-Host 'Please provide an input value: '))
BEGIN {}
PROCESS{
Write-Host $InputValue
}
END {}
}
Here is the help file if we execute Get-Help WriteText –Full
NAME
WriteText
SYNOPSIS
Writes what you give it.
SYNTAX
WriteText [-InputValue] <Object> [<CommonParameters>]
DESCRIPTION
This function displays the input that it was provided.
PARAMETERS
-InputValue <Object>
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters?
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
C:\PS>WriteText "Hello World"
-------------------------- EXAMPLE 2 --------------------------
C:\PS>WriteText -InputValue "Hello World"
RELATED LINKS
Comments