Share via


about_CommonParameters

Applies To: Windows PowerShell 2.0

TOPIC
    about_CommonParameters

SHORT DESCRIPTION
    Describes the parameters that can be used with any cmdlet.


LONG 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


    For more information about preference variables, type:

  
       help about_preference_variables


  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 generates
        a 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.

        NOTE: The WarningAction parameter does not override the value of
              the $WarningAction preference variable when the parameter
              is used in a command to run a script or function.              



    -WarningVariable [+]<variable-name>

        Stores warnings about the command in the specified variable. 

        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. 

        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.

        NOTE: The WarningVariable parameter does not capture warnings from
              nested calls in functions or scripts. 


    -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 non-terminating error, such as those from 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"):
        

        The Confirm response options are as follows:

            Yes (Y)         Perform the action.
            Yes to All (A)  Perform all actions and suppress subsequent
                            Confirm queries for this command.
            No (N):         Do not perform the action.
            No to All (L):  Do not perform any actions and suppress subsequent
                            Confirm queries for this command.
            Suspend (S):    Pause the command and create a temporary session.
            Help (?)        Display help for these options.

        
        The Suspend option places the command on hold and creates a temporary nested
        session in which you can work until you're ready to choose a Confirm option. 
        The command prompt for the nested session has two extra carets (>>) to indicate
        that it's a child operation of the original parent command. You can run commands
        and scripts in the nested session. To end the nested session and return to the
        Confirm options for the original command, type "exit".

        In the following example, the Suspend option (S) is used to halt a command
        temporarily while the user checks the help for a command parameter. After
        obtaining the needed information, the user types "exit" to end the nested prompt
        and then selects the Yes (y) response to the Confirm query.

            PS C:\ps-test> new-item -itemtype file -name test.txt -confirm

            Confirm
            Are you sure you want to perform this action?
            Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
            [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): s

            PS C:\ps-test>>> get-help new-item -parameter itemtype

            -ItemType <string>
                Specifies the provider-specified type of the new item.

                Required?                    false
                Position?                    named
                Default value
                Accept pipeline input?       true (ByPropertyName)
                Accept wildcard characters?  false


            PS C:\ps-test>>> exit

            Confirm
            Are you sure you want to perform this action?
            Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
            [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): y


                Directory: C:\ps-test
            

            Mode                LastWriteTime     Length Name
            ----                -------------     ------ ----
            -a---         8/27/2010   2:41 PM          0 test.txt

        



SEE ALSO
    about_Preference_Variables
    Write-Debug
    Write-Warning
    Write-Error
    Write-Verbose