Partager via

Procédure : filtrer des éléments énumérés

  • Article

Cette rubrique explique comment utiliser un langage managé pour filtrer les éléments énumérés par un fournisseur de synchronisation Sync Framework qui synchronise les données à partir d'un magasin de données personnalisé.

Cette rubrique suppose une connaissance de base des concepts C# et Microsoft .NET Framework.

Les exemples de cette rubrique reposent sur les classes et les membres Sync Framework suivants :

Présentation du filtrage d'éléments

Un filtre d'élément limite les modifications d'élément qui sont envoyées par le fournisseur de source pendant l'énumération des modifications, par exemple le fait d'envoyer uniquement des fichiers .txt dans un dossier de fichiers, en ignorant les fichiers d'autres types. Les éléments ne doivent pas changer de façon à provoquer l'inclusion de l'élément dans le filtre ou son exclusion du filtre. Les filtres d'élément sont simples à utiliser, mais les métadonnées utilisées pour la synchronisation augmentent proportionnellement au nombre d'éléments qui sont dans l'étendue de la synchronisation. Si le stockage pose un problème, les filtres personnalisés sont appropriés. Pour plus d'informations sur le filtrage personnalisé, consultez Filtrage des données de synchronisation.

La façon dont les éléments sont filtrés est définie à l'extérieur de Sync Framework, en général par le développeur du fournisseur ou un tiers. Le filtre peut être défini par l'application de synchronisation à l'aide d'un mécanisme approprié entre l'application et le fournisseur, mais il peut aussi être négocié entre les deux fournisseurs. Pour plus d'informations sur la négociation de filtres, consultez Filtrage des données de synchronisation.

Le fournisseur de destination reçoit et applique des modifications de la même façon que pour un lot de modifications standard. Il ne requiert aucune action spéciale pour prendre en compte le filtrage.

Configuration de build

Exemple

L'exemple de code dans cette rubrique indique comment implémenter un filtre d'élément simple et comment utiliser le service de stockage des métadonnées pour produire un lot de modifications filtré. Dans cet exemple, le réplica est un fichier texte qui stocke des coordonnées sous la forme d'une liste de valeurs séparées par des virgules. Les éléments à synchroniser sont les contacts contenus dans ce fichier. Le filtre est défini de façon à inclure uniquement les contacts qui ont un champ de date de naissance qui est inférieur à la valeur spécifiée par l'application.

Définition du filtre

Le fournisseur de source implémente une méthode publique qui permet à l'application de configurer un filtre qui définit la valeur maximale pour le champ de date de naissance. Tout contact avec une valeur supérieure à cette valeur dans le champ de date de naissance ne sera pas inclus dans un lot de modifications.

public void SetMaximumBirthdateFilter(DateTime maxBirthdateFilter)
{
    // Store the fact that a filter is set, and the value of the filter.
    _isFiltered = true;
    _maxBirthdateFilter = maxBirthdateFilter;
}

L'application de synchronisation crée le fournisseur de source comme fournisseur local et utilise la méthode SetMaximumBirthdateFilter pour spécifier la date de naissance maximale à inclure lors de l'énumération des modifications. L'application crée également le fournisseur de destination et effectue la synchronisation.

private void SynchronizeWithItemFiltering(ContactStore localStore, ContactStore remoteStore, SyncDirectionOrder syncDir)
{
    // Create the local provider and set the item filter.
    // The filter is ignored when the provider is the destination provider.
    SyncProvider localProvider = new ContactsProviderItemFiltering(localStore);
    // Only include contacts with a birthdate before January 1, 2000.
    ((ContactsProviderItemFiltering)localProvider).SetMaximumBirthdateFilter(
        new DateTime(2000, 1, 1));

    // Create the remote provider and do not set a filter.
    SyncProvider remoteProvider = new ContactsProviderItemFiltering(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");
}

Énumération d'un lot de modifications filtré

Le fournisseur de source implémente GetChangeBatch afin que, lorsqu'un filtre a été spécifié, il utilise le service de stockage des métadonnées pour produire un lot de modifications filtré. Cette opération est effectuée en créant un objet ItemListFilterInfo et en le passant à la méthode GetFilteredChangeBatch de l'objet ReplicaMetadata.

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;

    // Use the metadata storage service to get a batch of changes.
    ChangeBatch retrievedBatch;
    if (_isFiltered)
    {
        // If a filter is set, get a filtered change batch from the metadata storage service.
        // The BirthdateFilterCallback method indicates whether an item passes the filter.
        ItemListFilterInfo filterInfo = new ItemListFilterInfo(IdFormats);
        retrievedBatch = _ContactStore.ContactReplicaMetadata.GetFilteredChangeBatch(batchSize, destinationKnowledge,
            filterInfo, BirthdateFilterCallback);
    }
    else
    {
        retrievedBatch = _ContactStore.ContactReplicaMetadata.GetChangeBatch(batchSize, destinationKnowledge);
    }

    return retrievedBatch;
}

Pour déterminer si un élément est inclus dans le filtre, la méthode GetFilteredChangeBatch prend un délégué ItemFilterCallback implémenté par le fournisseur de source. Le service de stockage des métadonnées appelle ce délégué et utilise la valeur de retour pour inclure ou exclure des éléments dans le lot de modifications. Dans cet exemple, un élément est inclus dans le lot de modifications lorsque la valeur du champ de date de naissance est inférieure à la date de naissance maximale spécifiée.

public bool BirthdateFilterCallback(ItemMetadata itemMeta)
{
    // An item passes the filter only if its birthdate field is less than the maximum birthdate
    // specified by the filter.
    return (_ContactStore.ContactList[itemMeta.GlobalId].Birthdate < _maxBirthdateFilter);
}

Étapes suivantes

Vous pouvez ensuite ajouter la négociation de filtres à votre fournisseur afin qu'il puisse communiquer avec le fournisseur de destination pour décider du filtre à utiliser pour l'énumération des modifications. Pour plus d'informations sur la négociation de filtres, consultez Procédure : négocier un filtre.

Vous pouvez également utiliser un filtre personnalisé au lieu d'un filtre d'élément. L'implémentation des filtres personnalisés requiert plus de travail, mais ils sont beaucoup plus efficaces pour le suivi et la communication, ce qui fait que leur utilisation permet de minimiser les métadonnées de synchronisation. Pour plus d'informations sur les filtres personnalisés, consultez Filtrage des données de synchronisation.

Voir aussi

Concepts

Programmation de tâches de fournisseurs personnalisés standard courantes
Filtrage des données de synchronisation