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(" - 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.


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

#Requires -Version 3
#Requires -RunAsAdministrator 

Make a VHD File bootable
Converts a raw *.vhd file to a bootable *.vhd file
File path to a VHD File to be made active
.\Make-VHDBootable.ps1 -verbose -path C:\15\install.vhdx
Copyright Microsoft Corp, All Rights reserved.

       [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.


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

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

    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".

One thought on “Adding Help to your PowerShell Script

Leave a Reply

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

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

Google photo

You are commenting using your Google 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 )

Connecting to %s