Cmdlet.ShouldProcess Method (String, String, String)

Requests confirmation from the user before an operation is performed. This method sends a description of the operation to be performed, a warning message that can include query, and a caption for the warning message.


Namespace: System.Management.Automation
Assembly: System.Management.Automation (in System.Management.Automation.dll)

'Usage
Dim instance As Cmdlet
Dim verboseDescription As String
Dim verboseWarning As String
Dim caption As String
Dim returnValue As Boolean

returnValue = instance.ShouldProcess(verboseDescription, verboseWarning, caption)

public bool ShouldProcess (
	string verboseDescription,
	string verboseWarning,
	string caption
)
public boolean ShouldProcess (
	String verboseDescription, 
	String verboseWarning, 
	String caption
)
public function ShouldProcess (
	verboseDescription : String, 
	verboseWarning : String, 
	caption : String
) : boolean

Parameters

verboseDescription

A description of the operation to be performed. This description is displayed to the user when a Warning message is not specified, when the WhatIf parameter is used when the command is called, or when the ErrorActionPreference variable is set to Continue. To see how the warning is displayed in the confirmation message, see the following code examples.

verboseWarning

A warning message that contains a query asking whether the operation should be performed. This warning message is displayed to the user when the ErrorActionPreference variable is set to Inquire. To see how the warning is displayed in the confirmation message, see the following code examples.

caption

A caption for the warning message. This caption can also displayed in a window that might, or might not, be displayed by specific hosts. To see how the caption is displayed in the confirmation message, see the following code examples.

Return Value

A Boolean value that indicates true whether the cmdlet should perform the action. A return value of false indicates that the action should not be performed.

In the following code example, the ShouldProcess(String,String,String) call specifies a description, warning, and a caption.

protected override void ProcessRecord()
{
  if (ShouldProcess("ShouldProcess description",
                    "ShouldProcess warning",
                    "ShouldProcess caption"))
  {
    if (Force || ShouldContinue("",""))
    {
      // Add code that performs the operation.
    }
  }
}

This is the message that is returned when the Confirm parameter is specified and a warning message has been defined. Notice that with the exception of the possible answers, the cmdlet has full control over what is displayed to the user.

ShouldProcess caption
ShouldProcess warning.
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"):

This is the second message that is returned when the Confirm parameter is specified and the user answers Yes or Yes to All to the first message. In these cases, the call to the ShouldContinue method is made.

Confirm
Continue with this operation?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):

This is the message that is returned when the WhatIf parameter is specified. Notice that in this case the description message is displayed and not the warning message.

What if: ShouldProcess description

Exception typeCondition
PipelineStoppedException

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.

InvalidOperationException

The call cannot be completed at this time or cannot be completed from this thread. For more information, see the following Remarks section.

This variant provides maximum control over the confirmation message that is presented to the user and the warning that is presented to the user if the user is informed of the operation, but not explicitly prompted. This method should be called before the cmdlet makes a change to the system. For more information about confirmation requests, including information about how confirmation requests are affected by the $ConfirmPreference shell variable, see Requesting Confirmation.

To call ShouldProcess, the cmdlet must also set the SupportsShouldProcess parameter of its Cmdlet attribute 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 checks 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.


Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

 

Target Platforms

Windows Developer Preview, Windows Server Developer Preview

Send comments about this topic to Microsoft.
Show:
© 2014 Microsoft