Accessing Replica Metadata

The metadata storage service stores two groups of metadata: one that represents the whole replica and one that represents the individual items to be synchronized. Both are manipulated by using ReplicaMetadata (for managed code) or IReplicaMetadata (for unmanaged code).

Note

  A property change is not saved to the metadata store by simply setting a property on the replica metadata or item metadata object. Property changes are saved by using SaveReplicaMetadata or SaveItemMetadata(ItemMetadata) (for managed code) or IReplicaMetadata::SaveReplicaMetadata or IReplicaMetadata::SaveItemMetadata (for unmanaged code).

Replica Metadata

The replica metadata that is stored includes the replica ID, the tick count for the replica, the current knowledge of the replica, and the forgotten knowledge of the replica. The metadata store also provides a custom metadata field that can be used to store any provider-specific metadata that is associated with the replica. This field can be set by using the CustomReplicaMetadata property (for managed code) or IReplicaMetadata::SetCustomFieldMetadata method (for unmanaged code).

Item Metadata

The item metadata contains the global ID of the item, the current version and creation version, a value that indicates whether the item is deleted from the item store, and any custom fields specified when the replica metadata was initialized. The replica metadata object provides methods that can be used to create new item metadata, delete item metadata, or find item metadata based on the global ID of the item or a custom field value.

Managed code Item metadata is represented by an ItemMetadata object. To search for an item by using an index field value, pass the field name and value to FindItemMetadataByIndexedField(String, Object).

Unmanaged code Item metadata is represented by an IItemMetadata object. To search for an item by using an index field value, create an empty IFieldValue object by using IReplicaMetadata::CreateEmptyFieldValue. Set the value to search for on the IFieldValue object and call IReplicaMetadata::FindItemMetadataByIndexedFields.

Security noteSecurity Note

To protect user data, when an item is marked as deleted, all user data, such as custom index fields, should be removed from the metadata for that item. When an item is marked as deleted, the metadata storage service automatically removes all change unit information for the item.

Caching

The replica metadata and item metadata and objects use an in-memory cache of the metadata for that replica or item. The cache is populated from the disk when the metadata object is initialized and is not refreshed at any time after that. This means that the in-memory representation will be different from the one in the metadata store file under certain conditions, such as:

  • When updates have been set to a metadata object and saved by using one of the save methods but have not yet been written to disk, such as when an explicit transaction has not been committed.

  • When more than one metadata object is created for the same replica or item and one instance makes and commits an update. In this case, the object that did not make the change will not be current, and calls to obtain its metadata will return the values from before the update.

See Also

Reference

ReplicaMetadata

ItemMetadata

Other Resources

Sync Framework Metadata Storage Service

IReplicaMetadata interface

IItemMetadata interface

IFieldValue interface