Metadata Requirements for Standard Providers

项目
07/11/2014

Sync Framework requires a particular set of metadata for each replica and for each item that is to be synchronized.

Required Metadata for Each Replica

Each replica is required to store the set of metadata that is shown in the following table.

Metadata element	Description
Replica ID	Is the unique identifier of a replica in a synchronization community. Although the replica ID is a flexible ID and, therefore, can be defined by the schema for the community, we recommend a 16-byte GUID. The format of a replica ID that is passed to a Sync Framework method must match the format specified by the provider. Managed code The format is specified by the ReplicaIdFormat property of the SyncIdFormatGroup class. The ID is represented by the SyncId class. Unmanaged code The format is specified by the replicaId field of the ID_PARAMETERS Structure structure. The ID is represented by the SYNC_ID structure.
Current tick count	Is the current tick count for the replica. Be aware that this is a conceptual number and can be inferred from the latest local version in the per-item knowledge or some other monotonically increasing value available to the replica. For example, a replica could use the current clock time as long as it can prevent that value from being reset. Managed code Represented by a UInt64. Unmanaged code Represented by a ULONGLONG.
Replica key map	Is a mapping between replica IDs and 4-byte keys. Because of the repeated occurrences of replica IDs in the metadata (recommended to be 16-byte GUIDs), it is more efficient to represent the IDs by using a table to map replica IDs down to 4-byte keys. These keys are then used elsewhere where references to particular replicas are required. Managed code Represented by using ReplicaKeyMap. Unmanaged code Represented by using IReplicaKeyMap.
Current knowledge	Is the summary of the version information that the replica knows for the specified scope. Replica knowledge is manipulated through the metadata services and should not be manipulated directly. Managed code Represented by using SyncKnowledge. Unmanaged code Represented by using ISyncKnowledge.
Forgotten knowledge	Enables a replica to detect that a partner replica does not know about items that have been deleted. This can occur when the tombstones for those items have been cleaned up. Forgotten knowledge is manipulated through the metadata services. Managed code Represented by using ForgottenKnowledge. Unmanaged code Represented by using IForgottenKnowledge.
Conflict log	Is a log of conflicts that occurred when conflicts were detected after change enumeration and were not resolved. Replicas are required to keep a conflict log only if conflicts are saved during synchronization. The representation of a conflict log is determined by the replica and access to this log does not have to be provided to Sync Framework. However, when a change applier is used, Sync Framework can help to maintain the conflict log. For more information, see Logging and Managing Conflicts.
Tombstone log	Stores information about the deletion of items from a replica so that delete changes are correctly propagated in the synchronization communities and deleted items are not accidentally reintroduced. Replicas are required to keep a tombstone log. Representation of a tombstone log is determined by the replica, and access to this log does not have to be provided to Sync Framework. For more information, see Managing Tombstones.

Required Metadata for Each Item

Each item that is to be synchronized must have the set of metadata shown in the following table.

Metadata element	Description
Global ID	Is an identifier for an item stored in a replica. Because the replica is responsible for generating the global IDs, the replica can allocate global IDs that make enumeration more efficient. For example, a community can define its global ID format to be a GUID that is preceded by an 8-byte prefix. The prefix can then be used to control the sort order of the global IDs. This enables the providers to more easily use ranges to enumerate changes, and because one range can contain a large number of items, the knowledge structure can be more compact when items are represented as ordered groups. For more information on global ID formats, see Flexible IDs. Managed code The format is specified by the ItemIdFormat property of the SyncIdFormatGroup class. The ID is represented by the SyncId class. Unmanaged code The format is specified by the itemId field of the ID_PARAMETERS Structure structure. The ID is represented by the SYNC_ID structure.
Current version	Is the last updated version for a particular item. The current version contains the key of the replica that most recently updated the item, and the tick count of the replica when the change was made. This version is stored per change unit when an item uses change units. For example, a contact might have distinct change unit version numbers for the address and telephone number fields. Managed code Represented by SyncVersion. Unmanaged code Represented by SYNC_VERSION.
Creation version	Is the version when the item was created. The creation version contains the key of the replica that created the item, and the tick count of the replica when the item was created. Managed code Represented by SyncVersion. Unmanaged code Represented by SYNC_VERSION.

Global ID

Is an identifier for an item stored in a replica. Because the replica is responsible for generating the global IDs, the replica can allocate global IDs that make enumeration more efficient. For example, a community can define its global ID format to be a GUID that is preceded by an 8-byte prefix. The prefix can then be used to control the sort order of the global IDs. This enables the providers to more easily use ranges to enumerate changes, and because one range can contain a large number of items, the knowledge structure can be more compact when items are represented as ordered groups. For more information on global ID formats, see Flexible IDs.

Managed code The format is specified by the ItemIdFormat property of the SyncIdFormatGroup class. The ID is represented by the SyncId class.

Unmanaged code The format is specified by the itemId field of the ID_PARAMETERS Structure structure. The ID is represented by the SYNC_ID structure.

Current version

Is the last updated version for a particular item. The current version contains the key of the replica that most recently updated the item, and the tick count of the replica when the change was made.

This version is stored per change unit when an item uses change units. For example, a contact might have distinct change unit version numbers for the address and telephone number fields.

Managed code Represented by SyncVersion.

Unmanaged code Represented by SYNC_VERSION.

Creation version

Is the version when the item was created. The creation version contains the key of the replica that created the item, and the tick count of the replica when the item was created.

Managed code Represented by SyncVersion.

Unmanaged code Represented by SYNC_VERSION.

Storage Requirements

Because the replica determines the format for the global ID, the amount of space that is required to store the metadata for each item varies. However, when the recommended format of a GUID plus an 8-byte prefix is used, the total amount of storage that is required is 48 bytes, as shown in the following table.

Item	Bytes
Global ID	24 (GUID + 8-byte prefix)
Current version	12 (4-byte replica key + 8-byte tick count)
Creation version	12 (4-byte replica key + 8-byte tick count)
	48 bytes total

Metadata for Constraint Conflicts

When constraint conflicts are resolved by merging the items in conflict, additional metadata is required for the merged items. For more information, see Detecting and Resolving Constraint Conflicts.

Metadata for Custom Filters

When custom filters are used, additional metadata is required for each replica and each item. For more information, see Filtering Synchronization Data.