Adding Help to your PowerShell Script

So, after working on your PowerShell script for a while, you figure it’s time to cleanup the comments and add some help so other people can use it.

PowerShell has an existing framework setup for getting help that most people already understand, it’s the “Get-Help” cmdlet, but most PowerShell scripters don’t realize that you can use “Get-Help” for your script, if formatted correctly.

The wrong way

First off, let’s discuss how not to do help, occasionally, I will see scripts that try to parse the arguments passed into the script:

if(($args.Count -gt 0) -and (
        ($args[0].ToLower() -eq "/?") -or 
        ($args[0].ToLower() -eq "/help") -or 
        ($args[0].ToLower() -eq "-h") -or 
        ($args[0].ToLower() -eq "--help") -or 
        ($args[0].ToLower() -eq "-help")))  {

    Write-Host("USAGE:")
    Write-Host(" - Get Some Info: GetInfo")
    Write-Host(" - Get Remote Info: GetInfo <COMPUTER NAME | IP>")
    Write-Host(" - Get Many Remote Info: GetInfo <COMPUTER NAME | IP> <COMPUTER NAME | IP> (Repeat as many times as needed")
    Write-Host(" - Show this help: GetInfo /? | /help | -h | --help")
} Else {
    if($args.Count -eq 0) {$args = ("localhost")}
    Foreach($computer in $args) {
        Write-Host "Do Something $Computer"
    }
}

This is very much a C++/C#/Java way of parsing arguments, and doesn’t leverage built-in PowerShell functionality.

about_comment_based_help

Powershell has built in functionality for self documenting help based on the comment block of your function or script:

#Requires -Version 3
#Requires -RunAsAdministrator 

<#
.SYNOPSIS
Make a VHD File bootable
.DESCRIPTION
Converts a raw *.vhd file to a bootable *.vhd file
.PARAMETER Path
File path to a VHD File to be made active
.EXAMPLE
.\Make-VHDBootable.ps1 -verbose -path C:\15\install.vhdx
.NOTES
Copyright Microsoft Corp, All Rights reserved.
#>

[CmdletBinding()]
param(
       [Parameter(Mandatory=$true)]
       [string] $Path
)

$MountedVHD = Mount-VHD -Path $Path –Passthru
if ( $MountedVHD ) {
    $MountedVHD | Out-String | Write-Verbose
    $Drive = $MountedVHD | Get-Disk | Get-Partition | Get-Volume | Select-Object -ExpandProperty DriveLetter
    if ( Test-Path "$Drive`:\Windows\System32\BCDBoot.exe" ) {
        & "$Drive`:\Windows\System32\BCDBoot.exe" "$Drive`:\Windows" /s "$Drive`:" /F ALL | out-string |write-verbose
    }
    Dismount-VHD -Path $Path
}

Note how I have two #requires strings at the top of the script, this is an easy way to enforce basic script requirements. Most of the scripts I write require Elevated Administrative privileges, and this is the quickest way to make sure this works.

There is a large comment block at the top of the script describing what the script does. See: about_comment_based_help

Also note that I try to match the Parameters for my function with any cmdlets I will pass the parameters to within the function, that way I can convert to Splatting down the road if beneficial.

Get-Help

We know how get-help works for most of our cmdlets, and it’s a great way to learn the details of what functions do. But did you know that get-help also works for scripts?

Just run get-help with your full script path as the parameter:

PS C:\Users\Keith\Desktop> get-help .\Make-VHDBootable.ps1

NAME
    C:\Users\Keith\Desktop\Make-VHDBootable.ps1
    
SYNOPSIS
    Make a VHD File bootable
    
SYNTAX
    C:\Users\Keith\Desktop\Make-VHDBootable.ps1 [-Path] <String> [<CommonParameters>]
    
DESCRIPTION
    Converts a raw *.vhd file to a bootable *.vhd file
    
RELATED LINKS

REMARKS
    To see the examples, type: "get-help C:\Users\Keith\Desktop\Make-VHDBootable.ps1 -examples".
    For more information, type: "get-help C:\Users\Keith\Desktop\Make-VHDBootable.ps1 -detailed".
    For technical information, type: "get-help C:\Users\Keith\Desktop\Make-VHDBootable.ps1 -full".

Advertisements

One thought on “Adding Help to your PowerShell Script

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s