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 [+]<變數-名稱>

        將命令的相關警告儲存在指定變數中。

        若要將警告附加到變數內容，請在變數名稱之前輸入加號 (+)，而不要取代可
        能已儲存在其中的任何警告。

        例如，下列命令會建立 $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 [+]<變數-名稱>

        將命令的相關錯誤訊息儲存在指定的變數及 $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 [+]<變數-名稱>

        將來自命令的輸出物件儲存在指定的變數中，然後在命令列加以顯示。

        若要將輸出新增到變數，請在變數名稱之前輸入加號 (+)，而不要取代可能已儲
        存在其中的任何輸出。

        例如，下列命令會建立 $out 變數，然後在其中儲存處理程序物件：

            get-process powershell -OutVariable out

        下列命令會將處理程序物件新增到 $out 變數：

            get-process iexplore -OutVariable +out

        下列命令會顯示 $out 變數的內容：

            $out 


    -OutBuffer <Int32>

        決定要在緩衝區中累積多少物件後，才透過管線進行傳送。如果省略此參數，就
        會在產生物件時加以傳送。
        這個資源管理參數是針對進階使用者而設計。
        使用此參數時，在所產生的物件數目未達到 OutBuffer + 1 之前，
        Windows PowerShell 都不會呼叫管線中的下一個 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：在 "C:\ps-test\date.csv" 目標上執行 "Remove File" 作業。

        
    -Confirm[:{$true | $false}]
        在執行命令前先提示確認。

        Confirm 參數會覆寫目前命令的 $ConfirmPreference 變數值。預設值為 High。
        如需詳細資訊，請輸入下列命令：

            get-help about_preference_variables 

        有效值包括：

            $true (-WhatIf:$true)：其作用與 -Confirm 相同。

            $false(-Confirm:$false)：抑制自動確認作業，此作業會發生在當
                                     $ConfirmPreference 的值小於或等於
                                     Cmdlet 的估計風險時。

        例如，下列命令會將 Confirm 參數搭配 Remove-Item 命令使用。在移除項目之
        前，Windows PowerShell 會列出它所執行的作業及受其作用的項目，並要求核
        准。

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

        此命令會產生下列輸出：

            確認
            確定要執行此動作?
            在 " C:\ps-test\tmp1.txt 目標上執行「移除檔案」作業：[Y] 是、
            [A] 全部皆是、[N] 否、[L] 全部皆否、[S] 暫停、[?] 說明
            (預設為 "Y")。


請參閱
    about_Preference_Variables
    Write-Debug
    Write-Warning
    Write-Error
    Write-Verbose