Understanding PowerShell’s Common Parameters

PowerShell’s common parameters are a set of parameters that are automatically available to all cmdlets and advanced functions. These parameters provide a consistent way to control the behavior of cmdlets and functions, making it easier to manage and debug scripts. In this post, we will look at the most commonly used common parameters and how to use them.

What are Common Parameters?

Common parameters are a predefined set of parameters that are included in every cmdlet and advanced function. They are automatically added by the PowerShell engine and do not need to be explicitly defined in your scripts. These parameters allow you to control various aspects of cmdlet execution, such as (but not limited to) output formatting, error handling, and debugging.

List of Common Parameters

Here are some (but not all) of the (most commonly used) common parameters:

-Verbose

Provides detailed information about the operation being performed.

-Debug

Provides debugging information.

-ErrorAction

Specifies how the cmdlet should respond to an error.

-WarningAction

Specifies how the cmdlet should respond to a warning.

-InformationAction

Specifies how the cmdlet should respond to an information event.

-ErrorVariable

Specifies a variable to store error messages.

-WarningVariable

Specifies a variable to store warning messages.

-InformationVariable

Specifies a variable to store information messages.

-OutVariable

Specifies a variable to store output data.

-OutBuffer

Specifies the number of objects to buffer before calling the next cmdlet in the pipeline.

-PipelineVariable

Specifies a variable to store the current pipeline object.

Using Common Parameters

Let’s look at some examples of how to use common parameters in your PowerShell scripts.

Verbose

The -Verbose parameter provides detailed information about the operation being performed. This can be useful for troubleshooting and understanding the behavior of your scripts.

Get-Process -Name "powershell" -Verbose

ErrorAction

The -ErrorAction parameter specifies how the cmdlet should respond to an error. The possible values are Continue, Stop, SilentlyContinue, Inquire, and Ignore.

Get-Item "C:\NonExistentFile.txt" -ErrorAction SilentlyContinue

ErrorVariable

The -ErrorVariable parameter specifies a variable to store error messages. This allows you to capture and handle errors more effectively.

Get-Item "C:\NonExistentFile.txt" -ErrorVariable myError
if ($myError) {
    Write-Host "An error occurred: $($myError[0].Exception.Message)"
}

Using common parameters in your own functions

So how can you use these common parameters in your own functions? you have to add [CmdletBinding()] to your function like this:

Function Show-Example {
    [CmdletBinding()]
    Param(
        [Parameter(Mandatory=$true)]
        $ParameterOne
    )

    Write-Verbose "The value of ParameterOne is $ParameterOne"
    Write-Output "$ParameterOne"
}

Adding this will make your function an advanced function.

Try running the above example with the -Verbose parameter like this:

Show-Example -ParameterOne "Example" -Verbose

The result should look like this:

Show-Example -ParameterOne "Example" -Verbose
VERBOSE: The value of ParameterOne is Example
Example

Note that ‘common’ parameters like -WhatIf and -Confirm are not available by just adding [CmdletBinding()] to your function. Those (and other options) will be discussed in a different post as they require more understanding.

Preference variables

With the use of preference variables you can change the behaviour of the common parameters. for example you can use the $ErrorActionPreference variable to change how the -ErrorAction parameter works when your script encounters an error.

Say you want to silence the error output for your script, you can do this as shown below.

# Lines at the start of the script
$ErrActPref = $ErrorActionPreference
$ErrorActionPreference = "SilentlyContinue"

Get-Item "C:\NonExistentFile.txt"

# last line of the script (but before returning any output)
$ErrorActionPreference = $ErrActPref

This will cause all cmdlets between the 2nd and the last line to not show errors and continue running the script. By storing the $ErrorActionPreference variable in a different variable at the top of the script we set the new value and safely restore the old value at the end of the script. If we do not restore the value any action after this script will also use the value we set here (in this case SilentlyContinue).

The same can be done for the other common parameters, more info can be found in the official documentation: about_Preference_Variables

Conclusion

PowerShell’s common parameters provide consistent way to control the behavior of cmdlets and functions. By understanding and using these parameters, you can create more robust and maintainable scripts. Whether you need detailed output, error handling, or debugging information, common parameters have you covered.

For more information on common parameters, refer to the official documentation: about_CommonParameters.