Vorgehensweise: Filtern aufgelisteter Änderungseinheiten

Artikel
11/02/2009

In diesem Thema wird erläutert, wie Sie eine verwaltete Sprache zum Filtern von Änderungseinheiten verwenden, die von einem Sync Framework-Synchronisierungsanbieter aufgelistet werden, der Daten aus einem benutzerdefinierten Datenspeicher synchronisiert.

Dieses Thema setzt grundlegende Kenntnisse über C#- und Microsoft .NET Framework-Konzepte voraus.

In den Beispielen dieses Themas liegt der Schwerpunkt auf den folgenden Sync Framework-Klassen und -Membern:

Grundlegendes zum Filtern von Änderungseinheiten

Änderungseinheitsfilter schränken Synchronisierungsdaten auf eine Teilmenge von Änderungseinheiten ein, sodass z. B. nur die Felder für Name und Telefonnummer eines Kontakts synchronisiert und die verbleibenden Änderungseinheiten ignoriert werden. Ein Änderungseinheitsfilter ist nützlich, wenn ein Replikat nur eine Teilmenge der Änderungseinheiten speichert, die für die Elemente im Bereich definiert wurde.

Sync Framework stellt das ChangeUnitListFilterInfo-Objekt bereit, um die Liste der Änderungseinheiten zu definieren, die in einer Änderungsenumeration enthalten sein sollen. Der Filter kann durch die Synchronisierungsanwendung mit einem entsprechenden Mechanismus zwischen der Anwendung und dem Anbieter festgelegt oder zwischen zwei Anbietern ausgehandelt werden. Weitere Informationen zum Aushandeln von Filtern finden Sie unter Filtern von Synchronisierungsdaten.

Wenn ein Änderungseinheitsfilter definiert wird, fordert Sync Framework beim Aufrufen von LoadChangeData des Quellenanbieters nur Daten für die Änderungseinheiten an, die im Filter enthalten sind.

Das Empfangen und Anwenden von Änderungen durch den Zielanbieter erfolgt auf die gleiche Weise wie bei einem Standardänderungsbatch, mit dem Unterschied, dass Daten, die an SaveChangeWithChangeUnits gesendet wurden, nur die im Filter enthaltenen Änderungseinheiten enthalten.

Erstellungsanforderungen

.NET Framework 2.0 oder höher.
Verweis auf Microsoft.Synchronization.
Verweis auf Microsoft.Synchronization.MetadataStorage.

Beispiel

Der Beispielcode in diesem Thema zeigt die Verwendung des Metadaten-Speicherdiensts zur Erstellung eines Änderungsbatchs, der die im Änderungsbatch enthaltenen Änderungseinheiten filtert. Das Replikat in diesem Beispiel ist eine Textdatei, die Kontaktinformationen als Liste mit durch Trennzeichen getrennten Werten speichert. Die zu synchronisierenden Elemente sind in dieser Datei enthaltene Kontakte. Der Filter ist so definiert, dass nur die Felder für Name und Telefonnummer des Kontakts enthalten sind.

Festlegen des Filters

Der Quellenanbieter implementiert eine öffentliche Methode, mit der die Anwendung einen Änderungseinheitsfilter festlegen kann, der definiert, welche Kontaktfelder in die Änderungsenumeration aufgenommen werden.

public void SetContactFieldsToInclude(Contact.ChangeUnitFields[] includedFields)
{
    // Translate the array of fields to a list of IDs.
    _includedChangeUnits = new List<SyncId>(includedFields.Length);
    for (int iField = 0; iField < includedFields.Length; iField++)
    {
        _includedChangeUnits.Add(new SyncId((byte)includedFields[iField]));
    }

    _isFiltered = true;
}

Die Synchronisierungsanwendung erstellt den Quellenanbieter als lokalen Anbieter und verwendet die SetContactFieldsToInclude-Methode, um anzugeben, dass in die Auflistung von Änderungen nur die Felder für Name und Telefonnummer einbezogen werden. Die Anwendung erstellt außerdem den Zielanbieter und führt die Synchronisierung durch.

private void SynchronizeWithChangeUnitFiltering(ContactStore localStore, ContactStore remoteStore, SyncDirectionOrder syncDir)
{
    // Create the local provider and set the change unit filter.
    // The filter is ignored when the provider is the destination provider.
    SyncProvider localProvider = new ContactsProviderChangeUnitFiltering(localStore);
    // Only include name and phone number fields.
    Contact.ChangeUnitFields[] includedFields = new Contact.ChangeUnitFields[2];
    includedFields[0] = Contact.ChangeUnitFields.NameCU;
    includedFields[1] = Contact.ChangeUnitFields.PhoneCU;
    ((ContactsProviderChangeUnitFiltering)localProvider).SetContactFieldsToInclude(includedFields);
    
    // Create the remote provider and do not set a filter.
    SyncProvider remoteProvider = new ContactsProviderChangeUnitFiltering(remoteStore);

    // Create the synchronization orchestrator and set the providers and synchronization direction.
    SyncOrchestrator orchestrator = new SyncOrchestrator();
    orchestrator.LocalProvider = localProvider;
    orchestrator.RemoteProvider = remoteProvider;
    orchestrator.Direction = syncDir;

    string msg;
    try
    {
        // Synchronize data between the two providers.
        SyncOperationStatistics stats = orchestrator.Synchronize();

        // Display statistics for the synchronization operation.
        msg = "Synchronization succeeded!\n\n" +
            stats.DownloadChangesApplied + " download changes applied\n" +
            stats.DownloadChangesFailed + " download changes failed\n" +
            stats.UploadChangesApplied + " upload changes applied\n" +
            stats.UploadChangesFailed + " upload changes failed";
    }
    catch (Exception ex)
    {
        msg = "Synchronization failed! Here's why: \n\n" + ex.Message;
    }
    MessageBox.Show(msg, "Synchronization Results");
}

Auflisten eines gefilterten Änderungsbatchs

Der Quellenanbieter implementiert GetChangeBatch so, dass bei Angabe eines Filters der Metadaten-Speicherdienst zur Erstellung eines gefilterten Änderungsbatchs verwendet wird. Dies geschieht durch Erstellen eines ChangeUnitListFilterInfo-Objekts und die Initialisierung mit der angegebenen Liste der aufzunehmenden Änderungseinheiten. Die Filterinformationen werden an die GetFilteredChangeBatch-Methode des ReplicaMetadata-Objekts übergeben. Der Metadaten-Speicherdienst braucht keinen Rückruf an den Anbieter auszuführen, um zu ermitteln, was in den Filter aufgenommen werden soll, daher wird für den filterCallback-Parameter null festgelegt.

public override ChangeBatch GetChangeBatch(uint batchSize, SyncKnowledge destinationKnowledge, out object changeDataRetriever)
{
    // Return this object as the IChangeDataRetriever object that is called to retrieve item data.
    changeDataRetriever = this;

    ChangeBatch retrievedBatch;
    if (_isFiltered)
    {
        // Use the metadata storage service to get a filtered batch of changes.
        ChangeUnitListFilterInfo filterInfo = new ChangeUnitListFilterInfo(IdFormats, _includedChangeUnits, true);
        retrievedBatch = _ContactStore.ContactReplicaMetadata.GetFilteredChangeBatch(batchSize, destinationKnowledge,
            filterInfo, null);
    }
    else
    {
        // Use the metadata storage service to get a batch of changes.
        retrievedBatch = _ContactStore.ContactReplicaMetadata.GetChangeBatch(batchSize, destinationKnowledge);
    }
    
    return retrievedBatch;
}

Nächste Schritte

Im nächsten Schritt können Sie Ihrem Anbieter eine Filteraushandlung hinzufügen, sodass dieser mit dem Zielanbieter kommunizieren kann, um zu ermitteln, welcher Filter für die Änderungsauflistung verwendet wird. Weitere Informationen zum Aushandeln von Filtern finden Sie unter Vorgehensweise: Aushandeln eines Filters.

Siehe auch

Konzepte

Programmieren allgemeiner benutzerdefinierter Standardanbietertasks
Filtern von Synchronisierungsdaten

Freigeben über