Getting Started - Help!
Welcome to my Getting Started with Windows PowerShell series!
In case you missed the earlier posts, you can check them out here:
- Customizing your environment
- Command discovery
- Using the ISE and basic function creation
- A deeper dive into functions
- Loops
- Modules
We will be exploring:
Adding help
Adding help to your code is a great way to help people learn how to use it! It will also be useful for yourself if you have scripts you may use down the road, but do not need to use them all the time. It is easy to add, and maintain. The method of help I will be demonstrating is accessible via the Get-Help command.
Comment block creation
To create comment based help in PowerShell, you'll need the following basic layout:
<# .SYNOPSIS A brief description of what your code does. .DESCRIPTION A full description of what your code does. .NOTES Name: Script/function/module name Author: Your Name DateCreated: The current date #>
It is important to note that the comment section begins with '<#', and ends with '#>'.
This block should go above all of the code you are going to use, and is the only thing in PowerShell allowed above the [cmdletbinding()] statement.
For this basic example we will display the synopsis, description, and notes keywords. There are more keywords, and I will be going over those later in the accessing keywords section. All of the keyword identifiers must start with a period '.' for PowerShell to recognize them.
Here are some examples of the help block in action.
Script
Get-Help .\part7example.ps1
Function
To see this one we will need to import the module containing the function.
Import-Module .\part7examplemodule.psm1
Now we can use Get-Help, along with the function name, to display the help block's contents.
Get-Help Get-HelpExample
Accessing various keywords
You can access various keywords using different parameters with Get-Help. For this example I will be adding help to our function Write-Pretty from Part 6.
We'll be using the following comment based help block:
<# .SYNOPSIS This function will output text in different ways depending on the arguments received. .DESCRIPTION Write-Pretty will output text in the following ways: ------ |Random| ------ Random will add some spacing and split your text into an array using a space. It will take each part of the array and apply a random color to it. [Random] will be prepended to the text. ----- |Error| ----- Error will output the text as red. [Error] will be prepended to the text. ------- |Warning| ------- Warning will output the text as yellow. [Warning] will be prepended to the text. ---- |Info| ---- Info will output the text as as white, as is the default option if you do not specify any parameters. [Info] will be prepended to the text. .PARAMETER prettyText Alias: Text Argument: This parameter is the text you'd like to affect the look of. This parameter accepts value from the pipeline. .PARAMETER textType Alias: Type Argument: This parameter affects the type of text you'd like to display. Valid types: Random Error Warning Info .NOTES Name: part7.psm1 Author: Ginger Ninja (Mike Roberts) DateCreated: 5/8/16 .LINK http://www.gngrninja.com/script-ninja/2016/5/8/powershell-getting-started-part-7-help .EXAMPLE Write-Pretty -Text 'This is some pretty text.' -Type Random --------------------------------------------------------------- [Random] This is some pretty text .EXAMPLE Write-Pretty -Text 'This is some pretty text, and it is now an error.' -Type Error --------------------------------------------------------------- [Error] This is some pretty text, and it is now an error .EXAMPLE Write-Pretty -Text 'Warning, this will output warning text!' -Type Warning --------------------------------------------------------------- [Warning] Warning, this will output warning text! .EXAMPLE Write-Pretty -Text 'This will output info text.' -Type Info --------------------------------------------------------------- [Info] This will output info text. .EXAMPLE Write-Pretty "I wonder what happens if we don't specify an option..." --------------------------------------------------------------- [Info] I wonder what happens if we don't specify an option... .EXAMPLE Get-Process | Select-Object -ExpandProperty Name -First 5 | Sort-Object Name | Write-Pretty --------------------------------------------------------------- [Info] Battlenet [Info] Battlenet Helper [Info] AGSService [Info] AdobeUpdateService [Info] Agent #>
I've added some more keywords so we can use Get-Help in various ways with the function Write-Pretty. The link keyword allows you to add a link for use with the -online parameter. The parameter keyword allows you to display help information for each parameter via the -parameter <name> parameter and argument. I also added some examples of the code being used, and expected output via the examples keyword. This keyword can be access via the -examples parameter with Get-Help.
Let's take a look at the full code for this post. If you'd like to try it out for yourself, open the ISE and save the code as C:\PowerShell\part7.psm1.
#Begin function Write-Pretty function Write-Pretty { <# .SYNOPSIS This function will output text in different ways depending on the arguments received. .DESCRIPTION Write-Pretty will output text in the following ways: ------ |Random| ------ Random will add some spacing and split your text into an array using a space. It will take each part of the array and apply a random color to it. [Random] will be prepended to the text. ----- |Error| ----- Error will output the text as red. [Error] will be prepended to the text. ------- |Warning| ------- Warning will output the text as yellow. [Warning] will be prepended to the text. ---- |Info| ---- Info will output the text as as white, as is the default option if you do not specify any parameters. [Info] will be prepended to the text. .PARAMETER prettyText Alias: Text Argument: This parameter is the text you'd like to affect the look of. This parameter accepts value from the pipeline. .PARAMETER textType Alias: Type Argument: This parameter affects the type of text you'd like to display. Valid types: Random Error Warning Info .NOTES Name: part7.psm1 Author: Ginger Ninja (Mike Roberts) DateCreated: 5/8/16 .LINK http://www.gngrninja.com/script-ninja/2016/5/8/powershell-getting-started-part-7-help .EXAMPLE Write-Pretty -Text 'This is some pretty text.' -Type Random --------------------------------------------------------------- [Random] This is some pretty text .EXAMPLE Write-Pretty -Text 'This is some pretty text, and it is now an error.' -Type Error --------------------------------------------------------------- [Error] This is some pretty text, and it is now an error .EXAMPLE Write-Pretty -Text 'Warning, this will output warning text!' -Type Warning --------------------------------------------------------------- [Warning] Warning, this will output warning text! .EXAMPLE Write-Pretty -Text 'This will output info text.' -Type Info --------------------------------------------------------------- [Info] This will output info text. .EXAMPLE Write-Pretty "I wonder what happens if we don't specify an option..." --------------------------------------------------------------- [Info] I wonder what happens if we don't specify an option... .EXAMPLE Get-Process | Select-Object -ExpandProperty Name -First 5 | Sort-Object Name | Write-Pretty --------------------------------------------------------------- [Info] Battlenet [Info] Battlenet Helper [Info] AGSService [Info] AdobeUpdateService [Info] Agent #> [cmdletbinding()] param( [Parameter( Mandatory = $True, ValueFromPipeline = $True )] [Alias('Text')] $prettyText, [Parameter(Mandatory=$false)] [Alias('Type')] $textType ) Begin { #Create a space before the text is displayed. Write-Host `n } Process { #Begin process for Write-Pretty function ForEach ($textItem in $prettyText) { #Begin ForEach loop to handle prettyText input (normal and via pipeline) Switch ($textType) { #Begin switch for textType argument {$_ -eq 'Random'} { Write-Host -NoNewline "[" -ForegroundColor $(Get-Random -Minimum 1 -Maximum 15) Write-Host -NoNewline "R" -ForegroundColor $(Get-Random -Minimum 1 -Maximum 15) Write-Host -NoNewline "andom" -ForegroundColor $(Get-Random -Minimum 1 -Maximum 15) Write-Host -NoNewline "]" -ForegroundColor $(Get-Random -Minimum 1 -Maximum 15) #Split the text into an array, split by spaces. (Also turns it into a string before the split). #We needed to turn it into a string in case the type wasn't string when it was received. Or else the .Split() method wouldn't work $writeText = $textItem.ToString().Split(' ') #Change the text color for each element in the array. ForEach ($text in $writeText) { Write-Host -NoNewLine " $text" -ForegroundColor $(Get-Random -Minimum 1 -Maximum 15) } Write-Host `n } {$_ -eq 'Error'} { Write-Host -NoNewline "[" -ForegroundColor White Write-Host -NoNewline "Error" -ForegroundColor Red -BackgroundColor DarkBlue Write-Host -NoNewline "]" -ForegroundColor White Write-Host " $textItem" -ForegroundColor Red } {$_ -eq 'Warning'} { Write-Host -NoNewline "[" -ForegroundColor White Write-Host -NoNewline "Warning" -ForegroundColor Yellow -BackgroundColor Blue Write-Host -NoNewline "]" -ForegroundColor White Write-Host " $textItem" -ForegroundColor Yellow } {$_ -eq 'Info' -or $_ -eq $null} { Write-Host -NoNewline "[" -ForegroundColor White Write-Host -NoNewline "Info" -ForegroundColor Green -BackgroundColor Black Write-Host -NoNewline "]" -ForegroundColor White Write-Host " $textItem" -ForegroundColor White } #The default option will simply write the text with no changes. This is if you do not specify a valid option for textType. Default { Write-Host $textItem } } #End switch for textType argument } #End ForEach loop to handle prettyText input (normal and via pipeline) } #End process for Write-Pretty function End { Write-Host `n } } #End function Write-Pretty #Display this message when the module is imported. Write-Pretty -Text 'Part7 module loaded!' -textType Random
Now we'll need to import the module...
Import-Module .\part7.psm1
Now that it is imported, let's look at the various ways to access the help for the Write-Pretty function!
Get-Help
Get-Help Write-Pretty
Detailed
This will show us all of the available keywords.
Get-Help Write-Pretty -Detailed
Online
This will send us to the website (URI) defined in the link keyword.
Get-Help Write-Pretty -Online
Parameters
This one will display the information defined in the specified parameter keyword.
Get-Help Write-Pretty -Parameter prettyText
Get-Help Write-Pretty -Parameter textType
Examples
Get-Help Write-Pretty -Examples
This will display all the examples defined via the example keyword.
Adding comments to your code
Comments in your code provide messages to anyone editing the file. It can be useful for others that are reviewing your code (to see what it's doing, or more importantly, WHY it is doing what it is doing). You can add comments by simply starting the line with '#'
#This is an example comment. It will not be executed by PowerShell, but can be read by someone editing the script.
I like to add comments to the following areas of my code:
- Code that performs a specific task that may seem out of place.
- The beginning and end of functions, loops, ifs, and switches.
- Any statements or block of code that are long, and it may be hard to see where they begin and end.
I added comments to the code we used in this post. Here is a snippet, which encompasses the Process {} statement in the Write-Pretty function. There are also some other comments inside this example as well.
Process { #Begin process for Write-Pretty function ForEach ($textItem in $prettyText) { #Begin ForEach loop to handle prettyText input (normal and via pipeline) Switch ($textType) { #Begin switch for textType argument {$_ -eq 'Random'} { Write-Host -NoNewline "[" -ForegroundColor $(Get-Random -Minimum 1 -Maximum 15) Write-Host -NoNewline "R" -ForegroundColor $(Get-Random -Minimum 1 -Maximum 15) Write-Host -NoNewline "andom" -ForegroundColor $(Get-Random -Minimum 1 -Maximum 15) Write-Host -NoNewline "]" -ForegroundColor $(Get-Random -Minimum 1 -Maximum 15) #Split the text into an array, split by spaces. (Also turns it into a string before the split). #We needed to turn it into a string in case the type wasn't string when it was received. Or else the .Split() method wouldn't work $writeText = $textItem.ToString().Split(' ') #Change the text color for each element in the array. ForEach ($text in $writeText) { Write-Host -NoNewLine " $text" -ForegroundColor $(Get-Random -Minimum 1 -Maximum 15) } Write-Host `n } {$_ -eq 'Error'} { Write-Host -NoNewline "[" -ForegroundColor White Write-Host -NoNewline "Error" -ForegroundColor Red -BackgroundColor DarkBlue Write-Host -NoNewline "]" -ForegroundColor White Write-Host " $textItem" -ForegroundColor Red } {$_ -eq 'Warning'} { Write-Host -NoNewline "[" -ForegroundColor White Write-Host -NoNewline "Warning" -ForegroundColor Yellow -BackgroundColor Blue Write-Host -NoNewline "]" -ForegroundColor White Write-Host " $textItem" -ForegroundColor Yellow } {$_ -eq 'Info' -or $_ -eq $null} { Write-Host -NoNewline "[" -ForegroundColor White Write-Host -NoNewline "Info" -ForegroundColor Green -BackgroundColor Black Write-Host -NoNewline "]" -ForegroundColor White Write-Host " $textItem" -ForegroundColor White } #The default option will simply write the text with no changes. This is if you do not specify a valid option for textType. Default { Write-Host $textItem } } #End switch for textType argument } #End ForEach loop to handle prettyText input (normal and via pipeline) } #End process for Write-Pretty function
Homework
- Take a deeper dive into the different options available to you with comment based help
Get-Help about_Comment_Based_Help -Online
- https://technet.microsoft.com/en-us/library/hh847834.aspx
I hope you've enjoyed the series so far! As always, leave a comment if you have any feedback or questions!
-Ginger Ninja