Walkthrough: An example of how I write PowerShell functions

A couple of days ago I posted a blog article titled “PowerShell function: Test-ConsoleColor provides a visual demonstration of the foreach scripting construct” and today I thought I would walk you through that function step by step since it’s what I consider to be a well written PowerShell function.

It starts out by using the #Requires statement to require at least PowerShell version 3 or it won’t run. It also requires that the PowerShell Community Extensions module be installed since it uses a function from that module and continuing without it only leads to errors:

The function is then declared using a Pascal case name that uses an approved verb along with a singular noun. Comment based help is provided just inside the function declaration. This isn’t the only location where comment based help can be specified at, but it’s my preferred location for it:

This allows the function help to be viewed as it would be for any PowerShell command:


CmdletBinding is specified to turn this function into an advanced function. All of the parameters are specified using parameter validation attributes, the Paragraphs and Milliseconds parameters use data type constraints, and the Color parameter uses a .NET enumeration to try to catch invalid input as early as possible in a standardized way. Default values are provided to make the function as easy to use as possible:

I only want this function to be run in the PowerShell console:

Store the current console colors and title bar information in variables:

The background color is set in one foreach loop and then a nested foreach loop sets the foreground color for each of the 16 available color options before the background color is changed again. It takes 256 total iterations to view all possible color combinations of the PowerShell console if you count both the foreach loops:

Verbose output is also provided when the function is run with the Verbose parameter.

The colors and title bar are set back to the way they were before the function started using the variables that this information was previously stored in. The function declaration is closed with the last curly brace:

You could add things like pipeline input and error handling to improve it even further.

Remember to format your code for readability. Notice how the curly braces line up and the indentation of the code. Don’t use positional parameters or aliases in scripts and functions or any code that you’re sharing with others. Think about the next guy, it could be you.

I typically add my functions to a script module so I can simply call the function which auto-loads the module instead of having to manually locate and dot-source a .ps1 file. Note: Module auto-loading was introduced in PowerShell version 3.

Last but not least, you should place your code into some type of source control system such as GitHub or SAPIEN Technologies VersionRecall. It doesn’t matter if you’re an IT Pro or a developer, you should be using source control <period>.

The Test-ConsoleColor function shown in this blog article can be downloaded from my PowerShell repository on GitHub. To learn more, download the “Free eBook on PowerShell Advanced Functions” that I contributed to along with several other PowerShell MVP’s and/or enthusiasts.



  1. crshnbrn66

    nice walk through Mike.

  2. Michael Maher

    Hi Mike, thanks for this. One question. You are using ValidateNotNullOrEmpty but setting a default value in two cases. Is this just for the sake of completeness rather than having functional value. I went through the parameters help file to see if I am missing something.


Leave a Reply

%d bloggers like this: