The vast majority of Windows’ native PowerShell cmdlets include support for common parameters. If you look at the figure below, for example, you can see that the syntax for the Get-Service cmdlet lists CommonParameters among the cmdlet’s supported parameters.
For those who might not be familiar with common parameters, they include things like:
• Debug
• ErrorAction
• ErrorVariable
• InformationAction
• InformationVariable
• OutVariable
• OutBuffer
• PipelineVariable
• Verbose
• WarningAction
• WarningVariable
• WhatIf
• Confirm
Not every cmdlet supports every common parameter, but throughout PowerShell, these common parameters are widely supported. You might for example, append -WhatIf to a cmdlet to see what would happen if the cmdlet were run “for real,” or you might append -the Verbose parameter to a cmdlet to view verbose output.
Creating functions that act as cmdlets
So with that said, let’s switch gears for a moment. Although PowerShell contains a huge number of native cmdlets, you are not limited to working solely with those cmdlets. There are external modules that extend the command set, and it is also possible to create your own functions that essentially act as cmdlets.
Let me give you a really simple example. PowerShell includes a built-in cmdlet named Get-Service that displays the names of all of the system services. Let’s pretend for a moment that for whatever reason, you wanted to create a similar cmdlet called List-Services that listed the name of each service and whether or not the service was running. It is unlikely that you would do this in real life because the desired output can be achieved using the Get-Service cmdlet, I’m just using this scenario for the sake of illustration. At any rate, you could achieve this goal by using a function. Here is what the code might look like:
Function List-Services
{
Get-Service | Select-Object Name, Status
}
Now, every time you include the List Services command within this script, the script will display a list of all of the service names and their statuses. In other words, the function name (List Services) is essentially treated like a command. Unlike native cmdlets, functions do not normally support the use of common parameters. Even so, it is relatively easy to extend common parameter support to functions, thereby making the function behave much more like a native PowerShell cmdlet.
The first thing that you need to know about adding common parameter support to a function is that there is no magical command that will suddenly enable all of the common parameters. Instead, you will have to decide which of the common parameters that you want to support, and then tell your function how it should behave if those common parameters are used. Space limitations prevent me from talking about each common parameter individually, but I do want to show you a few examples.
My personal favorite is the Verbose parameter. The Verbose parameter allows you to tell your function that you want to display more detailed (verbose) output. Of course, you have to tell your function how to differentiate between normal output and verbose output.
To show you how this works, let’s go back to the function that I showed you earlier, and let’s make it so that when verbose output is enabled the function displays a line of text that says “These are the system services”.
The first thing that you will need to do is to add two lines of code to the beginning of the function. These lines of code enable cmdlet binding, which is what allows the common parameters to be used. Here are the two lines:
[cmdletbinding()] Param()
Once those two lines are in place, you can insert the Write-Verbose cmdlet anywhere that you want to display verbose text. Here is what the function might look like:
Function List-Services
{
[cmdletbinding()]
Param()
Write-Verbose "These are the system services:"
get-Service | Select-Object Name, Status
}
If you look at the figure below, you can see that I have created a short script that calls the function using the -Verbose parameter. You can also see in the output that the verbose text is displayed as a result. Had I run the function without the Verbose parameter, that line of text would not have been displayed.
Support for WhatIf
Now that I have shown you how the verbose parameter works, let’s switch things up a bit and add support for the WhatIf parameter. To do so, I am going to modify my script to pass the name of a service to the function, and then have the function to start the requested service. Here is what such a script might look like:
Function List-Services
{
[cmdletbinding()]
Param($Name)
Get-Service $Name
Start-Service $Name
Get-Service $Name
}
cls
List-Services VSS
As you can see, I am passing a service name (VSS) to the function as a parameter ($Name). The function then displays the service, starts the service, and then displays the service one more time to confirm that it has started. Here is what the output looks like:
Starting the VSS service is harmless, but let’s pretend for a moment that there is the potential for the function to cause damage if it is used incorrectly. If that were the case, then it might make sense to add WhatIf support so that an administrator could evaluate the function’s behavior before committing to a potentially destructive action. Here is what the script looks like:
Function List-Services
{
[cmdletbinding(SupportsShouldProcess)]
Param($Name)
If ($PSCmdlet.ShouldProcess("Starting the system service named: " + $Name)) {
Get-Service $Name
Start-Service $Name
Get-Service $Name
}
}
cls
List-Services VSS -WhatIf
As you look at the script above, you will notice that I have added SupportsShouldProcess to the cmdletbinding. This is what adds support for WhatIf. It has also created an “if” command that starts out with If ($PSCmdlet.ShouldProcess. This command determines the script’s behavior based on whether or not the -WhatIf parameter has been used. If WhatIf has been used, then the text within the parenthesis is displayed. Otherwise, the commands within the command block below are executed. Here is the script’s output with the -WhatIf parameter in use. Incidentally, if the -WhatIf parameter is removed then the output matches what you saw in the previous screen capture.
Going native with PowerShell functions
As you can see, the use of cmdlet binding allows you to leverage common parameters within your PowerShell functions. This can go a long way toward making your functions behave more like native cmdlets.
