How to: Filter Enumerated Items
This topic describes how to use a managed language to filter the items 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 Item Filtering
An item filter restricts which item changes are sent by the source provider during change enumeration, such as to send only .txt files in a file folder, ignoring files of other types. Items must not change in a way that causes an existing item to move into or out of the filter. Item filters are simple to use, but the metadata used for synchronization grows in proportion to the number of items that are in the synchronization scope. If storage is a concern, custom filters are appropriate. For more information on custom filtering, see Filtering Synchronization Data.
The way that items are filtered is defined outside of Sync Framework, typically by the provider developer or a third party. 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.
The destination provider receives and applies changes the same was it does for a standard change batch. It requires no special action to account for the filtering.
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 simple item filter and how to use the metadata storage service to produce a filtered 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 contacts that have a birth date field that is less than the value specified by the application.
Setting the Filter
The source provider implements a public method that allows the application to set a filter that defines the maximum value for the birth date field. Any contact with a value greater than this value in the birth date field will not be included in a change batch.
The synchronization application creates the source provider as the local provider and uses the SetMaximumBirthdateFilter method to specify the maximum birth date to include 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 an ItemListFilterInfo object and passing it to the GetFilteredChangeBatch(UInt32, SyncKnowledge, FilterInfo, ItemFilterCallback) method of the ReplicaMetadata object.
To determine whether an item is included in the filter, the GetFilteredChangeBatch(UInt32, SyncKnowledge, FilterInfo, ItemFilterCallback) method takes an ItemFilterCallback delegate that is implemented by the source provider. The metadata storage service calls this delegate and uses the return value to include or exclude items from the change batch. In this example, an item is included in the change batch when the value of the birth date field is less than the specified maximum birth date.
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 might also want to use a custom filter instead of an item filter. Custom filters require more work to implement, but are much more efficient to track and communicate, so their use keeps synchronization metadata small. For more information on custom filters, see Filtering Synchronization Data.