How to: Filter Enumerated Change Units
This topic describes how to use a managed language to filter the change units enumerated by a Sync Framework synchronization provider that synchronizes data from a custom data store.
This topic assumes a basic familiarity with C# and Microsoft .NET Framework concepts.
The examples in this topic focus on the following Sync Framework classes and members:
Understanding Change Unit Filtering
Change unit filters restrict synchronization data to a subset of change units, such as to only synchronize the name and phone number fields of a contact, ignoring the remaining change units. A change unit filter is useful when a replica only stores a subset of the change units defined for the items in the scope.
Sync Framework provides the ChangeUnitListFilterInfo object to define the list of change units to include in a change enumeration. The filter can be set by the synchronization application by using whatever mechanism is appropriate between the application and the provider, or it can be negotiated between the two providers. For more information on negotiating filters, see Filtering Synchronization Data.
When a change unit filter is defined, Sync Framework requests data only for the change units that are in the filter when it calls the LoadChangeData(LoadChangeContext) of the source provider.
The destination provider receives and applies changes the same was it does for a standard change batch, except that the data sent to SaveChangeWithChangeUnits(ItemChange, SaveChangeWithChangeUnitsContext) contains only the change units that are in the filter.
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 use the metadata storage service to produce a change batch that filters the change units that are included in the change batch. 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. The filter is defined to include only the name and phone number fields of the contact.
Setting the Filter
The source provider implements a public method that allows the application to set a change unit filter that defines which contact fields to include when enumerating changes.
The synchronization application creates the source provider as the local provider and uses the SetContactFieldsToInclude method to specify that only the name and phone number fields are to be included when enumerating changes. The application also creates the destination provider and performs synchronization.
Enumerating a Filtered Change Batch
The source provider implements GetChangeBatch(UInt32, SyncKnowledge, Object) so that, when a filter has been specified, it uses the metadata storage service to produce a filtered change batch. This is done by creating a ChangeUnitListFilterInfo object, initializing it with the specified list of change units to include. The filter information is passed to the GetFilteredChangeBatch(UInt32, SyncKnowledge, FilterInfo, ItemFilterCallback) method of the ReplicaMetadata object. The metadata storage service does not need to call back to the provider to determine what to include in the filter, so a null is specified for the filterCallback parameter.
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.