PowerShell – Using Common Parameters

One of the most useful features provided in PowerShell are “Common Parameters”. These are parameters which you can utilize in your own scripts and functions to provide a similar look and feel to the standard PowerShell cmdlets which use them.

What are these Common Parameters? 

• -Debug
• -ErrorAction
• -ErrorVariable
• -OutBuffer
• -OutVariable
• -Verbose
• -WarningAction
• -WarningVariable

You can find out the basic functionality of each of these by running:

PowerShell Get-Help about_CommonParameters

But, how do you add them into your own script? It is actually pretty easy. Just include the following line in your script or function as the first executable line (you can only have comments preceding this):

[CmdletBinding()]

You can now use these Common Parameters with your script.

To demonstrate the regular Common Parameters, I’ll show examples with the two you are most likely to start with: the -Debug and -Verbose parameters. If you check the help, you see that both are basically a switch (true/false), but you can explicitly specify $true or $false as the value (e.g. -Verbose:$true). If you want to use Write-Verbose commands in your script, but only when needed, then by using the CmdletBinding attribute, you can pass the -Verbose parameter when calling your script and the Write-Verbose statements will display.  Consider the following test script (saved as Test-Parm.ps1):

[CmdletBinding()]
Param ()
Write-Host "Begin Testing Common Parameters" -ForeGround Green
Write-Verbose "Verbose Parm Used"
Write-Host "End Testing Common Parameters" -ForeGround Green

Execute the script as follows without any parameters:

Powershell .\Test-Parm.ps1 

You’ll just see the two output lines from the Write-Host statements in green.

Now execute the script with the -Verbose parameter:

You might think that you can just reference this parameter now in your script like $Verbose…. Nope! However, when you use the CmdletBinding attribute, the PowerShell automatic variable $PSCmdlet is set and these common parameters are considered bound parameters.

This is helpful if you want to perform specific settings or actions within your script when one of these common parameters is used as shown. For example, the default behavior for Write-Debug is to prompt the user for the action to take as shown here:

You can use the following syntax, however, to test if the -Debug parameter was passed and change the $DebugPreference variable to “Continue” in order for your script to automatically continue processing whenever a Write-Debug statement is encountered.

If ($PSCmdlet.MyInvocation.BoundParameters["Debug"].IsPresent) 
{
     $DebugPreference="Continue"
     Write-Debug "Debug Output activated"
}
Else 
{
     $DebugPreference="SilentlyContinue"
}

The IsPresent property actually evaluates to true if either syntax is used: -Debug or -Debug:$true.

If -Debug:$false is the parameter or the -Debug parameter is not supplied, then IsPresent will evaluate as false.

Consider the following script (saved as Test-Parm.ps1) and note the execution examples shown following it.

[CmdletBinding()]
Param ()
Write-Host "Begin Testing Common Parameters" -ForeGroundColor Green
Write-Verbose "The -Verbose parameter was provided" 
If ($PSCmdlet.MyInvocation.BoundParameters["Debug"].IsPresent) 
{
     $DebugPreference="Continue"
     Write-Debug "Debug Output activated"
}
Else 
{
     $DebugPreference="SilentlyContinue"
}
Write-Debug "This script was called with the -Debug parameter." 
Write-Host "End Testing Common Parameters" -ForeGroundColor Green

Hopefully this tip will help you to incorporate these features into your next PowerShell script.