PowerShell Advanced Functions: Cmdlet Bindings and Parameters

PowerShell, like other programming languages, uses functions as repeatable blocks of code.

Functions are useful for isolating large blocks of code from the main script body. In fact, you can even turn a PowerShell function into a standalone cmdlet. Below is an example of a basic PowerShell script containing a function:

Function Do-Something {            Write-Host 'The function is executing'            }#Main BodyWrite-Host 'The main body is executing'Write-Host 'The function is about to be called'Do-SomethingWrite-Host 'The function has ended and the main body is executing once again'

As you can see, the script does little more than display a couple of lines of text, call a function (named Do-Something), and then display a couple more lines of text. The function’s code is enclosed in braces.

Now, having looked at an example of a basic function, let’s discuss advanced functions in PowerShell. The term “advanced function” has a specific meaning, and it has nothing to do with the function’s complexity. An advanced function is a function that supports cmdlet bindings, parameters, or both.

We will explore what these terms mean and how we can transform the basic function shown above into an advanced function.

Common Parameters

If you have ever examined the syntax of native PowerShell cmdlets, you might have noticed that many cmdlets support common parameters. For instance, in Figure 1, you can see that the Get-Service cmdlet allows the use of common parameters.

PowerShell Advanced 1-1

Figure 1. Most native PowerShell cmdlets allow the use of common parameters.

Common parameters are just as the name suggests – parameters that are widely supported by native PowerShell cmdlets. Popular common parameters include:

Cmdlet Bindings

Here’s why I am bringing up common parameters: When you add cmdlet bindings to a function, you enable the function to support common parameters. This might sound a bit strange, but it ties back to the idea of converting a function into a standalone cmdlet.

PowerShell makes it simple to add cmdlet binding to a function. Just add these two lines below the function declaration:

[CmdletBinding()]Param()

As straightforward as this technique may be, it’s important to understand that adding cmdlet binding to a function does not do much on its own. You still need to tell PowerShell how the common parameters should be used. Thankfully, this is usually easier than it sounds.

Using Cmdlet Binding To Enable Error Handling

One commonly used common parameter is ErrorAction, which tells a PowerShell script how to handle non-fatal errors that may occur while executing the function.

To demonstrate how this works, take a look at the following script:

Function Do-Something {[Cmdletbinding()]Param()            Write-Host 'The function is executing'            Wrt-Host 'This is an error'            Write-Host ‘The function continues to execute’            }#Main BodyWrite-Host 'The main body is executing'Write-Host 'The function is about to be called'Do-Something -ErrorAction ContinueWrite-Host 'The function has ended and the main body is executing once again'

This script closely resembles the one I presented earlier, with a few additional lines of code:

When executing the script, it will display an error. However, the function will continue running despite the error because the error was non-fatal. You can see what this looks like in Figure 2. To be fair, even if I hadn’t included an error action, the function would have continued running in the event of a non-fatal error since that's PowerShell’s normal way of doing things.

PowerShell Advanced 1-2

Figure 2. When the PowerShell script encounters an error, the function continues running.

There are a couple of other ways to handle the error. In Figure 3, you can see what happens when the error action is changed to Stop. In this case, even though the error is non-fatal, PowerShell terminates the function upon encountering the error. It is worth noting that since the error action is applied to the function call, it is only the function (not the entire script) that terminates when the error occurs. When encountering the error, PowerShell simply abandons the function, returns to the script body, and continues to execute the rest of the script.

PowerShell Advanced 1-3

Figure 3. Setting the ErrorAction to Stop causes the function to terminate when an error occurs.

Figure 4 shows what happens when you set the error action to SilentlyContinue. In this case, even though the error occurs, PowerShell hides the error message and proceeds to execute the function to its completion.

PowerShell Advanced 1-4

Figure 4. Setting the ErrorAction to SilentlyContinue suppresses the error message, allowing PowerShell to continue running the function without interruption.

So far, I have demonstrated how to use cmdlet bindings to control what happens when a PowerShell function produces a non-fatal error. However, there is so much more that could be done. In Part 2, I will go further into the discussion and explain more you can do with cmdlet bindings.