WhatIf, Confirm, and ValidateOnly Parameters

  • Article

Microsoft Exchange Server 2007 will reach end of support on April 11, 2017. To stay supported, you will need to upgrade. For more information, see Resources to help you upgrade your Office 2007 servers and clients.

 

Applies to: Exchange Server 2007, Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3

The Exchange Management Shell is a very powerful and flexible management interface. You can manage your infrastructure interactively by using the command line. You can create and run scripts that automate frequently used or complex tasks. As you learn how to use the Exchange Management Shell itself, scripting, or both, you may want to view the results of a command before the command affects data. Also, you may want to acknowledge that a command is about to run. This functionality is especially important as you transition from your test environment into your production environment and as you roll out new scripts or commands.

Both experienced administrators and script writers, and administrators who are new to Exchange and scripting, can benefit from using the WhatIf, Confirm, and ValidateOnly parameters. These parameters are available in the Exchange Management Shell. These parameters let you control how your commands run and indicate exactly what a command will do before it affects data. The WhatIf, Confirm, and ValidateOnly parameters are especially useful when you use them with commands that modify objects that are returned by using a filter or by using a Get command in a pipeline. This topic describes each parameter.

Important

If you want to use the WhatIf, Confirm, and ValidateOnly parameters with commands in a script, you must add the appropriate parameter to each command in the script, and not on the command line that calls the script.

Note

The WhatIf, Confirm, and ValidateOnly parameters are called switch parameters. For more information about switch parameter, see Parameters.

WhatIf Parameter

The WhatIf parameter instructs the command to which it is applied to run but only to display the objects that would be affected by running the command and what changes would be made to those objects. The domain does not actually change any of those objects. When you use the WhatIf parameter, you can see whether the changes that would be made to those objects match your expectations, without the worry of modifying those objects.

When you run a command together with the WhatIf parameter, you put the WhatIf parameter at the end of the command, as in the following example:

New-AcceptedDomain -Name "Contoso Domain" -DomainName "contoso.com" -WhatIf

When you run this example command, the following text is returned by the Exchange Management Shell:

What if: Creating Accepted Domain "Contoso Domain" with Domain Name "contoso.com".

To display a list of cmdlets that accept the WhatIf parameter, type the following command in the Exchange Management Shell:

Get-ExCommand | Where { $_.Definition -Like "*WhatIf*" }

Confirm Parameter

The Confirm parameter instructs the command to which it is applied to stop processing before any changes are made. The command then prompts you to acknowledge each action before it continues. When you use the Confirm parameter, you can step through changes to objects to make sure that changes are made only to the specific objects that you want to change. This functionality is useful when you apply changes to many objects and want precise control over the operation of the Exchange Management Shell. A confirmation prompt is displayed for each object before the Exchange Management Shell modifies the object.

By default, the Exchange Management Shell automatically applies the Confirm parameter to cmdlets that have the following verbs:

  • Remove

  • Move

  • Stop

  • Clear

  • Suspend

  • Uninstall

  • Dismount

  • Disable

When a cmdlet runs that has any of these verbs, the Exchange Management Shell automatically stops the command and waits for your acknowledgement before it continues to process.

When you manually apply the Confirm parameter to a command, include the Confirm parameter at the end of the command, as in the following example:

Get-JournalRule | Enable-JournalRule -Confirm

When you run this example command, the following confirmation prompt is returned by the Exchange Management Shell:

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

The confirmation prompt gives you the following choices:

  • [Y] Yes   Type Y to instruct the command to continue the operation. The next operation will present another confirmation prompt. [Y] Yes is the default choice.

  • [A] Yes to All   Type A to instruct the command to continue the operation and all subsequent operations. You will not receive additional confirmation prompts for the duration of this command.

  • [N] No   Type N to instruct the command to skip this operation and continue with the next operation. The next operation will present another confirmation prompt.

  • [L] No to All   Type L to instruct the command to skip this operation and all subsequent operations.

  • [S] Suspend   Type S to pause the current pipeline and return to the command line. Type Exit to resume the pipeline.

  • [?] Help   Type ? to display confirmation prompt help on the command line.

If you want to override the default behavior of the Exchange Management Shell and suppress the confirmation prompt for cmdlets on which it is automatically applied, you can include the Confirm parameter with a value of $False, as in the following example:

Get-JournalRule | Disable-JournalRule -Confirm:$False

In this case, no confirmation prompt is displayed.

Warning

The default value of the Confirm parameter is $True. The default behavior of the Exchange Management Shell is to automatically display a confirmation prompt. If you suppress this default behavior of the Exchange Management Shell, you instruct the command to suppress all confirmation prompts for the duration of that command. The command will process all objects that meet the criteria for the command without confirmation.

To display a list of cmdlets that accept the Confirm parameter, type the following command in the Exchange Management Shell:

Get-ExCommand | Where { $_.Definition -Like "*Confirm*" }

ValidateOnly Parameter

The ValidateOnly parameter instructs the command to which it is applied to evaluate all the conditions and requirements that are needed to perform the operation before you apply any changes. The ValidateOnly parameter is available on cmdlets that may take a long time to run, have several dependencies on multiple systems, or affect critical data, such as mailboxes.

When you apply the ValidateOnly parameter to a command, the command runs through the whole process. The command performs each action as it would without the ValidateOnly parameter. But the command doesn't change any objects. When the command completes its process, it displays a summary with the results of the validation. If the validation indicates that the command was successful, you can run the command again without the ValidateOnly parameter.

When you run a command together with the ValidateOnly parameter, you put the ValidateOnly parameter at the end of the command, as in the following example:

Get-Mailbox "Kim Akers" | Move-Mailbox -TargetDatabase "Executive Database" -ValidateOnly

When you run this example command, the following text is returned by the Exchange Management Shell:

Identity                         : contoso.com/Users/Kim Akers
DistinguishedName                : CN=Kim Akers,CN=Users,DC=contoso,DC=com
DisplayName                      : Kim Akers
Alias                            : kim
LegacyExchangeDN                 : /o=First Organization/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=kim
PrimarySmtpAddress               : kim@contoso.com
SourceServer                     : Win2003MS.contoso.com
SourceDatabase                   : WIN2003MS\First Storage Group\Mailbox Database
SourceGlobalCatalog              : Win2003MS.contoso.com
TargetGlobalCatalog              : Win2003MS.contoso.com
TargetDomainController           : Win2003MS.contoso.com
TargetMailbox                    :
TargetServer                     : Win2003MS.contoso.com
TargetDatabase                   : WIN2003MS\Second Storage Group\Executive Database
MailboxSize                      : 0KB
IsResourceMailbox                : False
SIDUsedInMatch                   :
SMTPProxies                      :
SourceManager                    :
SourceDirectReports              :
SourcePublicDelegates            :
SourcePublicDelegatesBL          :
MatchedTargetNTAccountDN         :
IsMatchedNTAccountMailboxEnabled :
MatchedContactsDNList            :
TargetNTAccountDNToCreate        :
TargetManager                    :
TargetDirectReports              :
TargetPublicDelegates            :
TargetPublicDelegatesBL          :
Options                          : Default
SourceForestCredential           :
TargetForestCredential           :
TargetFolder                     :
RsgMailboxGuid                   :
RsgMailboxLegacyExchangeDN       :
RsgMailboxDisplayName            :
RsgDatabaseGuid                  :
MoveType                         : IntraOrg
MoveStage                        : Validation
StartTime                        : 7/17/2006 4:39:13 PM
EndTime                          : 7/17/2006 4:39:14 PM
StatusCode                       : 0
StatusMessage                    : This mailbox can be moved to the target database.

To display a list of cmdlets that accept the ValidateOnly parameter, type the following command in the Exchange Management Shell:

Get-ExCommand | Where { $_.Definition -Like "*ValidateOnly*" }