PowerShell Functions Comment Based Help

Creating scripts that are easily portable and transferable is a huge bonus in the automation world.  Sys admins are notorious for developing huge script repositories that only they can use easily because of how they are written, named, stored etc..

If you are tired of not being able to share and transport your tribal knowledge, PowerShell modules with properly formatted functions are a great and easy way to turn those script libraries into distributable automation tools that can save time and money.

Before you can start compiling your modules, you need to take those scripts and turn them into properly formatted functions that can be easily used by others.  How do we do this?  Create your functions using the format template below.  This will give your audience the ability to get detailed information on each of the functions that you have packaged for them and specific examples on how to use each one.  The biggest plus here is that you spend a little more time preparing your tools but save big on having to document and train people to use your spiffy tools.

As a use case, I recently created a PowerShell module for a team that owns monitoring support so that they could perform various tasks on their agents without having to RDP or remote control every server they wanted to work on.

Functions in my module:

    Port Test - Test for connection to remote host on specific port
    Remove Proxy - Remove proxy server blocking communication on remote system
    Restart Services - Restart agent services on remote system
    Check Services - Check status of agent services on remote system
    Kill Processes - Forcibly stop agent processes and services on remote system
    Open Configuration File - Open the configuration file of a remote system
    Set IP Address - Changes IP address in remote server configuration file

Let's take a look at the general format I used for each function and how to construct of function.  The help section specifically.  Remember, in order to make your functions and modules portable and usable, people need to be able to understand what syntax they have to use and exactly (with as much detail as you deem relevant) what your script and function is written to do.  They easiest way to accomplish this without creating a bunch of outside documentation that will get lost and saved on some file share that no one will read, use comment based help that precedes each of your functions.

Using the template below, you can fill in the headings and values you need to and presto, you have a PowerShell function with comment based help.  Once loaded into your PowerShell profile, you can use Get-Help MyExample-Function -full and it will return the help info and examples just like a full-fledged, big-boy cmdlet.

<#.SYNOPSIS    
                      
                      Short one-liner - Script does this
                      
                          
                      
                      .DESCRIPTION  
                      
                      Full and detailed description of all function actions
                      
                      
                      .PARAMETER computername  
                      
                      This is a description of the parameters that can be used in your function.  You can add as many Parameters as you need.
                      
                      Leave this blank if it does not apply.
                      
                                                   
                      
                      .NOTES    
                      
                      Name: Name of Function
                      
                      Author: Your Name  
                      
                      DateCreated: Date Created or Last Modified
                      
                         
                      
                      .EXAMPLE    
                      
                      Show how to invoke the function with the desired syntax
                      
                      
                      .EXAMPLE    
                      
                      Give examples using any and all parameters and pipe inputs (if any) that the function will accept
                      
                      #>
                      
                      function MyExample-Function {
                      #Cmdletbinding allows you to use PowerShell Common Parameters with your function without coding them 
                      
                      #This will give you the ability to use Verbose and ErrorAction switches to control Function actions and output.
                      
                      
                      [cmdletbinding(  
                      
                          DefaultParameterSetName = '',  
                      
                          ConfirmImpact = 'low'  
                      
                      )] 
                      
                          param(
                      
                      [Parameter(  
                      
                                  Mandatory = $True,  
                      
                                  Position = 0,  
                      
                                  ParameterSetName = '',  
                      
                                  ValueFromPipeline = $True)]  
                      
                                  [string[]]$computername
                      
                      )
                      
                      Write-Host "This is my Example Function to show you how to construct comment based help"
                      
                      }
                      

Select all Open in new window

I suggest taking a look at TechNet's article on PowerShell parameters and Cmdletbinding.  The sample above is a practical implementation, but I will let those significantly more published than myself explain the intricacies to you.  Don Jones on Windows IT Pro has an excellent article on the available common parameters and what they do.