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 方法,提示使用者根據使用者叫用命令的方式確認作業。