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 ensure 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.0, but one of the providers continues to use Sync Framework 1.0.
There are two main areas of compatibility to consider:
Interface compatibility. For example, a synchronization application uses Sync Framework 2.0 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 not compatible in unmanaged code.
Metadata compatibility. For example, a synchronization application uses Sync Framework 2.0 and uses proxy providers to connect to providers that run in separate processes. One provider uses Sync Framework 2.0 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.0 without change. However, to ensure 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 differing 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.0. |
When assembly redirection is not used, Sync Framework 1.0 is used by the application, and InvalidCastException is thrown when the 2.0 provider is used. When assembly redirection is used, Sync Framework 2.0 is used by all components. Sync Framework components are backward compatible, so 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.0, one provider uses Sync Framework 1.0, and the other provider uses Sync Framework 2.0. |
Sync Framework 2.0 is used by the application, and assembly redirection is used to instantiate version 2.0 objects for the 1.0 provider. Sync Framework components are backward compatible, so synchronization functions correctly. |
Sync Framework 2.0 is used by the application and E_NOINTERFACE is returned when the provider is used. |
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 ensure 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.0 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 managed application project that specifies that any component that uses the Sync Framework 1.0 assemblies will be redirected to use the Sync Framework 2.0 assemblies. The following example shows what the AppName.exe.config file might look like.
<configuration>
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<dependentAssembly>
<assemblyIdentity name="Microsoft.Synchronization"
publicKeyToken="89845dcd8080cc91"
culture="neutral" />
<bindingRedirect oldVersion="1.0.0.0-1.9.9.9"
newVersion="2.0.0.0" />
</dependentAssembly>
</assemblyBinding>
</runtime>
</configuration>
Metadata Compatibility
Synchronization components of differing 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.0 and connects to two providers by using proxy providers that were built by using Sync Framework 2.0. One remote provider uses Sync Framework 1.0 and the other provider uses Sync Framework 2.0. Neither provider uses the Sync Framework change applier. Synchronization can be performed as long as the 2.0 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.0. 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.0. Synchronization can be performed as long as the 2.0 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.0 provider uses a feature from a later version, such as custom filters, then 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 thatSync Framework 2.0 includes two compatibility levels. Even when both providers use Sync Framework 2.0, take care to ensure 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.0 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 used. The compatibility level 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 greater 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 with a provider that is designed to work only with a lower compatibility level.
Metadata Storage Service Compatibility
Sync Framework provides several mechanisms to allow components of differing 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.