Tags


COMMON PARAMETERS

DESCRIPTION

The common parameters are a set of cmdlet parameters that you can  use with any cmdlet. They are implemented by Windows PowerShell, not by the cmdlet developer, and they are automatically available to any cmdlet.

You can use the common parameters with any cmdlet, but they might not have an effect on all cmdlets. For example, if a cmdlet does not   generate any verbose output, using the Verbose common parameter has no effect.

Several common parameters override system defaults or preferences that you set by using the Windows PowerShell preference variables. Unlike the preference variables, the common parameters affect only the commands in which they are used.

In addition to the common parameters, many cmdlets offer the WhatIf and Confirm risk mitigation parameters. Cmdlets that involve risk to the system or to user data usually offer these parameters.

    The common parameters are:

       -Verbose

       -Debug

       -WarningAction

       -WarningVariable

       -ErrorAction

       -ErrorVariable

       -OutVariable

       -OutBuffer  

    The risk mitigation parameters are:

       -WhatIf

       -Confirm

Common Parameter Descriptions      

-Verbose[:{$true | $false}]

Displays detailed information about the operation performed by the command. This information resembles the information in a trace or in a transaction log. This parameter works only when the command generatesa verbose message. For example, this parameter works when a command contains the Write-Verbose cmdlet.

The Verbose parameter overrides the value of the $VerbosePreference variable for the current command. Because the default value of the       $VerbosePreference variable is SilentlyContinue, verbose messages are not displayed by default.

Valid values:

$true (-Verbose:$true) has the same effect as -Verbose.

$false (-Verbose:$false) suppresses the display of verbose

messages. Use this parameter when the value of $VerbosePreference is not SilentlyContinue (the default).

-Debug[:{$true | $false}]

Displays programmer-level detail about the operation performed by the command. This parameter works only when the command generates      a debugging message. For example, this parameter works when a command contains the Write-Debug cmdlet.

The Debug parameter overrides the value of the $DebugPreference variable for the current command. Because the default value of the     $DebugPreference variable is SilentlyContinue, debugging messages are not displayed by default.

 Valid values:

$true (-Debug:$true). Has the same effect as -Debug.

$false (-Debug:$false). Suppresses the display of debugging

messages when the value of the $DebugPreference is not

SilentlyContinue (the default).

-WarningAction[:{SilentlyContinue | Continue | Inquire | Stop}]  

Determines how the cmdlet responds to a warning from the command. “Continue” is the default value. This parameter works only when the command generates a warning message. For example, this parameter works when a command contains the Write-Warning cmdlet.  The WarningAction parameter overrides the value of the $WarningPreference variable for the current command. Because the default value of the $WarningPreference variable is Continue, warnings are displayed and execution continues unless you use the WarningAction parameter.

Valid Values:

SilentlyContinue. Suppresses the warning message and continues executing the command.

Continue. Displays the warning message and continues executing the command. “Continue” is the default value.

Inquire. Displays the warning message and prompts you for confirmation before continuing execution. This value is rarely used.

Stop. Displays the warning message and stops executing the command.

 -WarningVariable [+]<variable-name>

Stores warnings about the command in the specified variable.  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.

For example, the following command creates the $a variable and then stores any warnings in it: get-process -id 6 -WarningVariable a  The following command adds any warnings to the $a variable: get-process -id 2 -WarningVariable +a

The following command displays the contents of $a: $a

You can use this parameter to create a variable that contains only warnings from specific commands. You can use array notation, such as        $a[0] or $warning[1,2] to refer to specific warnings stored in the variable.

-ErrorAction[:{SilentlyContinue | Continue | Inquire | Stop)]  

Determines how the cmdlet responds to a non-terminating error from the command. This parameter works only when the command generates    a debugging message. For example, this parameters works when a command contains the Write-Error cmdlet. The ErrorAction parameter overrides the value of the $ErrorActionPreference variable for the current command.

Because the default value of the $ErrorActionPreference variable is Continue, error messages are displayed and execution continues unless you use the ErrorAction parameter. The ErrorAction parameter has no effect on terminating errors (such as missing data, parameters that are not valid, or insufficient permissions) that prevent a command from completing successfully.

 Valid values:

SilentlyContinue. Suppresses the error message and continues  executing the command.

Continue. Displays the error message and continues executing  the command. “Continue” is the default value.

Inquire. Displays the error message and prompts you for confirmation before continuing execution. This value is rarely  used.

Stop. Displays the error message and stops executing the command.

 –ErrorVariable [+]<variable-name>

Stores error messages about the command in the specified variable and in the $Error automatic variable. For more information, type the following command:

get-help about_automatic_variables

By default, new error messages overwrite error messages that are already stored in the variable. To append the error message to the variable content, type  a plus sign (+) before the variable name.

For example, the following command creates the $a variable and then stores any errors in it:

get-process -id 6 -ErrorVariable a

The following command adds any error messages to the $a variable:  get-process -id 2 -ErrorVariable +a

The following command displays the contents of $a: $a

You can use this parameter to create a variable that contains only error messages from specific commands. The $Error automatic variable contains error messages from all the commands in the session.

You can use array notation, such as $a[0] or $error[1,2] to refer to specific errors stored in the variables.

-OutVariable [+]<variable-name>

Stores output objects from the command in the specified variable and displays it at the command line.  To add the output to the variable, instead of replacing any output that might already be stored there, type a plus sign (+) before the variable name.

For example, the following command creates the $out variable and  stores the process object in it:

get-process powershell -OutVariable out

The following command adds the process object to the $out variable: get-process iexplore -OutVariable +out

The following command displays the contents of the $out variable:  $out

-OutBuffer <Int32>

Determines the number of objects to accumulate in a buffer before any objects are sent through the pipeline. If you omit this parameter,         objects are sent as they are generated. This resource management parameter is designed for advanced users.  When you use this parameter, Windows PowerShell does not call the next cmdlet in the pipeline until the number of objects generated  equals OutBuffer + 1. Thereafter, it sends all objects as they are generated.

Risk Management Parameter Descriptions

-WhatIf[:{$true | $false}]

Displays a message that describes the effect of the command, instead of executing the command.

The WhatIf parameter overrides the value of the $WhatIfPreference variable for the current command. Because the default value of the     $WhatIfPreference variable is 0 (disabled), WhatIf behavior is not performed without the WhatIf parameter. For more information, type  the following command:

get-help about_preference_variables

Valid values:

$true (-WhatIf:$true). Has the same effect as -WhatIf.

$false (-WhatIf:$false). Suppresses the automatic WhatIf behavior that results when the value of the $WhatIfPreference variable is 1.

For example, the following command uses the WhatIf parameter in a Remove-Item command:

PS> remove-item date.csv -whatif Instead of removing the item, Windows PowerShell lists the operations it would perform and the items that would be affected. This command produces the following output:

What if: Performing operation “Remove File” on  Target “C:\ps-test\date.csv”.

-Confirm[:{$true | $false}]

Prompts you for confirmation before executing the command. The Confirm parameter overrides the value of the $ConfirmPreference variable for the current command. The default value is High. For more information, type the following command:

get-help about_preference_variables   Valid values:

$true (-WhatIf:$true). Has the same effect as -Confirm.

$false(-Confirm:$false). Suppresses automatic confirmation, which occurs when the value of $ConfirmPreference is less than or equal to the estimated risk of the cmdlet.

For example, the following command uses the Confirm parameter with a Remove-Item command. Before removing the item, Windows PowerShell lists the operations it would perform and the items that would be affected, and asks for approval.

PS C:\ps-test> remove-item tmp*.txt -confirm

This command produces the following output:

Confirm Are you sure you want to perform this action?

Performing operation “Remove File” on Target ” C:\ps-test\tmp1.txt

[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend

[?] Help (default is “Y”):

 

Enjoy!!

 

Advertisements