向 Cmdlet 要求確認

發行項
03/25/2025

Cmdlet 應該在即將變更 Windows PowerShell 環境外部的系統時要求確認。例如，如果 Cmdlet 即將新增用戶帳戶或停止進程，Cmdlet 應該要求使用者確認，才能繼續進行。相反地，如果 Cmdlet 即將變更 Windows PowerShell 變數，Cmdlet 就不需要確認。

若要提出確認要求，Cmdlet 必須指出它支持確認要求，而且必須呼叫 System.Management.Automation.Cmdlet.ShouldProcess，並 System.Management.Automation.Cmdlet.ShouldContinue （選擇性）方法來顯示確認要求訊息。

支援確認要求

若要支援確認要求，Cmdlet 必須將 Cmdlet 屬性的 SupportsShouldProcess 參數設定為 true。這會啟用 Windows PowerShell 所提供的 Confirm 和 WhatIf Cmdlet 參數。 Confirm 參數可讓使用者控制是否顯示確認要求。 WhatIf 參數可讓用戶判斷 Cmdlet 是否應該顯示訊息或執行其動作。請勿手動將 Confirm 和 WhatIf 參數新增至 Cmdlet。

下列範例顯示支援確認要求的 Cmdlet 屬性宣告。

[Cmdlet(VerbsDiagnostic.Test, "RequestConfirmationTemplate1",
        SupportsShouldProcess = true)]

呼叫確認要求方法

在 Cmdlet 程式代碼中，在執行變更系統的作業之前，先呼叫 System.Management.Automation.Cmdlet.ShouldProcess 方法。設計 Cmdlet，讓呼叫傳回 false值時，不會執行作業，而且 Cmdlet 會處理下一個作業。

呼叫 ShouldContinue 方法

大部分 Cmdlet 只會使用 System.Management.Automation.Cmdlet.ShouldProcess 方法來要求確認。不過，在某些情況下可能需要額外的確認。在這些情況下，請以呼叫 System.Management.Automation.Cmdlet.ShouldContinue 方法來補充 System.Management.Automation.Cmdlet.ShouldProcess 呼叫。這可讓 Cmdlet 或提供者對確認提示的所有 回應，更精細地控制 [是] 的範圍。

如果 Cmdlet 呼叫 System.Management.Automation.Cmdlet.ShouldContinue 方法，Cmdlet 也必須提供 Force 參數。如果使用者在叫用 Cmdlet 時指定 Force，Cmdlet 仍應呼叫 System.Management.Automation.Cmdlet.ShouldProcess，但應該略過呼叫 System.Management.Automation.Cmdlet.ShouldContinue。

System.Management.Automation.Cmdlet.ShouldContinue 從無法提示使用者的非互動式環境呼叫時，會擲回例外狀況。新增 Force 參數可確保命令在非互動式環境中叫用時仍可執行。

下列範例示範如何呼叫 System.Management.Automation.Cmdlet.ShouldProcess 和 System.Management.Automation.Cmdlet.ShouldContinue。

if (ShouldProcess (...) )
{
  if (Force || ShouldContinue(...))
  {
     // Add code that performs the operation.
  }
}

System.Management.Automation.Cmdlet.ShouldProcess 呼叫的行為可能會因叫用 Cmdlet 的環境而有所不同。使用先前的指導方針可協助確保不論主機環境為何，Cmdlet 都會與其他 Cmdlet 一致運作。

如需呼叫 System.Management.Automation.Cmdlet.ShouldProcess 方法的範例，請參閱如何要求確認。

指定影響等級

當您建立 Cmdlet 時，請指定變更的影響層級（嚴重性）。若要這樣做，請將 Cmdlet 屬性的 ConfirmImpact 參數值設定為 High、Medium 或 Low。只有當您也指定 cmdlet 的 SupportsShouldProcess 參數時，才可以指定 ConfirmImpact 的值。

對於大部分的 Cmdlet，您不需要明確指定 ConfirmImpact。請改用參數的預設設定，也就是 Medium。如果您將 [ConfirmImpact] 設定為 [高]，則預設會確認作業。針對高度干擾性動作保留此設定，例如重新格式化硬碟磁碟區。

呼叫非確認方法

如果 Cmdlet 或提供者必須傳送訊息，但不要求確認，它可以呼叫下列三種方法。請避免使用 System.Management.Automation.Cmdlet.WriteObject 方法來傳送這些類型的訊息，因為 System.Management.Automation.Cmdlet.WriteObject 輸出與您的 Cmdlet 或提供者的一般輸出交織在一起，使得腳本撰寫變得困難。

若要提醒用戶並繼續作，Cmdlet 或提供者可以呼叫 System.Management.Automation.Cmdlet.WriteWarning 方法。
若要提供使用者可以使用 Verbose 參數擷取的其他資訊，Cmdlet 或提供者可以呼叫 System.Management.Automation.Cmdlet.WriteVerbose 方法。
若要為其他開發人員或產品支援提供偵錯層級的詳細數據，Cmdlet 或提供者可以呼叫 System.Management.Automation.Cmdlet.WriteDebug 方法。使用者可以使用 Debug 參數來擷取此資訊。

Cmdlet 和提供者會先呼叫下列方法來要求確認，然後再嘗試執行在 Windows PowerShell 外部變更系統的作業：

他們藉由呼叫 System.Management.Automation.Cmdlet.ShouldProcess 方法，提示使用者根據使用者叫用命令的方式確認作業。

另請參閱

撰寫 Windows PowerShell Cmdlet

共用方式為