Detecting and Resolving Concurrency Conflicts

Concurrency conflicts occur when the same item or change unit is changed on two different replicas that are later synchronized. Sync Framework provides a change applier object that simplifies detection and resolution of concurrency conflicts.

How the Change Applier Detects and Resolves Concurrency Conflicts

A concurrency conflict is detected when the destination replica’s version of a change is not contained in the source replica's knowledge.

Sync Framework provides a change applier object that the destination provider can use to detect concurrency conflicts. The change applier detects concurrency conflicts by performing the following steps for each item in the change batch that is sent by the source provider:

1. Determines whether the destination replica's version of the item is contained in the source replica's knowledge.

2. If the destination replica's version of the item is not contained in the source replica's knowledge, the change is in conflict.

After the change applier detects a concurrency conflict, it resolves the conflict according to either the conflict resolution policy set for the session, or the conflict resolution action set by the application for the specified conflict.

Detecting Concurrency Conflicts by Using a Change Applier

To use a change applier to detect changes, the destination provider first creates the change applier object.

Managed code Create a NotifyingChangeApplier object.

Unmanaged code Create an ISynchronousNotifyingChangeApplier object by passing IID_ISynchronousNotifyingChangeApplier to the IProviderSyncServices::CreateChangeApplier method.

The destination provider next must provide version information for each item in the change batch sent by the source provider. The two ways to do this are as follows:

• The destination provider builds a list of versions that corresponds to the batch of changes that are sent by the source provider. The change applier uses this list to determine whether the destination version of an item is contained in the source replica's knowledge.

  Managed code To create this list, create an object of type System.Collections.Generic.IEnumerable<Microsoft.Synchronization.ItemChange>. For each item in the source provider's change batch, add an item to this list that contains the destination replica's version of the item. Pass this list to the change applier as the destinationVersions parameter of the appropriate method overload, such as ApplyChanges.

  Unmanaged code To create this list, create an IDestinationChangeVersionsBuilder object by calling IProviderSyncServices::CreateDestinationChangeVersionsBuilder. For each item in the source provider's change batch, add an item to this list that contains the destination replica's version of the item, by calling IDestinationChangeVersionsBuilder::AddItemMetadata. Get an enumerator for the list by calling IDestinationChangeVersionsBuilder::GetChangeEnumerator and pass the enumerator to the change applier as the pDestinationVersions parameter of the ApplyChanges method.

• Alternatively, the destination provider does not pass a list of destination versions to the change applier. Instead, the destination provider implements the TryGetDestinationVersion (for managed code) or ISynchronousNotifyingChangeApplierTarget::GetDestinationVersion (for unmanaged code) method. The change applier calls this method one time for each item in the source provider's change batch. In this method the destination provider looks up the destination replica's version of the item and returns it to the change applier so the change applier can determine whether the change is a conflict.

Finally, the destination provider calls the ApplyChanges (for managed code) or ISynchronousNotifyingChangeApplier::ApplyChanges (for unmanaged code) method of the change applier.

Using a Change Applier to Resolve Concurrency Conflicts

The change applier helps a destination provider resolve conflicts by dispatching calls to a change applier target object that is specified by the provider. When a conflict resolution policy is specified, the change applier uses it to determine the correct conflict resolution action to take to resolve each conflict that occurs. When custom conflict resolution is specified, the change applier notifies the synchronization application of the conflict, and the application specifies the conflict resolution action. In either situation, the change applier calls the appropriate change applier target method and the change applier target object performs the action, such as to save the change to the replica or to log the conflict for later processing.

The synchronization application typically specifies a concurrency conflict resolution policy before synchronization is started.

Managed code The application specifies the policy by setting the ConflictResolutionPolicy property of the destination provider to the desired value.

Unmanaged code The application specifies the policy in the resolutionPolicy parameter of the ISyncSession::Start method. The destination provider receives this policy as the resolutionPolicy parameter of the IKnowledgeSyncProvider::ProcessChangeBatch method.

The destination provider passes the conflict resolution policy to the change applier so the change applier can properly dispatch methods to the change applier target. The change applier target is represented by the INotifyingChangeApplierTarget object (for managed code) or ISynchronousNotifyingChangeApplierTarget (for unmanaged code) object.

Sync Framework defines the following concurrency conflict resolution policies.

Specifying Custom Conflict Resolutions

To specify the conflict resolution action dynamically for each concurrency conflict that occurs, an application performs the following actions before starting synchronization.

Managed code

• Registers an event handler for the ItemConflicting event of the destination provider.

• Sets the ConflictResolutionPolicy property of the destination provider to ApplicationDefined.

Unmanaged code

• Implements the ISyncCallback::OnConflict method and registers the ISyncCallback object by calling ISyncSession::RegisterCallback.

• Passes CRP_NONE for the resolutionPolicy parameter of ISyncSession::Start.

During synchronization, the change applier raises the ItemConflicting event (for managed code) or ISyncCallback::OnConflict method (for unmanaged code) one time for each concurrency conflict that it detects. The application can examine the two changes in conflict, make changes to the metadata or item data, and set the resolution action for the conflict by using the SetResolutionAction method (for managed code), or IChangeConflict::SetResolveActionForChange or IChangeConflict::SetResolveActionForChangeUnit method (for unmanaged code). The change applier then processes the conflict and dispatches the appropriate call to the change applier target object.

Concurrency Conflict Resolution Actions Used by Managed Code

Sync Framework provides the following set of concurrency conflict resolution actions for which the change applier handles most of the processing.

Concurrency Conflict Resolution Actions Used by Unmanaged Code

Sync Framework provides the following set of concurrency conflict resolution actions for which the change applier handles most of the processing.

See Also

Reference

ISynchronousNotifyingChangeApplier Interface
ISynchronousNotifyingChangeApplierTarget Interface
CONFLICT_RESOLUTION_POLICY Enumeration
SYNC_RESOLVE_ACTION Enumeration
NotifyingChangeApplier
INotifyingChangeApplierTarget
ConflictResolutionAction
ConflictResolutionPolicy

Concepts

Handling Conflicts
Detecting and Resolving Constraint Conflicts