about_Commonparameters

主题
    about_CommonParameters

简短说明
    描述可用于任何 cmdlet 的参数。


详细说明
    通用参数是指可用于任何 cmdlet 的一组 cmdlet 参数。这些参数由 Windows PowerShell 而不是 
    cmdlet 开发人员实现，并自动供所有 cmdlet 使用。


    通用参数可用于任何 cmdlet，但可能不是对所有 cmdlet 都起作用。例如，如果一个 cmdlet 不
    生成任何详细输出，则 Verbose 通用参数不起任何作用。


    有几个通用参数可覆盖您使用 Windows PowerShell 首选变量设置的系统默认值或首选项。与首选
    变量不同，通用参数只影响使用它们的命令。
 
    
    除通用参数外，很多 cmdlet 还提供 WhatIf 和 Confirm 风险缓解参数。给系统或用户数据带来
    风险的 Cmdlet 通常提供这些参数。


    这些通用参数包括：


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

 
    风险缓解参数为：


       -WhatIf
       -Confirm


    有关首选变量的详细信息，请键入：

  
       help about_preference_variables


  通用参数说明       

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

        显示有关由该命令执行的操作的详细信息。此信息类似于跟踪或事务日志中的
        信息。此参数仅在命令生成详细消息时才起作用。例如，此参数在命令中
        包含 Write-Verbose cmdlet 时起作用。
        
        Verbose 参数将覆盖当前命令的 $VerbosePreference 变量的值。$VerbosePreference 
        变量的默认值为 SilentlyContinue，因此在默认情况下不显示详细消息。

        有效值：

            $true (-Verbose:$true) 与 -Verbose 作用相同。

            $false (-Verbose:$false) 禁止显示详细消息。当 $VerbosePreference 的值不
            是 SilentlyContinue（默认值）时使用此参数。 



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

        显示有关由该命令执行的操作的程序员级详细信息。此参数仅在命令生成调试消息时
        才起作用。例如，此参数在命令中包含 Write-Debug cmdlet 时起作用。
    
        Debug 参数将覆盖当前命令的 $DebugPreference 变量的值。$DebugPreference 变量的
        默认值为 SilentlyContinue，因此在默认情况下不显示调试消息。
       
        有效值：

            $true (-Debug:$true)。与 -Debug 作用相同。

            $false (-Debug:$false)。当 $DebugPreference 的值不是 SilentlyContinue
            （默认值）时，禁止显示调试消息。



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

        确定 cmdlet 如何对命令生成的警告做出响应。默认值为“Continue”。此参数
    仅在命令生成警告消息时才起作用。例如，此参数在命令中包含 
        Write-Warning cmdlet 时起作用。

        WarningAction 参数将覆盖当前命令的 $WarningPreference 变量的值。
        $WarningPreference 变量的默认值为 Continue，因此如果不使用 WarningAction 参数，
        则将显示警告并继续执行命令。

         有效值：

            SilentlyContinue。禁止显示警告消息并继续执行命令。

            Continue。显示警告消息并继续执行命令。默认值为"Continue"。
 
            Inquire。显示警告消息并在继续执行前提示您进行确认。此值很少使用。

            Stop。显示警告消息并停止执行命令。



    -WarningVariable [+]<variable-name>

        将与命令有关的警告存储在指定变量中。

        要将警告追加到变量内容而不是替换可能已存储在变量中的任何警告，请在变量名称之前键入加号 (+)。

        例如，以下命令将创建 $a 变量，然后在其中存储所有警告：

            get-process -id 6 -WarningVariable a

        以下命令在 $a 变量中添加所有警告：

            get-process -id 2 -WarningVariable +a

        以下命令显示 $a 的内容：

            $a                                     

        可使用此参数创建一个变量，该变量仅包含来自特定命令的警告。可使用数组表示法（如 $a[0] 
        或 $warning[1,2]）来引用存储在变量中的特定警告。


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

        确定 cmdlet 如何对命令生成的非终止错误做出响应。此参数仅在命令生成调试消息时才起作
        用。例如，此参数在命令中包含 Write-Error cmdlet 时起作用。

        ErrorAction 参数将覆盖当前命令的 $ErrorActionPreference 变量的值。
        $ErrorActionPreference 变量的默认值为 Continue，因此如果不使用 ErrorAction 参
        数，则将显示错误消息并继续执行命令。

        ErrorAction 参数对数据丢失、参数无效或权限不足等终止错误不起作用，这些错误将阻止命令
        成功执行。

        有效值：

            SilentlyContinue。禁止显示错误消息并继续执行命令。

            Continue。显示错误消息并继续执行命令。默认值为"Continue"。
 
            Inquire。显示错误消息并在继续执行前提示您进行确认。此值很少使用。

            Stop。显示错误消息并停止执行命令。

            
    -ErrorVariable [+]<variable-name>

        将与命令有关的错误消息存储在指定变量和 $Error 自动变量中。有关详细信息，
    请键入以下命令：

            get-help about_automatic_variables

        默认情况下，新错误消息将覆盖已存储在变量中的错误消息。要在变量内容中追加错误消息，请在
        变量名称之前键入加号 (+)。

        例如，以下命令将创建 $a 变量，然后在其中存储所有错误：

            get-process -id 6 -ErrorVariable a

        以下命令在 $a 变量中添加所有错误消息：


            get-process -id 2 -ErrorVariable +a

        以下命令显示 $a 的内容：

            $a                                     

        可使用此参数创建一个变量，该变量仅包含来自特定命令的错误消息。$Error 自动变量包含来自
        会话中所有命令的错误消息。
        可使用数组表示法（如 $a[0] 或 $error[1,2]）来引用存储在变量中的特定错误。


    -OutVariable [+]<variable-name>

        将命令的输出对象存储在指定变量中并在命令行进行显示。

        要将输出添加到变量中而不是替换可能已存储在变量中的任何输出，请在变量名称之前键入加号 (+)。

        例如，以下命令将创建 $out 变量，然后在其中存储进程对象：

            get-process powershell -OutVariable out

        以下命令将进程对象添加到 $out 变量：

            get-process iexplore -OutVariable +out

        以下命令显示 $out 变量的内容：

            $out                                         


    -OutBuffer <Int32>

        确定在通过管道发送任何对象之前要在缓冲区中累积的对象数目。如果省略此参数，
    则对象在生成时即被发送。此资源管理参数供高级用户使用。

        当使用此参数时，Windows PowerShell 在生成的对象数目等于 OutBuffer + 1 之前，不
        会调用管道中的下一个 cmdlet。当对象数目达到该值之后，所有对象在生成时即被发送。

        
  风险管理参数说明
         
    -WhatIf[:{$true | $false}]
        显示描述命令效果的消息，而不是执行命令。

        WhatIf 参数将覆盖当前命令的 $WhatIfPreference 变量的值。$WhatIfPreference 变
        量的默认值为 0（禁用），因此在没有 WhatIf 参数时不会执行 WhatIf 行为。有关详细信息，
        请键入以下命令：

            get-help about_preference_variables



        有效值：

            $true (-WhatIf:$true)。与 -WhatIf 作用相同。           
            $false (-WhatIf:$false)。禁止 $WhatIfPreference 变量的值为 1 时的自动 
            WhatIf 行为。

        例如，以下命令在一个 Remove-Item 命令中使用 WhatIf 参数：

            PS> remove-item date.csv -whatif

        Windows PowerShell 列出它要执行的操作以及将影响的项，而不是将项删除。此命令将产生
        以下输出：

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

        
    -Confirm[:{$true | $false}]
        在执行命令之前提示您进行确认。

        Confirm 参数将覆盖当前命令的 $ConfirmPreference 变量的值。默认值为 High。有关详
        细信息，请键入以下命令：

            get-help about_preference_variables 

        有效值：

            $true (-Confirm:$true)。与 -Confirm 作用相同。          

            $false(-Confirm:$false)。禁止在 $ConfirmPreference 的值小于或等于 cmdlet 
            的估计风险时发生的自动确认。

        例如，以下命令在 Remove-Item 命令中使用 Confirm 参数。在删除项之前，Windows 
        PowerShell 会列出它要执行的操作以及将影响的项，并请求批准。

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

        此命令将产生以下输出：

            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"):


另请参阅
    about_Preference_Variables
    Write-Debug
    Write-Warning
    Write-Error
    Write-Verbose