<

PowerShell Functions Comment Based Help

Published on
8,319 Points
2,219 Views
1 Endorsement
Last Modified:
Approved
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"

}

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.
1
Comment
Author:Mahoney-84
1 Comment
 
LVL 73

Expert Comment

by:Qlemo
Some important points I have to add to above article:

If you want to know more about Comment Based Help, use get-help about_Comment_Based_Help or the online help at http://technet.microsoft.com/en-us/library/hh847834.aspx) .

There are certain restrictions where the comment can be placed, and other restrictions which apply like no more than one empty line after/before it if outside of a function.

Lastly, Get-Help works without CBH, and hence a CBH should add important info to what would be auto-generated, else it just isn't worth the effort.
0

Featured Post

Protect Your Employees from Wi-Fi Threats

As Wi-Fi growth and popularity continues to climb, not everyone understands the risks that come with connecting to public Wi-Fi or even offering Wi-Fi to employees, visitors and guests. Download the resource kit to make sure your safe wherever business takes you!

Join & Write a Comment

Exchange organizations may use the Journaling Agent of the Transport Service to archive messages going through Exchange. However, if the Transport Service is integrated with some email content management application (such as an anti-spam), the admin…
Screencast - Getting to Know the Pipeline

Keep in touch with Experts Exchange

Tech news and trends delivered to your inbox every month