Cmdlet.ShouldProcess Method (String, String, String, ShouldProcessReason)
Assembly: System.Management.Automation (in System.Management.Automation.dll)
'Declaration Public Function ShouldProcess ( _ verboseDescription As String, _ verboseWarning As String, _ caption As String, _ <OutAttribute> ByRef shouldProcessReason As ShouldProcessReason _ ) As Boolean
public boolean ShouldProcess ( String verboseDescription, String verboseWarning, String caption, /** @attribute OutAttribute() */ /** @ref */ 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.
A ShouldProcessReason constant that specifies any special circumstances that existed when the call was made, such as the WhatIf parameter was specified at the command line.
Return ValueA Boolean value that indicates true if the cmdlet should perform the operation. False indicates the cmdlet should not perform the operation and should process the next record.
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.
To call Cmdlet.ShouldProcess, the cmdlet must also set the SupportsShouldProcess parameter of its CmdletAttribute declaration to True. For more information about the syntax and declaration parameter of this attribute, see CmdletAttribute Declaration.
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.