Sync Framework Backwards Compatibility and Interoperability
Different versions of Sync Framework can be installed side-by-side on a computer so that applications and providers written for a specific version of Sync Framework continue to function as expected, even as newer versions of Sync Framework are released. However, because the version of Sync Framework that a synchronization application or provider uses can change independently of other components, care must be taken to guarantee that the replicas in a synchronization community can continue to synchronize with each other. For example, when the synchronization application is upgraded to use Sync Framework 2.1, but one of the providers continues to use Sync Framework 1.0.
Consider these areas of compatibility:
Interface compatibility. For example, a synchronization application uses Sync Framework 2.1 and connects to providers in the same process. One of the providers uses Sync Framework 1.0. Interface compatibility can be achieved in managed code by using assembly redirection. Interfaces are incompatible in unmanaged code.
Database metadata compatibility. The metadata format that is used by the database providers changed in Sync Framework 2.1. A Sync Framework 2.1 SQL Server database provider can synchronize databases that use either the 2.0 or 2.1 metadata format, or you can upgrade a database to the new format. A Sync Framework 2.1 SQL Server Compact database provider automatically upgrades the database to the new format when the provider connects to the database. For a guide to upgrading your synchronization community from Sync Framework 2.0 to Sync Framework 2.1 without ever losing the ability to keep your databases synchronized, see Upgrading the Database Synchronization Community.
Custom provider metadata compatibility. For example, a synchronization application that uses Sync Framework 2.1 and uses proxy providers to connect to custom providers that run in separate processes. One provider uses Sync Framework 2.1 and the other uses Sync Framework 1.0. Metadata compatibility can be achieved by using serialization when all components use only features that are compatible with the component with the lowest version.
Note
Code written against Sync Framework 1.0 can be recompiled against Sync Framework 2.1 without change. However, to guarantee metadata compatibility, a compatibility level of SyncFrameworkVersion1 (for managed code) or SYNC_SERIALIZATION_VERSION_V1 (for unmanaged code) must be specified whenever metadata objects are serialized.
Interface Compatibility
Interface compatibility is important when the synchronization application uses a version of Sync Framework that differs from that used by one or both of the providers.
When the synchronization components run in the same process, the interfaces must be compatible. The following table lists how components that have different versions can be used together when the components run in the same process.
Components |
Managed code |
Unmanaged code |
|---|---|---|
The application uses Sync Framework 1.0, one provider uses Sync Framework 1.0, and the other provider uses Sync Framework 2.1. |
When assembly redirection is not used, Sync Framework 1.0 is used by the application, and InvalidCastException is thrown when the 2.1 provider is used. When assembly redirection is used, Sync Framework 2.1 is used by all components. Sync Framework components are backward compatible. Synchronization functions correctly. |
Sync Framework 1.0 is used by the application and E_NOINTERFACE is returned when the provider is used. |
The application uses Sync Framework 2.1, one provider uses Sync Framework 1.0, and the other provider uses Sync Framework 2.1. |
Sync Framework 2.1 is used by the application, and assembly redirection is used to instantiate version 2.1 objects for the 1.0 provider. Sync Framework components are backward compatible. Synchronization functions correctly. |
Sync Framework 2.1 is used by the application and E_NOINTERFACE is returned when the provider is used. |
The application and database providers use Sync Framework 2.0 and the databases have been upgraded to the 2.1 metadata format. |
When assembly redirection is used, Sync Framework 2.1 is used by all components. Because the database provider interfaces are backward compatible, the application can use them without being recompiled. The providers use the new metadata format in the upgraded databases and synchronization functions correctly. |
Database providers are only available in managed code. |
Redirecting the Version of Sync Framework Assemblies Used by a Provider
When an application and the providers it connects to are written in managed code, assembly redirection can be used to guarantee that a particular version of the Sync Framework assemblies are used by all components that the application loads. This is useful when an application uses Sync Framework 2.1 and one of the providers it loads uses Sync Framework 1.0, because the default behavior is for the 1.0 provider to use the Sync Framework 1.0 assemblies. This causes the application to throw InvalidCastException when the provider is loaded.
To use assembly redirection, include an application configuration (AppName.exe.config) file in the same folder as the managed application executable. The application configuration file specifies that any component that uses the Sync Framework 1.0 assemblies will be redirected to use the Sync Framework 2.1 assemblies. Remember that the database provider components have a version one more than other Sync Framework components. Therefore, in Sync Framework 2.1 the database provider assemblies have a version of 3.1. The following example shows what the AppName.exe.config file might resemble for a project that synchronizes SQL Server and SQL Server Compact databases.
Database metadata compatibility
The metadata format that is used by the database providers changed in Sync Framework 2.1. Because Sync Framework 2.1 can operate in backward compatibility mode, you can upgrade your community without ever losing the ability to keep your databases synchronized. For more information, see Upgrading the Database Synchronization Community.
For SQL Server databases, when the SqlSyncProvider class is used to perform synchronization, SqlSyncProvider detects whether the database uses the 2.0 or 2.1 metadata format. When a database uses the 2.0 format, the provider operates in backward compatibility mode so that synchronization continues to function correctly. Be aware that operations other than synchronization, such as provisioning, throw DbVersionException when the version of the database does not match the version of the Sync Framework component. When you are ready to upgrade the metadata format of the database, you can use the SqlSyncStoreMetadataUpgrade class to perform the upgrade.
For SQL Server Compact databases, all Sync Framework components detect the version of the database and automatically upgrade the metadata format when the version does not match the version of the Sync Framework component. A SQL Server Compact database can also be explicitly upgraded by using the SqlCeSyncStoreMetadataUpgrade class.
Note
After a database has been upgraded to the 2.1 metadata format, it can no longer be synchronized by a provider that uses an earlier version of Sync Framework. When SqlSyncProvider from Sync Framework 2.0 tries to synchronize a database in the 2.1 format, Sync Framework throws SqlException with the following message: Invalid column name 'scope_name'. When SqlCeSyncProvider from Sync Framework 2.0 tries to synchronize a database in the 2.1 format, Sync Framework throws DbSyncException 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.
In both situations, you must upgrade to Sync Framework 2.1 and either recompile your application or use binding redirection to load Sync Framework 2.1 components, because the metadata format upgrade cannot be undone.
Because Sync Framework 2.0 components cannot operate on a database that uses the 2.1 metadata format, make sure that you upgrade the databases and components in the correct order. For more information, see Upgrading the Database Synchronization Community.
Metadata Compatibility
Synchronization components of different versions can exchange metadata with each other if the metadata they share is of the same compatibility level. Sync Framework defines the CompatibilityLevel enumeration (for managed code) and SYNC_SERIALIZATION_VERSION enumeration (for unmanaged code) to indicate the version of the metadata contained within synchronization components. Some common scenarios are as follows:
The application uses Sync Framework 2.1 and connects to two providers by using proxy providers that were built by using Sync Framework 2.1. One remote provider uses Sync Framework 1.0 and the other provider uses Sync Framework 2.1. Neither provider uses the Sync Framework change applier. Synchronization can be performed as long as the 2.1 provider does not use any features that are incompatible with the 1.0 provider. The proxy provider exchanges metadata with the 1.0 provider by using serialization and a compatibility level of SyncFrameworkVersion1 (for managed code) or SYNC_SERIALIZATION_VERSION_V1 (for unmanaged code). Be aware that in this case, if either provider uses the Sync Framework change applier then synchronization will fail.
The application and both providers use Sync Framework 2.1. One provider is designed to work with the synchronization components of the Windows 7 operating system and the other is built by using Sync Framework 2.1. Synchronization can be performed as long as the 2.1 provider uses only features that are compatible with the Windows 7 operating system synchronization components. In this case, the compatibility level of the metadata objects is specified to be WindowsSync (for managed code) or SYNC_SERIALIZATION_VERSION_V2 (for unmanaged code). If the 2.1 provider uses a feature from a later version, such as custom filters, synchronization will fail.
Managed code The metadata classes that support serialization versions are ChangeBatchBase, SyncKnowledge, and classes derived from these classes, such as ChangeBatch and ForgottenKnowledge. As an example, a provider serializes a SyncKnowledge object to the 1.0 format by setting the CompatibilityLevel property to SyncFrameworkVersion1 and calling Serialize. If the object contains elements that cannot be serialized to the 1.0 format, InvalidKnowledgeVersionException is thrown when the CompatibilityLevel property is set.
Unmanaged code The metadata interfaces that support serialization versions are ISyncKnowledge, ISyncChangeBatchBase2, and derived or related interfaces, such as IForgottenKnowledge and ISyncChangeBatch. As an example, a provider serializes an ISyncKnowledge2 object to the 1.0 format by specifying a serialization version of SYNC_SERIALIZATION_VERSION_V1 to the ISyncKnowledge2::SerializeWithOptions method. If the object contains elements that cannot be serialized to the 1.0 format, SYNC_E_INVALID_SERIALIZATION_VERSION is returned.
Be aware that Sync Framework 2.1 includes two compatibility levels. Even when both providers use Sync Framework 2.1, make sure that the metadata they use is compatible, whether the components are both used in the same process, or interoperate by using serialization.
The following table lists Sync Framework 2.1 features that affect the metadata format, their compatibility level, and some examples of classes or methods that are included in that feature:
Feature |
Compatibility level |
Example classes or methods |
|---|---|---|
Change unit filters |
WindowsSync (for managed code) or SYNC_SERIALIZATION_VERSION_V2 (for unmanaged code) |
ChangeUnitListFilterInfo (for managed code), IChangeUnitListFilterInfo Interface (for unmanaged code) |
Constraint conflicts |
SyncFrameworkVersion2 (for managed code) or SYNC_SERIALIZATION_VERSION_V3 (for unmanaged code) |
RecordConstraintConflictForItem (for managed code), ISaveChangeContext2::SetConstraintConflictOnChange (for unmanaged code). |
Custom filters |
SyncFrameworkVersion2 (for managed code) or SYNC_SERIALIZATION_VERSION_V3 (for unmanaged code) |
CustomFilterInfo (for managed code), ICustomFilterInfo Interface (for unmanaged code) |
A knowledge object has a minimum compatibility level that corresponds to the knowledge features that are used. The compatibility level that is used to serialize a knowledge object cannot be less than the minimum compatibility level. A knowledge object is typically initialized to have a minimum compatibility level of SyncFrameworkVersion1 (for managed code) or SYNC_SERIALIZATION_VERSION_V1 (for unmanaged code). When a feature is used that requires a larger minimum compatibility level, the minimum compatibility level is increased. For example, a marker is added to a knowledge object to support custom filtering. The minimum compatibility level of the knowledge object is increased to SyncFrameworkVersion2 (for managed code) or SYNC_SERIALIZATION_VERSION_V3 (for unmanaged code). Attempts to serialize the knowledge object to a lower level will fail, as will attempts to use the knowledge object together with a provider that is designed to work only with a lower compatibility level.
Metadata Storage Service Compatibility
Sync Framework provides several mechanisms to enable components of different versions to interoperate with metadata that is stored by using the metadata storage service. For more information, see Accessing Metadata from Components with Different Versions and Upgrading the Metadata Store Version.