HOW TO：篩選列舉變更單位

發行項
10/17/2009

本主題描述如何使用 Managed 語言來篩選 Sync Framework 同步處理提供者 (同步處理自訂資料存放區中的資料) 所列舉的變更單位。

本主題假設您對於 C# 和 Microsoft .NET Framework 概念有基本的了解。

本主題的範例將重點放在下列 Sync Framework 類別和成員：

了解變更單位篩選

變更單位篩選會將同步處理資料限制為變更單位的子集，例如，只同步處理連絡人的名稱和電話號碼欄位，並忽略剩餘的變更單位。當複寫只儲存針對範圍內的項目所定義的變更單位子集時，變更單位篩選將會很實用。

Sync Framework 會提供 ChangeUnitListFilterInfo 物件來定義要包含在變更列舉中的變更單位清單。同步處理應用程式可以使用應用程式與提供者之間適用的任何機制來設定篩選，也可以在這兩個提供者之間交涉篩選。如需交涉篩選的詳細資訊，請參閱篩選同步處理資料。

定義了變更單位篩選之後，當 Sync Framework 呼叫來源提供者的 LoadChangeData 時，它只會針對位於篩選中的變更單位要求資料。

目的地提供者接收和套用變更的方式與處理標準變更批次的方式完全相同，不過傳送至 SaveChangeWithChangeUnits 的資料只包含位於篩選中的變更單位。

組建需求

.NET Framework 2.0 或更新版本。
Microsoft.Synchronization 的參考。
Microsoft.Synchronization.MetadataStorage 的參考。

範例

本主題的範例程式碼將示範如何使用中繼資料儲存服務來產生變更批次，以便篩選變更批次所包含的變更單位。這個範例中的複寫是一個文字檔，這個檔案會將連絡人資訊儲存為以逗號分隔的值清單。要同步處理的項目是這個檔案中所包含的連絡人。此篩選會定義為只包含連絡人的名稱和電話號碼欄位。

設定篩選

來源提供者會實作一個公用方法，讓應用程式設定變更單位篩選，以便定義列舉變更時要包含的連絡人欄位。

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;
}

同步處理應用程式會將來源提供者建立成本機提供者，並且使用 SetContactFieldsToInclude 方法來指定列舉變更時只要包含名稱和電話號碼欄位。此外，這個應用程式也會建立目的地提供者並執行同步處理。

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");
}

列舉篩選的變更批次

來源提供者會實作 GetChangeBatch，如此一來，如果已經指定了篩選，它就會使用中繼資料儲存服務來產生篩選的變更批次。這項作業是透過建立 ChangeUnitListFilterInfo 物件，並以要包含的指定變更單位清單來初始化此物件完成的。篩選資訊會傳遞給 ReplicaMetadata 物件的 GetFilteredChangeBatch 方法。中繼資料儲存服務不需要回呼提供者來判斷要在篩選中包含的項目，因此系統會針對 filterCallback 參數指定 null。

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;
}

後續的步驟

接著，您可能會想要將篩選交涉新增至提供者，讓它能夠與目的地提供者通訊，以便確立要用於變更列舉的篩選。如需如何交涉篩選的詳細資訊，請參閱 HOW TO：交涉篩選。

請參閱

概念

程式設計一般標準的自訂提供者工作
 篩選同步處理資料

共用方式為