Share via

How to: Create a Managed Simple Provider

  • Article

This topic describes important parts of the "Sync101 using Simple Sync Provider" sample application that is included with the Sync Framework SDK. This application demonstrates how to create and synchronize anchor-based and full enumeration simple providers. The sample application has three classes:

Both provider classes implement the following conflict-handling interfaces: ISimpleSyncProviderConcurrencyConflictResolver and ISimpleSyncProviderConstraintConflictResolver.

This topic describes the following parts of the application:

  • Creating the metadata store

  • Identifying items in the item store and metadata store

  • Enumerating items and loading data

  • Synchronizing two providers

  • Handling conflicts

The topic also briefly describes how to filter data and perform local-only deletes.

Creating the Metadata Store

Each replica requires a metadata store, which for simple providers is an instance of SqlMetadataStore. The following code example specifies options for a store in the constructor of MyFullEnumerationSimpleSyncProvider:

public MyFullEnumerationSimpleSyncProvider(string name, MySimpleDataStore store)
{
    _name = name;
    _store = store;

    // Create a file to store metadata for all items and a file to store 
    // the replica ID.
    _replicaMetadataFile = Environment.CurrentDirectory + "\\" + _name.ToString() + ".Metadata";
    _replicaIdFile = Environment.CurrentDirectory + "\\" + _name.ToString() + ".Replicaid";

    // Set ReplicaIdFormat to use a GUID as an ID, and ItemIdFormat to use a GUID plus
    // an 8-byte prefix.
    _idFormats = new SyncIdFormatGroup();
    _idFormats.ItemIdFormat.IsVariableLength = false;
    _idFormats.ItemIdFormat.Length = 24;
    _idFormats.ReplicaIdFormat.IsVariableLength = false;
    _idFormats.ReplicaIdFormat.Length = 16;

    this.ItemConstraint += new EventHandler<SimpleSyncItemConstraintEventArgs>(OnItemConstraint);
    this.ItemConflicting += new EventHandler<SimpleSyncItemConflictingEventArgs>(OnItemConflicting);
}

Public Sub New(ByVal name As String, ByVal store As MySimpleDataStore)
    _name = name
    _store = store

    ' Create a file to store metadata for all items and a file to store 
    ' the replica ID. 
    _replicaMetadataFile = (Environment.CurrentDirectory & "\") + _name.ToString() & ".Metadata"
    _replicaIdFile = (Environment.CurrentDirectory & "\") + _name.ToString() & ".Replicaid"

    ' Set ReplicaIdFormat to use a GUID as an ID, and ItemIdFormat to use a GUID plus 
    ' an 8-byte prefix. 
    _idFormats = New SyncIdFormatGroup()
    _idFormats.ItemIdFormat.IsVariableLength = False
    _idFormats.ItemIdFormat.Length = 24
    _idFormats.ReplicaIdFormat.IsVariableLength = False
    _idFormats.ReplicaIdFormat.Length = 16

    AddHandler Me.ItemConstraint, AddressOf HandleItemConstraint
    AddHandler Me.ItemConflicting, AddressOf HandleItemConflicting
End Sub

The following code example creates the store:

private void InitializeMetadataStore()
{
    SyncId id = ReplicaId;

    // Create or open the metadata store, initializing it with the ID formats 
    // that are used to reference items and replicas.
    if (!File.Exists(_replicaMetadataFile))
    {
        _metadataStore = SqlMetadataStore.CreateStore(_replicaMetadataFile);
    }
    else
    {
        _metadataStore = SqlMetadataStore.OpenStore(_replicaMetadataFile);
    }
}

Private Sub InitializeMetadataStore()
    Dim id As SyncId = ReplicaId

    ' Create or open the metadata store, initializing it with the ID formats 
    ' that are used to reference items and replicas. 
    If Not File.Exists(_replicaMetadataFile) Then
        _metadataStore = SqlMetadataStore.CreateStore(_replicaMetadataFile)
    Else
        _metadataStore = SqlMetadataStore.OpenStore(_replicaMetadataFile)
    End If
End Sub

The following code returns this store as a provider property:

public override MetadataStore GetMetadataStore(out SyncId replicaId, out System.Globalization.CultureInfo culture)
{
    InitializeMetadataStore();

    replicaId = ReplicaId;
    culture = CultureInfo.CurrentCulture;
    return _metadataStore;
}

Public Overrides Function GetMetadataStore(ByRef replicaId__1 As SyncId, ByRef culture As System.Globalization.CultureInfo) As MetadataStore
    InitializeMetadataStore()

    replicaId__1 = ReplicaId
    culture = CultureInfo.CurrentCulture
    Return _metadataStore
End Function

Identifying Items in the Item Store and Metadata Store

To synchronize an item, Sync Framework must be able to identify the item in the item store and map that identity to an internal ID in the metadata store. It must also be able to determine if the item version has changed since the last synchronization session. If the version has changed and the destination replica does not already contain that version of an item, the item should be synchronized. If changes are synchronized at the level of a change unit instead of an item, Sync Framework must be able to identify the change unit and its version. A change unit represents a sub-item change, such as the telephone number field in an item that represents a contact. This sample does not use change units.

Specifying the Format of Metadata Store IDs

The following code defines the constructor for MyFullEnumerationSimpleSyncProvider and the IdFormats property. This enables the Sync Framework runtime to determine what format the metadata store uses for IDs. If flexible IDs are not used, Sync Framework uses a fixed format to identify replicas, items, and change units. If flexible IDs are used, ISimpleSyncProviderIdGenerator methods are used to generate IDs.

public MyFullEnumerationSimpleSyncProvider(string name, MySimpleDataStore store)
{
    _name = name;
    _store = store;

    // Create a file to store metadata for all items and a file to store 
    // the replica ID.
    _replicaMetadataFile = Environment.CurrentDirectory + "\\" + _name.ToString() + ".Metadata";
    _replicaIdFile = Environment.CurrentDirectory + "\\" + _name.ToString() + ".Replicaid";

    // Set ReplicaIdFormat to use a GUID as an ID, and ItemIdFormat to use a GUID plus
    // an 8-byte prefix.
    _idFormats = new SyncIdFormatGroup();
    _idFormats.ItemIdFormat.IsVariableLength = false;
    _idFormats.ItemIdFormat.Length = 24;
    _idFormats.ReplicaIdFormat.IsVariableLength = false;
    _idFormats.ReplicaIdFormat.Length = 16;

    this.ItemConstraint += new EventHandler<SimpleSyncItemConstraintEventArgs>(OnItemConstraint);
    this.ItemConflicting += new EventHandler<SimpleSyncItemConflictingEventArgs>(OnItemConflicting);
}

public SyncId ReplicaId
{
    get 
    {
        if (_replicaId == null)
        {
            _replicaId = GetReplicaIdFromFile( _replicaIdFile);
        }

        return _replicaId; 
    }
}

public override SyncIdFormatGroup IdFormats
{
    get { return _idFormats; }
}

Public Sub New(ByVal name As String, ByVal store As MySimpleDataStore)
    _name = name
    _store = store

    ' Create a file to store metadata for all items and a file to store 
    ' the replica ID. 
    _replicaMetadataFile = (Environment.CurrentDirectory & "\") + _name.ToString() & ".Metadata"
    _replicaIdFile = (Environment.CurrentDirectory & "\") + _name.ToString() & ".Replicaid"

    ' Set ReplicaIdFormat to use a GUID as an ID, and ItemIdFormat to use a GUID plus 
    ' an 8-byte prefix. 
    _idFormats = New SyncIdFormatGroup()
    _idFormats.ItemIdFormat.IsVariableLength = False
    _idFormats.ItemIdFormat.Length = 24
    _idFormats.ReplicaIdFormat.IsVariableLength = False
    _idFormats.ReplicaIdFormat.Length = 16

    AddHandler Me.ItemConstraint, AddressOf HandleItemConstraint
    AddHandler Me.ItemConflicting, AddressOf HandleItemConflicting
End Sub
Public ReadOnly Property ReplicaId() As SyncId
    Get
        If _replicaId Is Nothing Then
            _replicaId = GetReplicaIdFromFile(_replicaIdFile)
        End If

        Return _replicaId
    End Get
End Property

Public Overrides ReadOnly Property IdFormats() As SyncIdFormatGroup
    Get
        Return _idFormats
    End Get
End Property

Specifying Item Fields and the Metadata Schema

Sync Framework maps item store data, or additional metadata that you create, to internal metadata store IDs and versions by using an ItemMetadataSchema object that is exposed by the MetadataSchema property. The following code examples provide input for the ItemMetadataSchema object. The constants in the sample code define an integer value for each column in the item store. These values are used when creating the custom field definitions and identity rules for the ItemMetadataSchema object.

public const uint CUSTOM_FIELD_ID = 1;
public const uint CUSTOM_FIELD_TIMESTAMP = 2;

public override ItemMetadataSchema MetadataSchema
{
    get
    {
        CustomFieldDefinition[] customFields = new CustomFieldDefinition[2];
        customFields[0] = new CustomFieldDefinition(CUSTOM_FIELD_ID, typeof(ulong));
        customFields[1] = new CustomFieldDefinition(CUSTOM_FIELD_TIMESTAMP, typeof(ulong));

        IdentityRule[] identityRule = new IdentityRule[1];
        identityRule[0] = new IdentityRule(new uint[] { CUSTOM_FIELD_ID });

        return new ItemMetadataSchema(customFields, identityRule);
    }
}

Public Const CUSTOM_FIELD_ID As UInteger = 1
Public Const CUSTOM_FIELD_TIMESTAMP As UInteger = 2
Public Overrides ReadOnly Property MetadataSchema() As ItemMetadataSchema
    Get
        Dim customFields As CustomFieldDefinition() = New CustomFieldDefinition(1) {}
        customFields(0) = New CustomFieldDefinition(CUSTOM_FIELD_ID, GetType(ULong))
        customFields(1) = New CustomFieldDefinition(CUSTOM_FIELD_TIMESTAMP, GetType(ULong))

        Dim identityRule As IdentityRule() = New IdentityRule(0) {}
        identityRule(0) = New IdentityRule(New UInteger() {CUSTOM_FIELD_ID})

        Return New ItemMetadataSchema(customFields, identityRule)
    End Get
End Property

The ItemMetadataSchema object exposes three properties:

  • CustomFields

    Custom fields are fields in the metadata store that are identified by integers. If an application requires a friendly name for one or more fields, it should map the integer to a name. Custom fields are defined for two reasons: to identify items, and to provide version information about those items. Version fields enable Sync Framework to determine if an item or change unit has changed. In this example, the version fields contain the actual data from the item store, so there is a field for each field in the item store. This one-to-one correspondence is not required, nor is it efficient. A more practical solution would be to take a hash of the item fields and store that in a single custom field.

  • IdentityRules

    The identity rule specifies which custom field or fields should be used to identify an item. In this case, the CUSTOM_FIELD_ID field (field 0) is used.

  • ChangeUnitVersionDefinitions (not used in this sample)

    If change units are used, you must define version fields for the change units. There is no requirement that there be a one-to-one mapping between change units and version information, or that the actual data must be stored. Change units can also span multiple fields. For example, this application could specify that Zip and Phone are a change unit and that Guid is another change unit. For Guid, you might use the actual data, and for the other change unit a hash of the Zip and Phone fields or some other mechanism to determine version.

Some of the methods that work with item store data, such as InsertItem, require a collection of ItemField objects that represent each field. The ItemFieldDictionary objects that are parameters to these methods have the same index values as those specified in the CustomFieldDefinition objects.

Enumerating Items and Loading Data

Sync Framework must be able to enumerate items in the source item store, detect if items or change units have changed, and then load the changed data so that it can be applied to the destination store. Change detection is handled by the Sync Framework runtime, but change enumeration and data loading are store-specific and are handled for full enumeration providers by implementing EnumerateItems and LoadChangeData. The following code example returns a list of items that are enumerated from the MySimpleDataStore object:

public override void EnumerateItems(FullEnumerationContext context)
{
    List<ItemFieldDictionary> items = new List<ItemFieldDictionary>();
    foreach (ulong id in _store.Ids)
    {
        items.Add(_store.CreateItemFieldDictionary(id));
    }
    context.ReportItems(items);
}

Public Overrides Sub EnumerateItems(ByVal context As FullEnumerationContext)
    Dim items As New List(Of ItemFieldDictionary)()
    For Each id As ULong In _store.Ids
        items.Add(_store.CreateItemFieldDictionary(id))
    Next
    context.ReportItems(items)
End Sub

The following code example returns an object that contains one of the data changes that was enumerated by EnumerateItems. Sync Framework calls this method until all changes have been loaded.

public override object LoadChangeData(ItemFieldDictionary keyAndExpectedVersion, IEnumerable<SyncId> changeUnitsToLoad, RecoverableErrorReportingContext recoverableErrorReportingContext)
{
    IDictionary<uint, ItemField> expectedFields = (IDictionary<uint, ItemField>)keyAndExpectedVersion;
    ulong id = (ulong)expectedFields[CUSTOM_FIELD_ID].Value;
    return new ItemTransfer(id, _store.Get(id));
}

Public Overrides Function LoadChangeData(ByVal keyAndExpectedVersion As ItemFieldDictionary, ByVal changeUnitsToLoad As IEnumerable(Of SyncId), ByVal recoverableErrorReportingContext As RecoverableErrorReportingContext) As Object
    Dim expectedFields As IDictionary(Of UInteger, ItemField) = DirectCast(keyAndExpectedVersion, IDictionary(Of UInteger, ItemField))
    Dim id As ULong = CULng(expectedFields(CUSTOM_FIELD_ID).Value)
    Return New ItemTransfer(id, _store.[Get](id))
End Function

Applying Inserts, Updates, and Deletes

After Sync Framework has detected and loaded changes from the source, it must apply those changes and corresponding metadata changes to the destination replica. Metadata changes at the destination are handled by Sync Framework, but applying data changes is store-specific and is handled by implementing the following methods: DeleteItem, InsertItem, and UpdateItem. The following code examples provide an implementation for each of these methods:

public override void InsertItem(object itemData, 
    IEnumerable<SyncId> changeUnitsToCreate,
    RecoverableErrorReportingContext recoverableErrorReportingContext, 
    out ItemFieldDictionary keyAndUpdatedVersion, 
    out bool commitKnowledgeAfterThisItem)
{
    ItemTransfer transfer = (ItemTransfer)itemData;
    ItemData dataCopy = new ItemData(transfer.ItemData);

    // Check for duplicates, and record a constraint error if a duplicate is detected.
    if (!_store.Contains(transfer.Id))
    {
        _store.CreateItem(dataCopy, transfer.Id);
        keyAndUpdatedVersion = _store.CreateItemFieldDictionary(transfer.Id);
    }
    else
    {
        recoverableErrorReportingContext.RecordConstraintError(_store.CreateItemFieldDictionary(transfer.Id));
        keyAndUpdatedVersion = null;
    }
    commitKnowledgeAfterThisItem = false;
}

public override void UpdateItem(object itemData, 
    IEnumerable<SyncId> changeUnitsToUpdate, 
    ItemFieldDictionary keyAndExpectedVersion, 
    RecoverableErrorReportingContext recoverableErrorReportingContext, 
    out ItemFieldDictionary keyAndUpdatedVersion, 
    out bool commitKnowledgeAfterThisItem)
{
    ItemTransfer transfer = (ItemTransfer)itemData;
    ItemData dataCopy = new ItemData(transfer.ItemData);
    
    IDictionary<uint, ItemField> expectedFields = (IDictionary<uint, ItemField>)keyAndExpectedVersion;
    ulong idToUpdate = (ulong)expectedFields[CUSTOM_FIELD_ID].Value;

    if (_store.Contains(idToUpdate))
    {
        ulong timeStamp = _store.UpdateItem(idToUpdate, dataCopy);
        keyAndUpdatedVersion = _store.CreateItemFieldDictionary(transfer.Id);
    }
    else
    {
        // If the item to update does not exist, record an error on this change and 
        // continue with the rest of the session.
        recoverableErrorReportingContext.RecordRecoverableErrorForChange(new RecoverableErrorData(new Exception("Item not found in the store")));
        keyAndUpdatedVersion = null;
    }
    commitKnowledgeAfterThisItem = false;
}

public override void DeleteItem(ItemFieldDictionary keyAndExpectedVersion, 
    RecoverableErrorReportingContext recoverableErrorReportingContext, 
    out bool commitKnowledgeAfterThisItem)
{
    IDictionary<uint, ItemField> expectedFields = (IDictionary<uint, ItemField>)keyAndExpectedVersion;
    ulong id = (ulong)expectedFields[CUSTOM_FIELD_ID].Value;
    if (_store.Contains(id))
    {
        _store.DeleteItem(id);
    }
    else
    {
        // If the item to delete does not exist, record an error on this change and 
        // continue with the rest of the session.
        recoverableErrorReportingContext.RecordRecoverableErrorForChange(new RecoverableErrorData(new Exception("Item not found in the store")));
    }
    commitKnowledgeAfterThisItem = false;
}

Public Overrides Sub InsertItem(ByVal itemData As Object, ByVal changeUnitsToCreate As IEnumerable(Of SyncId), ByVal recoverableErrorReportingContext As RecoverableErrorReportingContext, ByRef keyAndUpdatedVersion As ItemFieldDictionary, ByRef commitKnowledgeAfterThisItem As Boolean)
    Dim transfer As ItemTransfer = DirectCast(itemData, ItemTransfer)
    Dim dataCopy As New ItemData(transfer.ItemData)

    ' Check for duplicates, and record a constraint error if a duplicate is detected. 
    If Not _store.Contains(transfer.Id) Then
        _store.CreateItem(dataCopy, transfer.Id)
        keyAndUpdatedVersion = _store.CreateItemFieldDictionary(transfer.Id)
    Else
        recoverableErrorReportingContext.RecordConstraintError(_store.CreateItemFieldDictionary(transfer.Id))
        keyAndUpdatedVersion = Nothing
    End If
    commitKnowledgeAfterThisItem = False
End Sub
Public Overrides Sub UpdateItem(ByVal itemData As Object, ByVal changeUnitsToUpdate As IEnumerable(Of SyncId), ByVal keyAndExpectedVersion As ItemFieldDictionary, ByVal recoverableErrorReportingContext As RecoverableErrorReportingContext, ByRef keyAndUpdatedVersion As ItemFieldDictionary, ByRef commitKnowledgeAfterThisItem As Boolean)
    Dim transfer As ItemTransfer = DirectCast(itemData, ItemTransfer)
    Dim dataCopy As New ItemData(transfer.ItemData)

    Dim expectedFields As IDictionary(Of UInteger, ItemField) = DirectCast(keyAndExpectedVersion, IDictionary(Of UInteger, ItemField))
    Dim idToUpdate As ULong = CULng(expectedFields(CUSTOM_FIELD_ID).Value)

    If _store.Contains(idToUpdate) Then
        Dim timeStamp As ULong = _store.UpdateItem(idToUpdate, dataCopy)
        keyAndUpdatedVersion = _store.CreateItemFieldDictionary(transfer.Id)
    Else
        ' If the item to update does not exist, record an error on this change and 
        ' continue with the rest of the session. 
        recoverableErrorReportingContext.RecordRecoverableErrorForChange(New RecoverableErrorData(New Exception("Item not found in the store")))
        keyAndUpdatedVersion = Nothing
    End If
    commitKnowledgeAfterThisItem = False
End Sub
Public Overrides Sub DeleteItem(ByVal keyAndExpectedVersion As ItemFieldDictionary, ByVal recoverableErrorReportingContext As RecoverableErrorReportingContext, ByRef commitKnowledgeAfterThisItem As Boolean)
    Dim expectedFields As IDictionary(Of UInteger, ItemField) = DirectCast(keyAndExpectedVersion, IDictionary(Of UInteger, ItemField))
    Dim id As ULong = CULng(expectedFields(CUSTOM_FIELD_ID).Value)
    If _store.Contains(id) Then
        _store.DeleteItem(id)
    Else
        ' If the item to delete does not exist, record an error on this change and 
        ' continue with the rest of the session. 
        recoverableErrorReportingContext.RecordRecoverableErrorForChange(New RecoverableErrorData(New Exception("Item not found in the store")))
    End If
    commitKnowledgeAfterThisItem = False
End Sub

Synchronizing Two Providers

The following code example shows how source and destination replicas are synchronized. After creating source and destination providers, the code sets SyncOrchestrator options, and synchronizes the replicas.

Dim agent As New SyncOrchestrator()
agent.Direction = SyncDirectionOrder.DownloadAndUpload
agent.LocalProvider = providerA
agent.RemoteProvider = providerB
stats = agent.Synchronize()

SyncOrchestrator agent = new SyncOrchestrator();
agent.Direction = SyncDirectionOrder.DownloadAndUpload;
agent.LocalProvider = providerA;
agent.RemoteProvider = providerB;
stats = agent.Synchronize();

Handling Conflicts

In this sample, the conflict handling policies for concurrency conflicts and constraint conflicts are left as the default of ApplicationDefined. This means that the application will register for the ItemConflicting and ItemConstraint events and specify an action to resolve conflicts if they occur during synchronization processing. For more information, see Handling Conflicts for Simple Providers. The following code example shows the event handlers that are specified in the constructor of MyFullEnumerationSimpleSyncProvider:

this.ItemConstraint += new EventHandler<SimpleSyncItemConstraintEventArgs>(OnItemConstraint);
this.ItemConflicting += new EventHandler<SimpleSyncItemConflictingEventArgs>(OnItemConflicting);

AddHandler Me.ItemConstraint, AddressOf HandleItemConstraint

The following code example shows the event handlers setting the conflict resolution actions to Merge:

void OnItemConstraint(object sender, SimpleSyncItemConstraintEventArgs e)
{
    // Set the resolution action for constraint conflicts.
    // In this sample, the provider checks for duplicates in InsertItem, and this event would
    // fire if a duplicate occurred. 
    e.SetResolutionAction(ConstraintConflictResolutionAction.Merge);
}

void OnItemConflicting(object sender, SimpleSyncItemConflictingEventArgs e)
{
    // Set the resolution action for concurrency conflicts.
    e.SetResolutionAction(ConflictResolutionAction.Merge);
}

Private Sub HandleItemConstraint(ByVal sender As Object, ByVal e As SimpleSyncItemConstraintEventArgs)
    ' Set the resolution action for constraint conflicts. 
    ' In this sample, the provider checks for duplicates in InsertItem, and this event would 
    ' fire if a duplicate occurred. 
    e.SetResolutionAction(ConstraintConflictResolutionAction.Merge)
End Sub

Private Sub HandleItemConflicting(ByVal sender As Object, ByVal e As SimpleSyncItemConflictingEventArgs)
    ' Set the resolution action for concurrency conflicts. 
    e.SetResolutionAction(ConflictResolutionAction.Merge)
End Sub

The following code example shows the MergeConstraintConflict method that is implemented to respond to a resolution action of Merge for a constraint conflict:

public void MergeConstraintConflict(object itemData, 
    ConflictVersionInformation conflictVersionInformation, 
    IEnumerable<SyncId> changeUnitsToMerge, 
    ItemFieldDictionary localConflictingItem, 
    ItemFieldDictionary keyAndExpectedVersion, 
    RecoverableErrorReportingContext recoverableErrorReportingContext, 
    out ItemFieldDictionary updatedKeyAndVersion)
{
    ItemTransfer transfer = (ItemTransfer)itemData;
    ItemData dataCopy = new ItemData(transfer.ItemData);

    // Combine the conflicting data.
    ItemData mergedData = (_store.Get(transfer.Id)).Merge((ItemData)dataCopy);

    // We are doing a merge so we must delete the old conflicting item from our store.
    ulong idConflicting = (ulong)localConflictingItem[CUSTOM_FIELD_ID].Value;

    _store.DeleteItem(idConflicting);

    // Now create the new merged data in the store.
    if (_store.Contains(transfer.Id))
    {
        _store.UpdateItem(transfer.Id, dataCopy);
    }
    else
    {
        _store.CreateItem(mergedData, transfer.Id);
    }

    updatedKeyAndVersion = _store.CreateItemFieldDictionary(transfer.Id);
}

Public Sub MergeConstraintConflict(ByVal itemData As Object, ByVal conflictVersionInformation As ConflictVersionInformation, ByVal changeUnitsToMerge As IEnumerable(Of SyncId), ByVal localConflictingItem As ItemFieldDictionary, ByVal keyAndExpectedVersion As ItemFieldDictionary, ByVal recoverableErrorReportingContext As RecoverableErrorReportingContext, _
ByRef updatedKeyAndVersion As ItemFieldDictionary) Implements ISimpleSyncProviderConstraintConflictResolver.MergeConstraintConflict
    Dim transfer As ItemTransfer = DirectCast(itemData, ItemTransfer)
    Dim dataCopy As New ItemData(transfer.ItemData)

    ' Combine the conflicting data. 
    Dim mergedData As ItemData = (_store.[Get](transfer.Id)).Merge(DirectCast(dataCopy, ItemData))

    ' We are doing a merge so we must delete the old conflicting item from our store. 
    Dim idConflicting As ULong = CULng(localConflictingItem(CUSTOM_FIELD_ID).Value)

    _store.DeleteItem(idConflicting)

    ' Now create the new merged data in the store. 
    If _store.Contains(transfer.Id) Then
        _store.UpdateItem(transfer.Id, dataCopy)
    Else
        _store.CreateItem(mergedData, transfer.Id)
    End If

    updatedKeyAndVersion = _store.CreateItemFieldDictionary(transfer.Id)
End Sub

Filtering Data

Some applications require data to be filtered, so that only data that meets specific criteria is applied to a destination. For example, a salesperson might require detailed product information only for those products that she sells regularly. Simple providers enable replicas to filter data by implementing a filtering interface and by negotiating filter use.

The following code example uses filter negotiation interfaces to determine whether a specific filter should be used during a synchronization session. Filter negotiation enables a destination provider to specify that the source provider should use one or more filters during change enumeration; the source provider can accept or reject a filter. If a source provider does not support any of the requested filters, the destination provider can choose to receive all the data and do the filtering itself. Sync Framework calls the providers appropriately to negotiate filter usage.

public bool RequestFilter
{
    set
    {
        _requestFilter = value; 
    }
}
private bool _requestFilter = false;

void IRequestFilteredSync.SpecifyFilter(FilterRequestCallback filterRequest)
{
    // Request a filter only if this provider represents a filtered replica.
    if (_requestFilter)
    {
        if (!filterRequest("TheFilter", FilteringType.CurrentItemsOnly))
        {
            throw new SyncInvalidOperationException("Could not agree on filter.");
        }
    }
}

bool ISupportFilteredSync.TryAddFilter(object filter, FilteringType filteringType)
{
    if (!((string)filter).Equals("TheFilter"))
    {
        throw new Exception("Filter is incorrect");
    }

    // Remember the filter.
    _filter = (string)filter;

    return true;
}
private string _filter = "";

Public WriteOnly Property RequestFilter() As Boolean
    Set(ByVal value As Boolean)
        _requestFilter = value
    End Set
End Property

Private _requestFilter As Boolean = False

Private Sub SpecifyFilter(ByVal filterRequest As FilterRequestCallback) Implements IRequestFilteredSync.SpecifyFilter
    ' Request a filter only if this provider represents a filtered replica.
    If _requestFilter Then
        If Not filterRequest("TheFilter", FilteringType.CurrentItemsOnly) Then
            Throw New SyncInvalidOperationException("Could not agree on filter.")
        End If
    End If
End Sub

Private Function TryAddFilter(ByVal filter As Object, ByVal filteringType As FilteringType) As Boolean Implements ISupportFilteredSync.TryAddFilter
    If Not DirectCast(filter, String).Equals("TheFilter") Then
        Throw New Exception("Filter is incorrect")
    End If

    ' Remember the filter.
    _filter = DirectCast(filter, String)

    Return True
End Function

Private _filter As String = ""

The following code example first specifies a filter option of None. This means that items should be filtered out even if they are already known to the destination. The code example then implements the IsItemInFilterScope method, which filters out items based on one of the item field values. After the filter is defined, the code example implements the UseFilterThisSession method. This enables an application to specify whether filtering should be used on a per-session basis.

SimpleSyncProviderFilterOptions IFilteredSimpleSyncProvider.FilterOptions
{
    get
    {
        return SimpleSyncProviderFilterOptions.None;
    }
}

bool IFilteredSimpleSyncProvider.IsItemInFilterScope(ItemFieldDictionary KeyAndVersion)
{
    ulong itemId = (ulong)KeyAndVersion[1].Value;
    ItemData itemData = _store.Get(itemId);
    if (itemData["data"] == "3333")
    {
        return false;
    }

    return true;
}

bool IFilteredSimpleSyncProvider.UseFilterThisSession
{
    get
    {
        // Indicate whether a filter has been requested and agreed upon for this session.
        return ("" != _filter);
    }
}

Private ReadOnly Property FilterOptions() As SimpleSyncProviderFilterOptions Implements IFilteredSimpleSyncProvider.FilterOptions
    Get
        Return SimpleSyncProviderFilterOptions.None
    End Get
End Property

Private Function IsItemInFilterScope(ByVal KeyAndVersion As ItemFieldDictionary) As Boolean Implements IFilteredSimpleSyncProvider.IsItemInFilterScope
    Dim itemId As ULong = KeyAndVersion(1).Value
    Dim data As ItemData = _store.Get(itemId)
    If data("data") Is "3333" Then
        Return False
    End If

    Return True
End Function

Private ReadOnly Property UseFilterThisSession() As Boolean Implements IFilteredSimpleSyncProvider.UseFilterThisSession
    Get
        ' Indicate whether a filter has been requested and agreed upon for this session.
        Return "" Is _filter
    End Get
End Property

Performing Local-Only Deletes

Some synchronization scenarios require the ability to delete an item at a local replica without propagating that delete to other replicas. For example, a server might synchronize with several devices that store information for different salespeople. Each device has limited space, so salespeople delete old completed orders from the device. These kinds of deletes should not be propagated to the server, because the server still requires this data. Simple providers let you specify that the data should only be deleted locally. To control the behavior of deletes on a per-session basis, specify the appropriate option by using SetDeleteMode. The following code example specifies that deletes should not be propagated during synchronization.

public override void EnumerateItems(FullEnumerationContext context)
{

    context.SetDeleteMode(SimpleSyncProviderDeleteMode.LocalOnly);

    List<ItemFieldDictionary> items = new List<ItemFieldDictionary>();
    foreach (ulong id in _store.Ids)
    {
        items.Add(_store.CreateItemFieldDictionary(id));
    }
    context.ReportItems(items);
}

public override void EnumerateItems(FullEnumerationContext context) 
{ 

context.SetDeleteMode(SimpleSyncProviderDeleteMode.LocalOnly); 

List<ItemFieldDictionary> items = new List<ItemFieldDictionary>(); 
foreach (ulong id in _store.Ids) 
{ 
items.Add(_store.CreateItemFieldDictionary(id)); 
} 
context.ReportItems(items); 
}

See Also

Concepts

Implementing a Simple Custom Provider