SimpleSyncProvider.InsertItem Method

When overridden in a derived class, called by the Sync Framework runtime to insert an item into the destination store.

Namespace: Microsoft.Synchronization.SimpleProviders
Assembly: Microsoft.Synchronization.SimpleProviders (in microsoft.synchronization.simpleproviders.dll)

Syntax

'Declaration
Public MustOverride Sub InsertItem ( _
    itemData As Object, _
    changeUnitsToCreate As IEnumerable(Of SyncId), _
    recoverableErrorReportingContext As RecoverableErrorReportingContext, _
    <OutAttribute> ByRef keyAndUpdatedVersion As ItemFieldDictionary, _
    <OutAttribute> ByRef commitKnowledgeAfterThisItem As Boolean _
)
'Usage
Dim instance As SimpleSyncProvider
Dim itemData As Object
Dim changeUnitsToCreate As IEnumerable(Of SyncId)
Dim recoverableErrorReportingContext As RecoverableErrorReportingContext
Dim keyAndUpdatedVersion As ItemFieldDictionary
Dim commitKnowledgeAfterThisItem As Boolean

instance.InsertItem(itemData, changeUnitsToCreate, recoverableErrorReportingContext, keyAndUpdatedVersion, commitKnowledgeAfterThisItem)

public abstract void InsertItem (
    Object itemData,
    IEnumerable<SyncId> changeUnitsToCreate,
    RecoverableErrorReportingContext recoverableErrorReportingContext,
    out ItemFieldDictionary keyAndUpdatedVersion,
    out bool commitKnowledgeAfterThisItem
)

public:
virtual void InsertItem (
    Object^ itemData, 
    IEnumerable<SyncId^>^ changeUnitsToCreate, 
    RecoverableErrorReportingContext^ recoverableErrorReportingContext, 
    [OutAttribute] ItemFieldDictionary^% keyAndUpdatedVersion, 
    [OutAttribute] bool% commitKnowledgeAfterThisItem
) abstract

public abstract void InsertItem (
    Object itemData, 
    IEnumerable<SyncId> changeUnitsToCreate, 
    RecoverableErrorReportingContext recoverableErrorReportingContext, 
    /** @attribute OutAttribute() */ /** @ref */ ItemFieldDictionary keyAndUpdatedVersion, 
    /** @attribute OutAttribute() */ /** @ref */ boolean commitKnowledgeAfterThisItem
)

JScript does not support passing value-type arguments by reference.

Parameters

• itemData
  Data for the item in provider-specific format.

• changeUnitsToCreate
  A SyncId object that contains the change units to insert for an item. The parameter should be null (not empty) if no change units are specified.

• recoverableErrorReportingContext
  A RecoverableErrorReportingContext object that is used to report recoverable errors that occur during attempts to insert an item.

• keyAndUpdatedVersion
  Returns the key and updated version properties of the item to be inserted. If the return value is not valid, the Sync Framework runtime throws ArgumentOutOfRangeException, which ends the session.

• commitKnowledgeAfterThisItem
  Returns whether the Sync Framework runtime should commit knowledge to the metadata store after processing is complete for the specified item.

Remarks

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.

Example

The following code example shows an implementation of this method that applies inserts to an in-memory sample data store. ItemTransfer is a simple transfer mechanism that is used when changes are loaded from the source and applied to the destination. To view this code in the context of a complete application, see the "Sync101 using Simple Sync Provider" application that is available in the Sync Framework SDK and from Code Gallery.

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 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

See Also

Reference

SimpleSyncProvider Class
SimpleSyncProvider Members
Microsoft.Synchronization.SimpleProviders Namespace