How to optimize or customize the migration parameters

Problem:

You would like to customize or optimize the parameters of the migration process.

Solution:

Both CodeTwo Exchange Migration and CodeTwo Office 365 Migration have config files with settings that can be edited to suit a wide range of migration scenarios. However, keep in mind that all the default values have been thoroughly tested during the software test phase and have been decided to be the most optimal and efficient ones, and should be adequate in most migration cases. Therefore, if you notice that after changing some of the parameters described below the migration process takes longer than before, make sure to go back to the default values provided in this article.

All config files can be found in the default installation folder of the software. On 64-bit systems, this would be:

C:\Program Files (x86)\CodeTwo\<Name of the software>

On 32-bit systems, the installation folder can be found at:

C:\Program Files\CodeTwo\<Name of the software>

The config files are the same for both CodeTwo migration tools. In the current version of the software (3.x), you can modify the following files to customize the migration parameters:

• C2ExchangeMigration.Common.dll.config
• C2ExchangeMigration.MAPI.Service.dll.config
• C2ExchangeMigration.Engine.dll.config
• ExchangeMigration.Exchange.Client.dll.config
• C2ExchangeMigration.Ews.dll.config
• C2ExchangeMigration.MAPI.dll.config

C2ExchangeMigration.Common.dll.config

This file contains the following parameters that can be adjusted to your migration needs:

• DefaultConnectionLimit – defines the number of concurrent connections per endpoint.

  <setting name="DefaultConnectionLimit" serializeAs="String">
  <value>40</value>
  

  Increasing the default value may speed up the migration process; however, you cannot overdo it.

• HostedMailboxSettingsSupport – allows to enable/disable support for other mailbox types than MailboxUser.

  <setting name="HostedMailboxSettingsSupport" serializeAs="String">
  <value>True</value>
  

  Setting this parameter to False can considerably speed up mailbox enumeration but will also disable support for other types of mailboxes (they will not be displayed in the Source mailboxes step of the migration job wizard). This flag applies to connections to Office 365 only.

• HostedMailboxSettingsThreadCount – allows to set the number of threads used to enumerate mailbox types.

  <setting name="HostedMailboxSettingsThreadCount" serializeAs="String">
  <value>1</value>
  

  You can try increasing the value if you’re not satisfied with the speed of mailbox enumeration, but remember to modify it with moderation.

C2ExchangeMigration.MAPI.Service.dll.config

• SuppressMapiProfileDeletion – determines if MAPI user profiles should be deleted on launching the service or not.

  <setting name="SuppressMapiProfileDeletion" serializeAs="String">
  <value>False</value>
  

  Configuring a MAPI source server connection requires the program to create an appropriate MAPI user profile that is used to access source mailboxes. Every time on launching the source server connection wizard, the program deletes all previously created profiles and creates a new one. Setting the flag to True prevents the program from deleting the profiles and makes it use the first found profile.

C2ExchangeMigration.Engine.dll.config

This config file holds the following parameters that affect the program’s upload process (copying files to the target server):

• UploadRetryCount – defines the number of migration attempts (attempts to upload data to Exchange Web Services) if the first one fails.

  <setting name="UploadRetryCount" serializeAs="String">
  <value>3</value>
  

  In order to speed up the migration, you can decrease the value to 1. If some items are not migrated during the initial run, you can use the Run delta migration feature to allow the program to attempt to migrate these files again). If, however, you often experience connectivity problems you should consider increasing this value.
• UploadRetryBackOffTimeSeconds – defines the minimum time (in seconds) the program should wait before attempting to upload data to the target server.

  <setting name="UploadRetryBackOffTimeSeconds" serializeAs="String">
  <value>60</value> 

  Decreasing this value can speed up the migration process; however, as with the previous parameter, you may also want to increase it if you lose connectivity often.
• MaxBatchItemsSize – our software migrates items in batches. This parameter defines the maximum size (in bytes) of such a batch.

  <setting name="MaxBatchItemsSize" serializeAs="String">
  <value>10485760</value> 

  The default value is 10 MB. If the migration batch consists of more than one item, it cannot exceed this value. Increasing this value can significantly speed up the migration process while decreasing it may result in each email being uploaded one at a time. The latter is recommended for environments with slow Internet connections, as it can reduce the number of errors that may appear during the migration.
• MaxBatchItemsCount - defines the maximum number of items in one migration batch.

  <setting name="MaxBatchItemsCount" serializeAs="String">
  <value>25</value> 

  In order to improve the migration speed, you can try increasing this value. However, keep in mind that if just one item from one batch fails, the entire batch will not be migrated. The more items are in the batch, the more items will require you to use Run delta migration in the case of any problems. Reducing the batch size, on the other hand, considerably decreases the migration speed. The default value should be considered an optimal one.

• DumpFailedItems – allows to enable/disable the mechanism for dumping items which have failed to migrate to a disk.

  <setting name="DumpFailedItems" serializeAs="String">
  <value>False</value>
  

  Enabling the mechanism degrades migration performance, so you should set the parameter to True only if you experience issues.

• DumpCapacity – defines the capacity (size) of the dump for failed items.

  <setting name="DumpCapacity" serializeAs="String">
  <value>5</value>
  

  The program will dump exactly as many items as you set for this parameter. It is 5 items by default.

• DumpLocation – defines the path to the location on a disk where failed items will be dumped.

  <setting name="DumpLocation" serializeAs="String">
  <value><none></value>
  

  By default, the setting is empty, which means the items will be stored to %programdata%\CodeTwo\Exchange Migration\Dump.

• ProvisioningPropagationTimeoutSeconds – defines for how long (in seconds) the Office 365 provisioning mechanism is supposed to wait for a newly created mailbox to become correctly propagated to Exchange Web Services (EWS).

  <setting name="ProvisioningPropagationTimeoutSeconds" serializeAs="String">
  <value>600</value>
  

  The default value is set to 600 seconds. A mailbox must be propagated to EWS because it is created using the Graph API.

ExchangeMigration.Exchange.Client.dll.config

• Powershell_GetMailboxIgnoreDefaultScope – this flag allows extending the scope of enumerated user mailboxes.

  <setting name="Powershell_GetMailboxIgnoreDefaultScope" serializeAs="String">
  <value>False</value>

  Changing the value to True will allow the software to enumerate target mailboxes:
  • from an entire domain forest, rather than a single Exchange server.
  • from subdomains. 

• Powershell_MaxConnectionUptimeSeconds – defines for how long (in seconds) an idle connection to PowerShell will remain open.

  <setting name="Powershell_MaxConnectionUptimeSeconds" serializeAs="String">
  <value>600</value>
  

  After the time has elapsed, the connection will be closed.

• Ews_Trace_Enabled – allows to enable/disable trace logging when connecting to EWS and Autodiscover.

  <setting name="Ews_Trace_Enabled" serializeAs="String">
  <value>False</value>
  

  If the flag is set to True, the trace information will be logged.

• Powershell_RetryPolicySeconds – allows to configure the policy for retrying queries when connecting to PowerShell.

  <setting name="Powershell_RetryPolicySeconds" serializeAs="String">
  <value>10;30;60</value>
  

  The policy deals with intermittent issues (e.g. throttling). The program will wait as many times as the number of the values separated with a semicolon, entered in the <value> tag. For example, with the default setting, the program will wait: 10 seconds, 30 seconds, 60 seconds.

• Ews_RetryPolicySeconds – allows to configure the policy for retrying queries when connecting to EWS.

  <setting name="Ews_RetryPolicySeconds" serializeAs="String">
  <value>1;2;5</value>
  

  The policy covers intermittent issues (e.g. throttling). The program will wait as many times as the number of the values separated with a semicolon, entered in the <value> tag. For example, with the default setting, the program will wait: 1 second, 2 seconds, 5 seconds.

C2ExchangeMigration.Ews.dll.config

This file contains settings that allows you to configure an EWS (Exchange Web Services) connection in CodeTwo migration software when connecting to the source on-premises Exchange server. You can change the following parameters:

• DownloadBatchSize – defines the maximum size (in bytes) of a batch of data downloaded from the source server.

  <setting name="DownloadBatchSize" serializeAs="String">
  <value>16777216</value>
  

  The default value is 16 MB. Increasing this value significantly improves the migration speed but, at the same time, increase the risk for errors to occur.
• DownloadBatchItems – defines the maximum number of items in a download batch.

  <setting name="DownloadBatchItems" serializeAs="String">
  <value>250</value>
  

  Increasing the size of this batch increases the speed of migration. However, the probability of errors will be also greater.
• DownloadThreadsCount – defines the maximum number of threads used to retrieve data through EWS per migration job.

  <setting name="DownloadThreadsCount" serializeAs="String">
  <value>2</value>
  

  Increasing the number of threads may slightly improve the migration speed. The frequency of errors may be also higher, though.
• DownloadRetryCount – defines the number of attempts the migration tool makes to download source data via EWS.

  <setting name="DownloadRetryCount" serializeAs="String">
  <value>5</value>
  

  You can increase this value if you experience frequent connection issues due to poor network connection.
• DownloadRetryBackOffTimeSeconds – defines the time (in seconds) between consecutive failed attempts to download data from the source server.

  <setting name="DownloadRetryBackOffTimeSeconds" serializeAs="String">
  <value>60</value>
  

  You can increase this value if you experience frequent issues due to poor Internet connection.
• SuppressEmailPreviewGeneration – this flag generates the PR_PREVIEW property for emails that are missing this property (such email messages are usually found in Exchange 2010).

  <setting name="SuppressEmailPreviewGeneration" serializeAs="String">
  <value>False</value>
  

  Changing this value to true will stop the program from generating that property. It may speed up the migration process, but you need to consider that messages lacking this property will have no preview in the message list in Outlook on the web (OWA).

• MaxSlotsCount – defines how many parallel operations are available for the uploading process.

  <setting name="MaxSlotsCount" serializeAs="String">
  <value>2</value>
  

  The value takes the form of an integer and, in basic terms, says how many parallel upload transmissions can take place simultaneously.

C2ExchangeMigration.MAPI.dll.config

This config file contains timeout settings for the CodeTwo service responsible for extracting items from a source Exchange server via MAPI (Messaging Application Program Interface) and for the service’s communication with the main engine of the software. You can configure the following parameters:

• ReceiveTimeout – items extracting (downloading) operation timeout.

  <setting name="ReceiveTimeout" serializeAs="String">
  <value>600</value>
  

• CloseTimeout – connection opening timeout (connection between MAPI service and the main engine of the migration software).

  <setting name="CloseTimeout" serializeAs="String">
  <value>60</value>
  

• OpenTimeout – connection closing timeout.

  <setting name="OpenTimeout" serializeAs="String">
  <value>60</value>
  

• SendTimeout – request delivery timeout.

  <setting name="SendTimeout" serializeAs="String">
  <value>1800</value>
  

Lowering any of the above parameters is not recommended unless strictly advised by CodeTwo Customer Support. Increasing timeout values may be a good idea if you experience performance issues with the source Exchange Server and the software logs errors mentioning endpoint, pipe, net.pipe or SOAP. Be aware not to increase those values too much straight away – try using a value that is two times greater than the default one. Once you save the config file and you’re your CodeTwo product, use Run delta migration to check the results.