Upgrading the Database Synchronization Community
This topic shows you how to upgrade a synchronization community from Sync Framework 2.0 to Sync Framework 2.1. The examples in this topic focus on the following Sync Framework classes:
Understanding Community Upgrade
Sync Framework 2.1 introduces new features and changes to the database metadata format that makes it incompatible with previous versions of Sync Framework. However, Sync Framework 2.1 can operate in a backward compatibility mode with databases that are in the 2.0 format so that synchronization continues to function even while some members of the community have not yet been upgraded. Be aware that, while synchronization can be performed in backward compatibility mode, most features are disabled until the database is upgraded to the 2.1 format. See the table in the Features Available in Backward-Compatibility Mode section for a list of features that can be used in backward compatibility mode. By following the steps outlined in the Upgrading the Synchronization Community section, you can upgrade your community without ever losing the ability to keep your databases synchronized.
Understanding Metadata Upgrade
The change to the database metadata format in Sync Framework 2.1 is the primary consideration for upgrading your community. The new metadata format is incompatible with previous versions of the database providers. The upgrade to the new metadata format cannot be undone, and when you try to use an earlier version of the database providers to synchronize a database that is in the 2.1 format, Sync Framework throws an exception. However, the SqlSyncProvider class in Sync Framework 2.1 detects the version of the metadata format, and operates in a backward compatibility mode to synchronize a database that contains metadata in the old format. Because Sync Framework 2.1 can synchronize a database in the old format with a database in either format, it is not necessary to upgrade the metadata of all of your databases at the same time. But, to make sure that the databases in your synchronization community can continue to synchronize with each other after some of them have been upgraded, you must upgrade them in the correct order. This is especially important when you use a 2-tier architecture because older versions of Sync Framework cannot read the 2.1 format. The Upgrading a 2-tier Community section in this document outlines a procedure to upgrade a 2-tier community. If you use an N-tier architecture, you can upgrade in any order as long as the local proxy provider can continue to communicate with the service component that represents the database provider on the server. For more information about the components used in an N-tier architecture, see Architecture and Classes for Database Synchronization.
Be aware that Sync Framework 2.1 components in the Microsoft.Synchronization.Data.SqlServerCe namespace automatically upgrade the metadata format of a SQL Server Compact database. This upgrade occurs the first time a component in this namespace connects to the database.
Upgrading the Synchronization Community
Because SqlSyncProvider has a backward compatibility mode, it can synchronize SQL Server databases that store metadata in the old format. This means that you can upgrade individual databases in the community as needed, and do not have to upgrade them all at the same time. The following sections describe the steps to upgrade an individual database and a procedure to use to upgrade the databases in a community that uses a 2-tier architecture.
Upgrading a Database
To upgrade a database, use the following general procedure:
Install Sync Framework 2.1. This installs side-by-side with Sync Framework 2.0.
Recompile your synchronization application and other components to use Sync Framework 2.1 by updating references to the Sync Framework assemblies to point to the 2.1 assemblies, or use binding redirection to load the Sync Framework 2.1 assemblies. For more information about binding redirection, see Sync Framework Backwards Compatibility and Interoperability.
At this point, you can continue to synchronize a SQL Server database without upgrading the metadata format, because SqlSyncProvider operates in backward compatibility mode. If you synchronize a SQL Server Compact database, it will automatically be upgraded to the new metadata format. Be aware that only synchronization operates in backward compatibility mode. Most other metadata operations or features introduced in Sync Framework 2.1 result in DbSyncException being thrown when being executed on a database with 2.0 metadata.
Upgrade the metadata format of the database by calling SqlSyncStoreMetadataUpgradeUpgradeSyncSchema or SqlCeSyncStoreMetadataUpgradeUpgradeSyncSchema. The following example shows how to do this:
You can now synchronize the upgraded database with databases that are in either metadata format.
Upgrading a 2-tier Community
When you use a 2-tier architecture for your synchronization community, Sync Framework runs on your local computer and synchronizes a local database with a database on a remote computer that is not running Sync Framework. In a 2-tier community that uses a hub-and-spoke topology you must upgrade the version of Sync Framework on all of the spoke computers before you upgrade the database metadata on the hub computer. Otherwise, when a spoke computer that uses Sync Framework 2.0 tries to synchronize with the upgraded database on the hub computer, Sync Framework will not be able to read the new metadata format and synchronization will fail.
To upgrade a 2-tier community that uses a hub-and-spoke topology, use the following general procedure:
Use the procedure in the Upgrading a Database section to upgrade a spoke computer, synchronization application, and database to Sync Framework 2.1.
At this point you can continue to synchronize the spoke database with the hub database. Sync Framework operates on the hub database in backward-compatibility mode so only synchronization functions. Other metadata operations on the hub database throw DbSyncException.
Upgrade the remaining spoke computers.
After all the spoke computers are upgraded, upgrade the hub database to the new metadata format.
Features Available in Backward-Compatibility Mode
When Sync Framework is operating in backward-compatibility mode, many features cannot be used. The following table lists some features of Sync Framework and indicates whether they can be used in backward-compatibility mode.
Sync Framework Feature |
Usable in backward-compatibility mode? |
|---|---|
Synchronization |
Yes |
Metadata cleanup |
Yes |
Batching |
Yes |
Scope detection |
Yes |
Provisioning and deprovisioning |
No |
Snapshot generation |
No |
Snapshot initialization from a database in the old format |
Yes, but the metadata is automatically upgraded to the new format. |
Maximum application transaction size |
No |
Restore from a backup in the old format |
No |
Exceptions Thrown when Metadata and Component Versions Do Not Match
When a Sync Framework 2.1 method is called for a feature that does not support backward compatibility mode, or when older Sync Framework components are used to synchronize a database in the new format, exceptions are thrown to indicate that an error has occurred. The following list of exceptions describes the situations in which the exceptions are thrown.
DbVersionException is thrown. This occurs when a Sync Framework 2.1 method is called on a database in the old format and the method does not support backward compatibility, such as provisioning a scope by calling SqlSyncScopeProvisioningApply.
SqlException is thrown with the following message: “Invalid column name 'scope_name'.” This occurs when a SqlSyncProvider object from an earlier version of Sync Framework tries to synchronize a database that is in the new format.
DbSyncException is thrown with the following message: “An error occurred when initializing adapters for scope '<scope name>'. Ensure that the scope name specified on the provider exists in the scope metadata table, and that the correct base tables are specified for that scope.” This occurs when a SqlCeSyncProvider object from an earlier version of Sync Framework tries to synchronize a database that is in the new format.