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:

Important

Before you attempt to make any changes in these files, make sure to stop all active migration jobs and close the program.

Keep also in mind that this article describes only these parameters that can directly influence the migration process. You should not attempt to change other parameters in these config files on your own as it may result in the program not functioning or functioning incorrectly.

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.
  • PowerShellEnumerationIgnoreDefaultScope – this flag allows extending the scope of enumerated user mailboxes.
    <setting name="PowerShellEnumerationIgnoreDefaultScope" serializeAs="String">
    <value>False</value>
    
    Changing the value to true will allow the software to enumerate source and target mailboxes from an entire domain forest, rather than a single Exchange server.

C2ExchangeMigration.Engine.dll.config

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

  • EwsMaxRetryCount – defines the number of migration attempts (if the first one fails).
    <setting name="EwsMaxRetryCount" 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 Rescan 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.
  • EwsRetrySleepTimeMilliseconds – defines the minimum time (in milliseconds) the program should wait before attempting to upload data to the target server.
    <setting name="EwsRetrySleepTimeMilliseconds" serializeAs="String">
    <value>200</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.
  • UploadMaxAttempts – defines the number of attempts the program makes to upload a single batch in case the upload fails.
    <setting name="UploadMaxAttempts" serializeAs="String">
    <value>5</value> 
    The lower the value the faster the migration process. However, it’s not recommended to decrease this value in case of poor Internet performance and connectivity issues.
  • 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 Rescan 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.

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.
  • DownloadRetryBackOffTime – defines the time (in seconds) between consecutive failed attempts to download data from the source server.
    <setting name="DownloadRetryBackOffTime" serializeAs="String">
    <value>120</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).

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 Rescan to check the results.