Requesting Confirmation from Cmdlets


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 Overload:System.Management.Automation.Cmdlet.ShouldProcess and Overload:System.Management.Automation.Cmdlet.ShouldContinue (optional) methods to display a confirmation request message.

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)]

In the cmdlet code, call the Overload: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.

Most cmdlets request confirmation using only the Overload:System.Management.Automation.Cmdlet.ShouldProcess method. However, some cases might require additional confirmation. For these cases, supplement the Overload:System.Management.Automation.Cmdlet.ShouldProcess call with a call to the Overload: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 Overload: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 Overload:System.Management.Automation.Cmdlet.ShouldProcess, but it should bypass the call to Overload:System.Management.Automation.Cmdlet.ShouldContinue.

Overload: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 Overload:System.Management.Automation.Cmdlet.ShouldProcess and Overload:System.Management.Automation.Cmdlet.ShouldContinue.

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

The behavior of a Overload: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 Overload:System.Management.Automation.Cmdlet.ShouldProcess method, see How to Request Confirmations.

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.

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

  • To caution the user and continue with the operation, the cmdlet or provider can call the WriteWarning method.

  • To provide additional information that the user can retrieve using the Verbose parameter, the cmdlet or provider can call the WriteVerbose method.

  • To provide debugging-level detail for other developers or for product support, the cmdlet or provider can call the WriteDebug method. The user can retrieve this information using the Debug parameter.

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 Overload:System.Management.Automation.Cmdlet.ShouldProcess method, which prompts the user to confirm the operation based on how the user invoked the command.