How to: Filter a Replica
This topic describes how to use a managed language to implement a Sync Framework provider that represents a filtered replica. A filtered replica stores data only for items or change units that are in its filter.
This topic assumes a basic familiarity with C# and Microsoft .NET Framework concepts.
The examples in this topic focus on the following Sync Framework class and member:
Understanding Filtered Replicas
A filtered replica stores item and change unit data only for the items and change units that are in its filter, as well as ghosts, which are metadata for items and change units that were in the filter but have moved out. A filtered replica also tracks its filter, and may track other filters as well. A filtered replica can negotiate a filter with the source provider, in which case the source provider produces a filtered change batch. If the source provider cannot produce a filtered change batch, the filtered provider can filter the changes itself and apply only those that are in its filter.
A filtered provider implements IFilteredReplicaNotifyingChangeApplierTarget to communicate with the change applier about items that have moved in relation to the filter. A filtered provider also typically implements IRequestFilteredSync so that it can negotiate the filter that the source provider uses for enumerating changes.
Build Requirements
.NET Framework 2.0 or later.
Reference to Microsoft.Synchronization.
Reference to Microsoft.Synchronization.MetadataStorage.
Example
The example code in this topic shows how to implement a filtered destination provider. The filtered provider requests a filtered change batch that includes ghosts, and applies the filtered changes and ghosts to the destination replica. The replica in this example is a text file that stores contact information as a list of comma-separated values. The items to synchronize are the contacts that are contained in this file. A filter is a string that causes a contact to be included only if the filter string is found in the address field of the contact.
Negotiating the Filter
When Sync Framework calls the SpecifyFilter(FilterRequestCallback) method of the destination replica, the destination replica requests the filter that the source provider uses to enumerate changes. This example specifies the first filter in the list of filters tracked by the destination replica and throws an exception if the source provider rejects the filter.
Applying Filtered Changes
The destination provider uses a change applier to process the change batch. The metadata storage service does not support custom filtering, so the list of local versions must be updated to mark ghost changes before the list is sent to the change applier.
The change applier calls the SaveItemChange(SaveChangeAction, ItemChange, SaveChangeContext) method to save changes. A filtered replica handles change actions that affect ghosts.
Enumerating Items Moved into the Filter
The filtered provider implements IFilteredReplicaNotifyingChangeApplierTarget to communicate with the change applier about items that have moved in relation to the filter. This example enumerates all the items in the metadata store and adds an item to the returned list when the item is in the filter for the replica and the move version of the item is not contained in the specified base knowledge.
Next Steps
Next, you might want to add filter negotiation to your provider so that it can communicate with the destination provider to establish which filter to use for change enumeration. For more information on how to negotiate filters, see How to: Negotiate a Filter.
You may also want to enable your provider to track filters. Filter-tracking replicas keep the knowledge size small when sending changes to filtered replicas. For more information on how to implement a filter-tracking provider, see How to: Track Filters and Enumerate Filtered Changes.