SqlMetadataStore.InitializeReplicaMetadata Method

Creates and initializes metadata for a replica in the metadata store, and returns a replica metadata object that is used to access the replica metadata.

Namespace: Microsoft.Synchronization.MetadataStorage
Assembly: Microsoft.Synchronization.MetadataStorage (in microsoft.synchronization.metadatastorage.dll)

Syntax

'Declaration
Public Overrides Function InitializeReplicaMetadata ( _
    idFormats As SyncIdFormatGroup, _
    replicaId As SyncId, _
    customItemFieldSchemas As IEnumerable(Of FieldSchema), _
    customIndexedFieldSchemas As IEnumerable(Of IndexSchema) _
) As ReplicaMetadata
'Usage
Dim instance As SqlMetadataStore
Dim idFormats As SyncIdFormatGroup
Dim replicaId As SyncId
Dim customItemFieldSchemas As IEnumerable(Of FieldSchema)
Dim customIndexedFieldSchemas As IEnumerable(Of IndexSchema)
Dim returnValue As ReplicaMetadata

returnValue = instance.InitializeReplicaMetadata(idFormats, replicaId, customItemFieldSchemas, customIndexedFieldSchemas)
public override ReplicaMetadata InitializeReplicaMetadata (
    SyncIdFormatGroup idFormats,
    SyncId replicaId,
    IEnumerable<FieldSchema> customItemFieldSchemas,
    IEnumerable<IndexSchema> customIndexedFieldSchemas
)
public:
virtual ReplicaMetadata^ InitializeReplicaMetadata (
    SyncIdFormatGroup^ idFormats, 
    SyncId^ replicaId, 
    IEnumerable<FieldSchema^>^ customItemFieldSchemas, 
    IEnumerable<IndexSchema^>^ customIndexedFieldSchemas
) override
public ReplicaMetadata InitializeReplicaMetadata (
    SyncIdFormatGroup idFormats, 
    SyncId replicaId, 
    IEnumerable<FieldSchema> customItemFieldSchemas, 
    IEnumerable<IndexSchema> customIndexedFieldSchemas
)
public override function InitializeReplicaMetadata (
    idFormats : SyncIdFormatGroup, 
    replicaId : SyncId, 
    customItemFieldSchemas : IEnumerable<FieldSchema>, 
    customIndexedFieldSchemas : IEnumerable<IndexSchema>
) : ReplicaMetadata

Parameters

  • idFormats
    The ID format schema for the provider.
  • replicaId
    The replica ID that is associated with this metadata.
  • customItemFieldSchemas
    The collection of schema information for the custom metadata fields for each metadata item. Can be a null reference (Nothing in Visual Basic) when there are no custom metadata fields.
  • customIndexedFieldSchemas
    The list of index schemas that can be used to more efficiently find items in the metadata store. Can be a null reference (Nothing in Visual Basic) when there are no custom indexes.

Return Value

The replica metadata object that is used to access the replica metadata in the metadata store.

Exceptions

Exception type Condition

ObjectDisposedException

This object has been disposed or was not initialized correctly.

ArgumentNullException

idFormats or replicaId is a null reference (Nothing in Visual Basic).

ArgumentException

Any of the custom field names in customItemFieldSchemas is 0 length.

NullReferenceException

Any of the custom field names in customItemFieldSchemas is a null reference (Nothing in Visual Basic).

MetadataFieldNotFoundException

A field listed in customIndexedFieldSchemas does not exist in customItemFieldSchemas.

SyncIdFormatMismatchException

The format of replicaId does not match the format that is specified in idFormats.

ArgumentOutOfRangeException

The length of an ID specified by idFormats is more than 8000 bytes.

InvalidOperationException

A metadata store has not been opened or created.

ReplicaMetadataAlreadyExistsException

Replica metadata already exists in the metadata store for the specified replicaId.

Remarks

This method is used to create a new set of replica metadata in the metadata store. To access existing replica metadata in a metadata store, use GetReplicaMetadata.

This method returns the implementation of the ReplicaMetadata abstract class that is provided by the metadata storage service. This abstract class can be used to access replica metadata that is stored in the Sync Framework database file.

A set of custom fields can be defined for item metadata by using customItemFieldSchemas. Each field consists of a unique string name and a value. These fields can store any additional metadata about an item that is not otherwise supported by the default set of item metadata. The fields can be accessed through various methods on ItemMetadata, such as ItemMetadata.GetByteField or Microsoft.Synchronization.MetadataStorage.ItemMetadata.SetCustomField.

A set of index schemas can be defined by using customIndexedFieldSchemas so that sets of custom fields can be used as indexes to efficiently find items in the metadata store. An index schema can be defined as unique to ensure that the index defines one item. Each field that is contained in an index schema must also exist in the custom field schema that is defined for the replica. Index fields can be used in methods such as ReplicaMetadata.FindItemMetadataByIndexedField and ReplicaMetadata.FindItemMetadataByUniqueIndexedFields.

Example

The following example initializes replica metadata in a SqlMetadataStore object when replica metadata does not already exist. The example specifies a set of custom fields in the replica metadata and also specifies that the custom fields are used as a unique index.

public void NewStore(string StoreName, MetadataStore metaStore, bool metaStoreIsNew)
{
    // Close the current store. This is necessary to release the ReplicaMetadata object held by this object.
    Close(true);

    // Keep the store name for later use.
    _StoreName = StoreName;

    // The absolute path of the item store is used as the replica ID.
    string StoreAbsPath = Path.GetFullPath(StoreName);

    // Get or initialize replica metadata in the metadata store.
    _ContactMetadataStore = metaStore;
    if (!metaStoreIsNew)
    {
        // The metadata store exists, so open it and get the replica metadata for the current replica.
        // The replica ID is the absolute path of the item store.
        _ContactReplicaMetadata = _ContactMetadataStore.GetReplicaMetadata(ContactIdFormatGroup,
            new SyncId(StoreAbsPath));

        // Read the contacts from the item store and the metadata store and save them in two
        // in-memory lists. These lists are modified in memory by the methods in this object 
        // and committed to the disk when SaveChanges is called.
        StreamReader contactReader;
        contactReader = File.OpenText(StoreName);

        Contact contact = ReadNextContact(contactReader);
        while (null != contact)
        {
            ItemMetadata itemMeta = FindMetadata(contact);

            _ContactList.Add(itemMeta.GlobalId, contact);
            _ContactItemMetaList.Add(itemMeta.GlobalId, itemMeta);

            contact = ReadNextContact(contactReader);
        }

        contactReader.Close();
    }
    else
    {
        // The metadata store does not exist, so create a new one.

        // Create custom fields for First Name, Last Name, and Phone Number. These will be used
        // as unique index fields for identifying items between the metadata store and the item store.
        FieldSchema[] CustomFields = 
        {
            new FieldSchema(FirstNameField, typeof(string), 100),
            new FieldSchema(LastNameField, typeof(string), 100),
            new FieldSchema(PhoneNumberField, typeof(string), 20)
        };

        // Specify the custom fields as a unique index.
        string[] IndexFields = { FirstNameField, LastNameField, PhoneNumberField };
        IndexSchema[] Indexes = 
        {
            new IndexSchema(IndexFields, true)
        };

        // Create the metadata for the replica in the metadata store.
        _ContactReplicaMetadata = _ContactMetadataStore.InitializeReplicaMetadata(
            ContactIdFormatGroup, new SyncId(StoreAbsPath), CustomFields, Indexes);

        // Set the provider version
        _ContactReplicaMetadata.ProviderVersion = (uint)ContactsProviderVersion.ContactsProvider_v1;
    }
}

See Also

Reference

SqlMetadataStore Class
SqlMetadataStore Members
Microsoft.Synchronization.MetadataStorage Namespace