The common parameters are a set of cmdlet parameters that you can use with any cmdlet. They're implemented by PowerShell, not by the cmdlet developer, and so they are automatically available to any cmdlet.
The 11 common parameters with aliases in (parentheses) and with default values underlined, in most cases the default can be changed by setting a preference variable.
| Parameter | Description |
|---|---|
| -Debug (-db) |
Provide programming-level information about the operation [boolean] $true (-Debug:$true). Has the same effect as -Debug. By default, debugging messages aren’t displayed because the value of the $DebugPreference variable is SilentlyContinue. In interactive mode, the Debug parameter overrides the value of the $DebugPreference variable for the current command, setting the value of $DebugPreference to Inquire. In non-interactive mode, the Debug parameter overrides the value of the $DebugPreference variable for the current command, setting the value of $DebugPreference to Continue. Used by: Write-Debug |
| -ErrorAction (-ea) |
Control command behaviour when an error occurs [Enum] Valid values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend, Break. Or the Enumeration values: 0, 1, 2, 3, 4, 5, 6 e.g. -EA SilentlyContinue will supress errors from being printed to stderr. The -SilentlyContinue option will cause any Throw statement to be completely ignored. This can be mitigated by using Try/Catch or by adding a trap {} statement to trap the error. [ Set a default with the optional Preference Variable $ErrorActionPreference = Continue ] Used by: Write-Error |
| -ErrorVariable [+]variable_name (-ev) |
Name of variable [string] If the variable name is prefixed with a + then the new information will be appended to the variable. |
| -InformationAction (-infa) |
Override the value of the $InformationPreference preference variable. Valid values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend, Break [ Set a default with the optional Preference Variable $InformationPreference = SilentlyContinue ] Used by: Write-Information |
| -InformationVariable [+]variable_name (-iv) |
Store into a variable a string that you specify with Write-Information.
PowerShell 5.0+ If the variable name is prefixed with a + then the new information will be appended to the variable. |
| -OutBuffer (-ob) |
The number of objects to buffer before calling the next cmdlet in the pipeline.[Int32] |
| -OutVariable [+]variable_name (-ov) |
Name of variable in which to place output objects [string] To append to the variable content, instead of replacing any message that might already be stored there, type a plus sign (+) before the variable name. -OutVariable +myvar |
| -PipelineVariable (-pv) |
Stores the value of the current pipeline element as a variable, for any named command as it flows through the pipeline. Valid values are strings, the same as for any variable names. |
| -Verbose (-vb) |
Provide detailed information about the operation [boolean] -Verbose:$true which can also be given as just -Verbose. or -Verbose:$false [ Set a default with the optional Preference Variable $VerbosePreference = $True ] Used by: Write-Verbose |
| -WarningAction (-wa) |
Determines how the cmdlet responds to a warning from the command. This parameter works only when the command generates a warning message.
For example when a command contains the Write-Warning cmdlet. Valid values: Break, Continue, SilentlyContinue, Inquire, Stop [ Set a default with the optional Preference Variable $WarningPreference = Continue ] -WarningAction:break Enter the debugger when a warning occurs. -WarningAction:Continue Display the warning messages and continues executing the command. Continue is the default. -WarningAction:SilentlyContinue Suppress the warning message and continue executing the command. -WarningAction:Inquire Display the warning message and prompts you for confirmation before continuing execution. This value is rarely used. -WarningAction:Stop Display the warning message and stop executing the command. Used by: Write-Warning |
| -WarningVariable [+]variable_name (-wv) |
Stores warnings about the command in the specified variable. (wv) All generated warnings are saved in the variable even if the warnings are not displayed to the user. To append the warnings to the variable content, instead of replacing any warnings that might already be stored there, type a plus sign (+) before the variable name. -WarningVariable +myvar |
An Error Variable can be useful for logging errors as part of a pipeline process i.e. when only a few out of many items may fail:
some-pscmdlet | ForEach-Object {
another-pscmdlet -options blah -ErrorVariable ErrFlag
if ($ErrFlag) { Echo "$_.name failed" }
}
In addition to the common parameters, many cmdlets offer risk mitigation parameters. Cmdlets that involve risk to the system or to user data usually offer these two parameters:
Parameter Description -Confirm
(-cf)Prompt the user for permission before performing any action that modifies the system.[boolean] (cf) -Confirm:$false or -Confirm:$true
[ Set a default with the optional Preference Variable $ConfirmPreference = $true ]-WhatIf
(-wi)Explain what will happen if the command is executed, without actually executing the command.[boolean] (wi) -whatif:$false or -whatif:$true [ Set a default with the optional Preference Variable $WhatIfPreference = 0 ] The -confirm parameter allows dropping into the runtime command line while running a PowerShell scriptCmdlet:
The confirmation prompt is [Y] Yes [A] All [N] No [L] No to all [S] Suspend
choosing S will drop you at the command prompt where you can echo variables, make changes etc before typing EXIT to resume running the scriptCmdlet.
Other than where stated above, none of the common parameters have a defined default value, so they will evaluate as FALSE.
You can set a default value, for the duration of a script or a session using a Preference Variable, for example you could set the value of the WhatIf preference to TRUE and this will affect every subsequent cmdlet called:
PS C:\demo\> $WhatIfPreference=$true
PS C:\demo\> New-Item 'Testing'
What if: Performing the operation "create File" on target "Destination: C:\demo\Testing"Alternatively the $PSDefaultParameterValues preference variable lets you specify custom default values for just one specific cmdlet or advanced function, see Help about_Parameters_Default_Values for more.
Any Preference Variable values that you set will be specific to the current PowerShell session. To make variables effective in all PowerShell sessions, add them to your PowerShell profile.
The -passthru parameter is not a common parameter but is present on a large number of cmdlets. It allows outputting an object when the cmdlet would not do so by default.
e.g. Start-Process, Stop-Service, Stop-Job, do not by default, return an object to the pipeline they just complete the action and return nothing.
If you start a new process using Start-Process and want the script to later close that process, it can be useful to save the process object with -Passthru and then manipulate that object later on:
$processObject = Start-Process notepad.exe -PassThru
# other code here
Stop-Process -InputObject $processObject
Some common parameters will have no effect in some cmdlets, this does not raise an error.
Delete a file and capture any errors in a variable:
PS C:\> Remove-Item $somefile -ErrorVariable somevariable
Notice that the error variable is not prefixed with a $ here, using $somevariable will not work.
If the ErrorVariable name is prefixed with a + then PowerShell will ADD the errors to that variable:
PS C:\> Remove-Item $somefile -ErrorVariable +somevariable
PS C:\> $somevariable.count
“Friendship is born at that moment when one person says to another, What! You, too? I thought I was the only one” ~ C. S. Lewis
Preference variables - Verbosity, Confirmations, ErrorAction, $Debug
Parameters - Command Line Parameters param() and $args[]
Get-Help - Open the help file, list parameters for a cmdlet.