PowerShell: Writing Professional Level Code

Making a Good Thing Better...

One of the great things about PowerShell is that it is feature rich with things that allow you to make your code robust, reliable and readable.  But if you're like me, you are always in a rush to get something done.  Well I have been stepping up the level of my code and want to share with some of the great things you can do to make your code more maintainable and supportable.

First, I always try to wrap things up in functions so I can make them reusable by passing parameters to them to change the behavior.  So let's take a look at a function I just wrote and I will highlight the nice coding features PowerShell has.  Actually, PowerShell has more features to support readability and reliability than any language I can think of.  So here it is...

<#    
.SYNOPSIS
    Does a Windows Message Box with optional parameters.      
.DESCRIPTION
    Using the .Net object to show a message box - [System.Windows.Forms.MessageBox]::Show($message , $title, $type)
.NOTES
    Author         : Bryan Cafferky, BPC Global Solutions, LLC
 
.PARAMETER message
This is the message (string) you want to display.

.PARAMETER title
This is the title to be put in the window title bar.

.PARAMETER type 
This sets the types of buttons you want.

 Types are
   0     OK
   1     OK Cancel
   2     Abort Retry Ignore
   3     Yes No Cancel
   4     Yes No
   5:     Retry Cancel
 
.LINK
    Place link here.
.EXAMPLE
    ufn_ShowMessageBox "Show this message" "Important" 4   
.EXAMPLE  
    Example 2
#> 

function ufn_ShowMessageBox
{
    [CmdletBinding()]
    param (
    [Parameter(Mandatory=$true,ValueFromPipeline=$false)]
    [string] $message,
    [Parameter(Mandatory=$true,ValueFromPipeline=$false)]
    [string] $title,
    [Parameter(Mandatory=$true,ValueFromPipeline=$false)]
    [ValidateRange(0,5)]
    [int] $type
    )
 
 write-verbose  $message

 RETURN [System.Windows.Forms.MessageBox]::Show($message , $title, $type)

}

Note: This function is handy when you want to display a message box. 

First, there is the CmdletBinding which enables a lot of power in your ability to validate parameters and support optional testing message features like write-verbose and write-debug.  So when you have the CmdletBinding, you automatically get the ability to add statements to display only when you pass the relavant switch such as -verbose, i.e.

ufn_ShowMessageBox "Super" "Important" 3 -verbose

would cause any write-verbose statements to display. 

Of course we have the # for a single line comment and <# to start a block of comment lines and #> to end it.  Use these often to make your code understandable.

I particularly like the    [Parameter(Mandatory=$true,ValueFromPipeline=$false)] statements.  These allow you to control things about the parameter like if the parameter is required and if it can come from a pipeline. 

You can also have PowerShell automatically validate the parameters.  Here I only use    [ValidateRange(0,5)] which rejects any values less than zero or greater than 5.  There are many different Validate statement and just to show a few...

ValidateNotNull()
ValidateSet("one","two")
ValidateNotNullOrEmpty()
ValidateLength(1 50)
ValidatePattern([A-Za-z])

Lastly I want to mention the . comment blocks.  These are tagged by special reserved words that get-help is supposed to pick up for documentation purposes.  So the line

 .SYNOPSIS
    Does a Windows Message Box with optional parameters.     

Will display when a user enters

. .ufn_ShowMessageBox.ps1      #must load the function first by dot sourcing.
get-help ufn_ShowMessageBox -full

Frankly, I think this is slick and reminds of the java javadoc statements.  Using this feature will impress users of your code and increase the likelihood your functions will get used.

That's all for now but I hope you found this helpful.  Lord knows I've learned so much from all the people out there who take the time to share their knowledge.

Bryan