While Windows PowerShell benefits admins in several ways, its extensibility may be its most important attribute. This includes PowerShell functions, those small, single task tools that consist of commands wrapped in a function box. Using functions makes it easier to debug and write less code by enabling you to port functions from one script to another.
So when are PowerShell functions most useful? Here are three basic guidelines to keep in mind:
- If you are repeating the same code block over and over -- such as a code block that checks several services on a computer. Here, you can use a function to perform a check and run it against each server, as well as troubleshoot codes more efficiently.
- If you use a specific code in other scripts. For example, if you write a recursive parsing block you may want to reuse that logic.
- If the code is useful outside of the script. This is slightly different from the previous guideline, with a good example being a ping-server function.
Generally speaking, it is always a good idea to consider reuse when writing code -- especially functions designed for reuse. Therefore, it’s important to consider how and where functions will be used to help establish what parameters they should have, as well as any defaults.
When considering reuse, it is best to be as thorough as possible and avoid hardcoding. In addition, all data should be passed through parameters when writing functions. While it’s okay to use default values for the parameters, you should allow the function caller to specify other options without having to modify the function. This is where black box tests come in handy by determining the usability of a function in different environments. As such, it’s important to consider every change to the original function and how those changes will affect the script as a whole. For instance, in PowerShell V1 I always try to implement –verbose and whatif commands with my own switches. In V2 this is handled for you.
You should also consider looping and processing logic when designing functions. Typically, you will find this is script-specific. For example, if you have logic to process servers, then you should keep that logic outside of the functions. There is no need to implement it for every function call. On the other hand if you have logic that is expressly the domain of the function, then you don’t need to remove it just to apply the calling script.
What makes a good function?
Great functions are born out of a specific need and grow out of use, but there are some commonalities that all good functions possess. Below are some of these features:
A function needs to be very clear on what data it is expected to return. You can do this by applying specific parameters. If you absolutely must have a specific value to process, then make sure it’s clear in the function. A great way to accomplish this is by assigning the parameter’s default value to $ThisParam is required.
Consistent and expected output
It is critical that you don't guess what data will come from the function, rather you want it to return what is expected. Design the function so that it returns one or more of a single data type, such as a string, DateTime or Boolean. But be careful not to pollute the data stream with unexpected data written with write-output or data that wasn’t captured in a variable.
The function should not rely on any variables from the script. If the function needs input from outside, make it a parameter.
The single most important job of a function is to be portable. If you do not plan to reuse the code you might as well write the code inline. A key factor to portability is to make sure your variable names will not collide with the calling script. As such, you can preface them with $my or $func.
You can follow SearchWindowsServer.com on Twitter @WindowsTT.
Miss a column? Check out our Scripting School archive.
ABOUT THE AUTHOR
Brandon Shell has been in the IT industry since 1994. He started out as a PC tech and general fix-it guy for numerous companies. In 2007, he joined the PowerShell MVP ranks, and Shell has spent the past several years building his PowerShell knowledge and helping others build theirs.