Move Mailboxes by Using the MoveMailbox.ps1 Script in the Shell

Article
06/29/2011

Applies to: Exchange Server 2010

Similar to the Move-Mailbox cmdlet in Microsoft Exchange Server 2007, the MoveMailbox.ps1 script provides a synchronous management experience for moving mailboxes. By default, scripts are installed at C:\Program Files\Microsoft\Exchange Server\V14\Scripts.

Note

You can use this script for local moves only. You can't use this script for remote (cross-forest) moves. For information about remote mailbox moves, see Prepare Mailboxes for Cross-Forest Move Requests.

MoveMailbox.ps1 performs the following tasks:

Creates a local move request.
Waits for the mailbox move to complete.
Clears the move request after it completes.

MoveMailbox.ps1 includes two parameter sets. The first parameter set moves a single mailbox, or you can pipeline mailboxes into the command. The second parameter set moves all mailboxes hosted on a specified database, or you can pipeline database objects into the command to move all mailboxes that reside on those mailbox databases.

Note

The Shell doesn't load scripts automatically. You must precede all scripts with ".</STRONG>" For example, to run the MoveMailbox.ps1 script, type .\MoveMailbox.ps1.

For more information about using and writing scripts, see Scripting with the Exchange Management Shell.

Looking for other management tasks related to move requests? Check out Managing Move Requests.

Using MoveMailbox.ps1 to move specific mailboxes

You need to be assigned permissions before you can perform this procedure. To see what permissions you need, see the "Mailbox moves" entry in the Mailbox Permissions topic.

The following parameter syntax set and table lists the parameters that you can use to move specific mailboxes.

MoveMailbox.ps1 -Identity <Object> -DatabaseMap <Hashtable> -TargetDatabase <Object> [-StartBatchSize <Int32>] [-BadItemLimit <Int32>] [-AutoSuspend] [-pollInterval <Int32>] [-DomainController <Object>]

Parameter Required Description

DatabaseMap

Required

The DatabaseMap parameter specifies the map between the databases you're moving to and from. Use this parameter if you're using the pipelining method to identify the mailboxes you're moving to. The DatabaseMap parameter requires the following:

Use the following syntax: @{"<SourceDatabase>"="<TargetDatabase>"}

The SourceDatabase name must match the database name as reported by the Get-Mailbox cmdlet.

You can include multiple database maps. Separate multiple maps with a semicolon (;), for example, @{"DB1"="DBA";"DB2"="DBB"}

Note:

You can't use this parameter in conjunction with the TargetDatabase parameter. If you're pipelining the command, and a user matches the identity in the Get-Mailbox cmdlet but doesn't match the source database in the DatabaseMap cmdlet, that user's mailbox will be skipped.

Identity

Required

The Identity parameter specifies the identity of the mailbox that you want to move. This parameter accepts the following values:

ADObjectID

Alias

Distinguished name (DN)

Domain\Account

GUID

LegacyExchangeDN

SmtpAddress

User principal name (UPN)

Note:

You can pipeline the Identity parameter by using the Get-Mailbox cmdlet.

TargetDatabase

Required

The TargetDatabase parameter specifies the identity of the database that you're moving the mailbox to. This parameter accepts the following values:

GUID

Distinguished name (DN)

Server\database name

Database name

Note:

You can't use this parameter in conjunction with the DatabaseMap parameter.

AutoSuspend

Optional

The AutoSuspend switch specifies whether to suspend the move request before it reaches the status of CompletionInProgress. After the move is suspended, it has a status of AutoSuspended. If you use this parameter, you must complete the move by using the Resume-MoveRequest cmdlet.

BadItemLimit

Optional

The BadItemLimit parameter specifies the number of bad items to skip if the move request encounters corruption in the mailbox. Use the value 0 if you don’t want to skip bad items. Use the value -1 to skip an unlimited number of bad items. The valid input range for this parameter is from -1 through 2,147,483,647. The default value is 0. We recommend that you keep the default value 0 and only change the BadItemLimit parameter value if the move request fails.

DomainController

Optional

The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory.

PollInterval

Optional

The PollInterval parameter specifies, in seconds, the amount of time to wait before checking if a move request is completed. For example, if the PollInterval is set to 180, the MoveMailbox.ps1 script will check the move requests status every 3 minutes to see if the move has the status of Completed. The default time is 10 seconds.

StartBatchSize

Optional

The StartBatchSize parameter specifies how often to start mailbox moves for load balancing purposes. The parameter applies only when moving multiple mailboxes at one time. For example, if this parameter is set to 10 and you're moving 15 mailboxes, the script will invoke the New-MoveRequest cmdlet when it sees that 10 mailboxes are being moved to the same target database.

Examples

EXAMPLE 1

This example moves the mailboxes that begin with "ay". If these mailboxes reside on the mailbox database DB1, this example uses the DatabaseMap parameter to move them to mailbox database DBA. If these mailboxes reside on DB2, this example moves them to mailbox database DBB.

Get-Mailbox ay* | .\MoveMailbox.ps1 -DatabaseMap @{"DB1"="DBA";"DB2"="DBB"}

EXAMPLE 2

This example moves Tony Smith's mailbox to DB2.

.\MoveMailbox.ps1 -Identity "Tony@Contoso.com" -TargetDatabase "DB2"

Using MoveMailbox.ps1 to move mailboxes homed on a specific database

You need to be assigned permissions before you can perform this procedure. To see what permissions you need, see the "Mailbox moves" entry in the Mailbox Permissions topic.

The following parameter syntax set and table lists the parameters that will move mailboxes based on the database.

MoveMailbox.ps1 -MailboxDatabase <Object> [-DatabaseMap <Hashtable>] [-TargetDatabase <Object>] [-StartBatchSize <Int32>] [-BadItemLimit <Int32>] [-AutoSuspend] [-pollInterval <Int32>] [-DomainController <Object>]

Parameter

Required

Description

MailboxDatabase

Required

The MailboxDatabase parameter specifies the mailbox database from which you're moving mailboxes.

This parameter accepts the following values:

GUID

Distinguished name (DN)

Server\database name

Database name

Note:

You can't use this parameter in conjunction with the DatabaseMap parameter.

AutoSuspend

Optional

The AutoSuspend switch specifies whether to suspend the move request before it reaches the status of CompletionInProgress. After the move is suspended, it has a status of AutoSuspended. If you use this parameter, you must complete the move by using the Resume-MoveRequest cmdlet.

BadItemLimit

Optional

The BadItemLimit parameter specifies the number of bad items to skip if the move request encounters corruption in the mailbox. Use the value 0 if you don’t want to skip bad items. Use the value -1 to skip an unlimited number of bad items. The valid input range for this parameter is -1 to 2,147,483,647. The default value is 0. We recommend that you keep the default value 0 and only change the BadItemLimit parameter value if the move request fails.

DatabaseMap

Optional

The DatabaseMap parameter specifies the map between the databases you're moving to and from. Use this parameter if you're using the pipelining method to identify the mailboxes you're moving to. The DatabaseMap parameter requires the following:

Use the following syntax: @{"<SourceDatabase>"="<TargetDatabase>"}

The SourceDatabase name must match the database name as reported by the Get-Mailbox cmdlet.

You can include multiple database maps. Separate multiple maps with a semicolon (;), for example, @{"DB1"="DBA";"DB2"="DBB"}

Note:

You can't use this parameter in conjunction with the TargetDatabase parameter. If you're pipelining the command, and a user matches the identity in the Get-Mailbox cmdlet but doesn't match the source database in the DatabaseMap cmdlet, that user's mailbox will be skipped.

DomainController

Optional

The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory.

PollInterval

Optional

The PollInterval parameter specifies, in seconds, the amount of time to wait before checking if a move request is completed. For example, if the PollInterval is set to 180, the MoveMailbox.ps1 script will check the move requests status every 3 minutes to see if the move has the status of Completed. The default time is 10 seconds.

StartBatchSize

Optional

The StartBatchSize parameter specifies how often to start mailbox moves for load balancing purposes. The parameter applies only when moving multiple mailboxes at one time. For example, if this parameter is set to 10 and you're moving 15 mailboxes, the script will invoke the New-MoveRequest cmdlet when it sees that 10 mailboxes are being moved to the same target database.

TargetDatabase

Optional

The TargetDatabase parameter specifies the identity of the database that you're moving the mailbox to. This parameter accepts the following values:

GUID

Distinguished name (DN)

Server\database name

Database name

Note:

You can't use this parameter in conjunction with the DatabaseMap parameter.

Examples

EXAMPLE 1

This example moves all mailboxes that reside on mailbox database DB1 to database DB2.

.\MoveMailbox.ps1 -MailboxDatabase DB1 -TargetDatabase DB2

EXAMPLE 2

This example uses the Get-MailboxDatabase cmdlet to retrieve all mailbox database objects whose mailbox database begins with "DB1", and then pipelines the result to the MoveMailbox.ps1 script.

Get-MailboxDatabase DB1* | .\MoveMailbox.ps1 -DatabaseMap @{"DB10"=DBA;"DB11"="DBB";"DB12"="DBA"}

Share via

Move Mailboxes by Using the MoveMailbox.ps1 Script in the Shell

Using MoveMailbox.ps1 to move specific mailboxes

Examples

EXAMPLE 1

EXAMPLE 2

Using MoveMailbox.ps1 to move mailboxes homed on a specific database

Examples

EXAMPLE 1

EXAMPLE 2

Additional resources

Parameter	Required	Description
DatabaseMap	Required	The DatabaseMap parameter specifies the map between the databases you're moving to and from. Use this parameter if you're using the pipelining method to identify the mailboxes you're moving to. The DatabaseMap parameter requires the following: Use the following syntax: `@{"<SourceDatabase>"="<TargetDatabase>"}` The SourceDatabase name must match the database name as reported by the Get-Mailbox cmdlet. You can include multiple database maps. Separate multiple maps with a semicolon (;), for example, @{"DB1"="DBA";"DB2"="DBB"} Note: You can't use this parameter in conjunction with the TargetDatabase parameter. If you're pipelining the command, and a user matches the identity in the Get-Mailbox cmdlet but doesn't match the source database in the DatabaseMap cmdlet, that user's mailbox will be skipped.
Identity	Required	The Identity parameter specifies the identity of the mailbox that you want to move. This parameter accepts the following values: ADObjectID Alias Distinguished name (DN) Domain\Account GUID LegacyExchangeDN SmtpAddress User principal name (UPN) Note: You can pipeline the Identity parameter by using the Get-Mailbox cmdlet.
TargetDatabase	Required	The TargetDatabase parameter specifies the identity of the database that you're moving the mailbox to. This parameter accepts the following values: GUID Distinguished name (DN) Server\database name Database name Note: You can't use this parameter in conjunction with the DatabaseMap parameter.
AutoSuspend	Optional	The AutoSuspend switch specifies whether to suspend the move request before it reaches the status of `CompletionInProgress`. After the move is suspended, it has a status of `AutoSuspended`. If you use this parameter, you must complete the move by using the Resume-MoveRequest cmdlet.
BadItemLimit	Optional	The BadItemLimit parameter specifies the number of bad items to skip if the move request encounters corruption in the mailbox. Use the value `0` if you don’t want to skip bad items. Use the value `-1` to skip an unlimited number of bad items. The valid input range for this parameter is from `-1` through `2,147,483,647`. The default value is `0`. We recommend that you keep the default value `0` and only change the BadItemLimit parameter value if the move request fails.
DomainController	Optional	The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory.
PollInterval	Optional	The PollInterval parameter specifies, in seconds, the amount of time to wait before checking if a move request is completed. For example, if the PollInterval is set to 180, the MoveMailbox.ps1 script will check the move requests status every 3 minutes to see if the move has the status of Completed. The default time is 10 seconds.
StartBatchSize	Optional	The StartBatchSize parameter specifies how often to start mailbox moves for load balancing purposes. The parameter applies only when moving multiple mailboxes at one time. For example, if this parameter is set to `10` and you're moving 15 mailboxes, the script will invoke the New-MoveRequest cmdlet when it sees that 10 mailboxes are being moved to the same target database.

Parameter	Required	Description
MailboxDatabase	Required	The MailboxDatabase parameter specifies the mailbox database from which you're moving mailboxes. This parameter accepts the following values: GUID Distinguished name (DN) Server\database name Database name Note: You can't use this parameter in conjunction with the DatabaseMap parameter.
AutoSuspend	Optional	The AutoSuspend switch specifies whether to suspend the move request before it reaches the status of `CompletionInProgress`. After the move is suspended, it has a status of `AutoSuspended`. If you use this parameter, you must complete the move by using the Resume-MoveRequest cmdlet.
BadItemLimit	Optional	The BadItemLimit parameter specifies the number of bad items to skip if the move request encounters corruption in the mailbox. Use the value `0` if you don’t want to skip bad items. Use the value `-1` to skip an unlimited number of bad items. The valid input range for this parameter is `-1` to `2,147,483,647`. The default value is `0`. We recommend that you keep the default value `0` and only change the BadItemLimit parameter value if the move request fails.
DatabaseMap	Optional	The DatabaseMap parameter specifies the map between the databases you're moving to and from. Use this parameter if you're using the pipelining method to identify the mailboxes you're moving to. The DatabaseMap parameter requires the following: Use the following syntax: `@{"<SourceDatabase>"="<TargetDatabase>"}` The SourceDatabase name must match the database name as reported by the Get-Mailbox cmdlet. You can include multiple database maps. Separate multiple maps with a semicolon (;), for example, @{"DB1"="DBA";"DB2"="DBB"} Note: You can't use this parameter in conjunction with the TargetDatabase parameter. If you're pipelining the command, and a user matches the identity in the Get-Mailbox cmdlet but doesn't match the source database in the DatabaseMap cmdlet, that user's mailbox will be skipped.
DomainController	Optional	The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory.
PollInterval	Optional	The PollInterval parameter specifies, in seconds, the amount of time to wait before checking if a move request is completed. For example, if the PollInterval is set to 180, the MoveMailbox.ps1 script will check the move requests status every 3 minutes to see if the move has the status of Completed. The default time is 10 seconds.
StartBatchSize	Optional	The StartBatchSize parameter specifies how often to start mailbox moves for load balancing purposes. The parameter applies only when moving multiple mailboxes at one time. For example, if this parameter is set to `10` and you're moving 15 mailboxes, the script will invoke the New-MoveRequest cmdlet when it sees that 10 mailboxes are being moved to the same target database.
TargetDatabase	Optional	The TargetDatabase parameter specifies the identity of the database that you're moving the mailbox to. This parameter accepts the following values: GUID Distinguished name (DN) Server\database name Database name Note: You can't use this parameter in conjunction with the DatabaseMap parameter.