Cmdlet.ShouldProcess Method (String, String, String, ShouldProcessReason)
Updated: April 27, 2016
Applies To: Windows PowerShell
Requests confirmation from the user before an operation is performed. This method sends a detailed description of the resource to be changed and the operation to be performed to the user for confirmation before the operation is performed.
Assembly: System.Management.Automation (in System.Management.Automation.dll)
public bool ShouldProcess( string verboseDescription, string verboseWarning, string caption, out ShouldProcessReason shouldProcessReason )
The operation to be performed. This is what will be displayed to the user for ActionPreference.Continue.
Query that confirms whether the operation should be performed. This query is what will be displayed to the user for ActionPreference.Inquire.
Caption of the window that displays the query. Not all hosts display this window.
The pipeline is stopped. The pipeline was terminated either before the call was made or while the call was in progress. By default, the cmdlet should allow the caller of the processing record method to catch this exception.
Also, if the pipeline was terminated because of ActionPreference.Stop or ActionPreference.Inquire, the command failure will ultimately be ActionPreferenceStopException.
The call cannot be completed at this time or cannot be completed from this thread. For more information, see the following Remarks section.
This method allows the cmdlet to prompt the user for a confirmation request, and to detect the special circumstances that existed when the call was made. The shouldProcessReason parameter returns the following values.
The WhatIf parameter was specified on the command line so False was returned by the call.
YesToAll was selected and True was returned by the call.
NoToAll was selected and False was returned by the call.
The confirmImpact variable was not set high enough to prompt the user so True was returned by the call.
The confirmImpact variable was set high enough to prompt the user and True or False was returned by the call.
However, it is unusual that the cmdlet needs to know the reason why False was returned, so most cmdlets should use Cmdlet.ShouldProcess(String, String, String). For more information about confirmation requests, including information about how confirmation requests are affected by the $ConfirmPreference shell variable, see Requesting Confirmation.
This method can be called only from within the cmdlet input processing methods (BeginProcessing, ProcessRecord, and EndProcessing) and only from that thread. If this call is made from outside these methods or from another thread, an InvalidOperationException exception is thrown.
When this method is called, the runspace implements any command-line settings or preference variables when it determines what should be returned or what is displayed to the user.
For more information about cmdlets, see Windows PowerShell Cmdlets.