Cmdlet.ShouldProcess Method (String)

Requests confirmation from the user before an operation is performed. This method sends the name of the resource to be changed so that the user can decide if the operation should continue.


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

'Usage
Dim instance As Cmdlet
Dim target As String
Dim returnValue As Boolean

returnValue = instance.ShouldProcess(target)

public:
bool ShouldProcess (
	String^ target
)
public boolean ShouldProcess (
	String target
)
public function ShouldProcess (
	target : String
) : boolean

Parameters

target

The name of the resource to be changed. To see how the resource is displayed in the confirmation message, see the following code examples.

Return Value

A Boolean value that indicates true if the user wants to perform the operation. A returned value of false indicates that the operation should not be performed.

In the following code example, the ShouldProcess(String) call specifies the resource that the command will act upon. In the confirmation message that is displayed to the user, Windows PowerShell adds the name of the command and the call specifies the resource.

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

This is the message that is returned when the Confirm parameter is specified. In this case, Windows PowerShell adds the name of the cmdlet as the operation to be performed.

Confirm
Are you sure you want to perform this action?
Performing operation "Test-RequestConfirmationTemplate1" on Target "ShouldProcess target".
[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"):

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.

Also, if the pipeline was terminated because of ActionPreference.Stop or ActionPreference.Inquire, the command failure will ultimately be ActionPreferenceStopException.

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 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 the ShouldProcess method, the command making the call must also indicate that it supports these calls.

  1. For cmdlets, set the SupportsShouldProcess parameter of its Cmdlet attribute to true. For more information about the syntax and declaration parameter of this attribute, see CmdletAttribute Declaration.

  2. For functions, set the SupportsShouldProcess parameter of its CmdletBinding attribute to true.

  3. For providers, set the SupportsShouldProcess parameter of its CmdletProvider attribute to true.

This method can be called only from within the 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 Writing a Windows PowerShell Cmdlet.


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