Edit

Requesting Confirmation from Cmdlets

  • Article

Cmdlets should request confirmation when they are about to make a change to the system that is outside of the Windows PowerShell environment. For example, if a cmdlet is about to add a user account or stop a process, the cmdlet should require confirmation from the user before it proceeds. In contrast, if a cmdlet is about to change a Windows PowerShell variable, the cmdlet does not need to require confirmation.

In order to make a confirmation request, the cmdlet must indicate that it supports confirmation requests, and it must call the System.Management.Automation.Cmdlet.ShouldProcess and System.Management.Automation.Cmdlet.ShouldContinue (optional) methods to display a confirmation request message.

Supporting Confirmation Requests

To support confirmation requests, the cmdlet must set the SupportsShouldProcess parameter of the Cmdlet attribute to true. This enables the Confirm and WhatIf cmdlet parameters that are provided by Windows PowerShell. The Confirm parameter allows the user to control whether the confirmation request is displayed. The WhatIf parameter allows the user to determine whether the cmdlet should display a message or perform its action. Do not manually add the Confirm and WhatIf parameters to a cmdlet.

The following example shows a Cmdlet attribute declaration that supports confirmation requests.

[Cmdlet(VerbsDiagnostic.Test, "RequestConfirmationTemplate1",
        SupportsShouldProcess = true)]

Calling the Confirmation request methods

In the cmdlet code, call the System.Management.Automation.Cmdlet.ShouldProcess method before the operation that changes the system is performed. Design the cmdlet so that if the call returns a value of false, the operation is not performed, and the cmdlet processes the next operation.

Calling the ShouldContinue Method

Most cmdlets request confirmation using only the System.Management.Automation.Cmdlet.ShouldProcess method. However, some cases might require additional confirmation. For these cases, supplement the System.Management.Automation.Cmdlet.ShouldProcess call with a call to the System.Management.Automation.Cmdlet.ShouldContinue method. This allows the cmdlet or provider to more finely control the scope of the Yes to all response to the confirmation prompt.

If a cmdlet calls the System.Management.Automation.Cmdlet.ShouldContinue method, the cmdlet must also provide a Force switch parameter. If the user specifies Force when the user invokes the cmdlet, the cmdlet should still call System.Management.Automation.Cmdlet.ShouldProcess, but it should bypass the call to System.Management.Automation.Cmdlet.ShouldContinue.

System.Management.Automation.Cmdlet.ShouldContinue will throw an exception when it is called from a non-interactive environment where the user cannot be prompted. Adding a Force parameter ensures that the command can still be performed when it is invoked in a non-interactive environment.

The following example shows how to call System.Management.Automation.Cmdlet.ShouldProcess and System.Management.Automation.Cmdlet.ShouldContinue.

if (ShouldProcess (...) )
{
  if (Force || ShouldContinue(...))
  {
     // Add code that performs the operation.
  }
}

The behavior of a System.Management.Automation.Cmdlet.ShouldProcess call can vary depending on the environment in which the cmdlet is invoked. Using the previous guidelines will help ensure that the cmdlet behaves consistently with other cmdlets, regardless of the host environment.

For an example of calling the System.Management.Automation.Cmdlet.ShouldProcess method, see How to Request Confirmations.

Specify the Impact Level

When you create the cmdlet, specify the impact level (the severity) of the change. To do this, set the value of the ConfirmImpact parameter of the Cmdlet attribute to High, Medium, or Low. You can specify a value for ConfirmImpact only when you also specify the SupportsShouldProcess parameter for the cmdlet.

For most cmdlets, you do not have to explicitly specify ConfirmImpact. Instead, use the default setting of the parameter, which is Medium. If you set ConfirmImpact to High, the operation will be confirmed by default. Reserve this setting for highly disruptive actions, such as reformatting a hard-disk volume.

Calling Non-Confirmation Methods

If the cmdlet or provider must send a message but not request confirmation, it can call the following three methods. Avoid using the System.Management.Automation.Cmdlet.WriteObject method to send messages of these types because System.Management.Automation.Cmdlet.WriteObject output is intermingled with the normal output of your cmdlet or provider, which makes script writing difficult.

Cmdlets and providers first call the following methods to request confirmation before they attempt to perform an operation that changes a system outside of Windows PowerShell:

They do so by calling the System.Management.Automation.Cmdlet.Shouldprocess method, which prompts the user to confirm the operation based on how the user invoked the command.

See Also

Writing a Windows PowerShell Cmdlet