共用方式為

從變更摘要處理器程式庫移轉到 Azure Cosmos DB .NET V3 SDK

  • 發行項

適用於：NoSQL

本文將說明必要步驟，以將使用變更摘要處理器程式庫的現有應用程式程式碼移轉到最新版 .NET SDK (又稱 .NET V3 SDK) 中的變更摘要功能。

必要的程式碼變更

.NET V3 SDK 有數項重大變更，以下是移轉您應用程式的關鍵步驟：

  1. 將 DocumentCollectionInfo 執行個體轉換為受監視與租用容器的 Container 參考。
  2. WithProcessorOptions使用的自定義專案應更新為使用 WithLeaseConfiguration 和 WithPollInterval 間隔、 WithStartTime 開始時間，以及WithMaxItems定義專案計數上限。
  3. 在 GetChangeFeedProcessorBuilder 上設定 processorName 以符合於 ChangeFeedProcessorOptions.LeasePrefix 上設定的值，或是使用 string.Empty。
  4. 變更將不會再作為 IReadOnlyList<Document> 傳遞，而是 IReadOnlyCollection<T> (其中 T 是您需要定義的類型)，且不再有基底項目類別。
  5. 您不再需要實作 IChangeFeedObserver 才能處理變更，反之，您必須定義委派。 委派可以是靜態函式，或者，如果您需要維護跨執行的狀態，您可以建立自己的類別，並將執行個體方法傳遞為委派。

例如，如果建置變更摘要處理器的原始程式碼看起來如下所示：

ChangeFeedProcessorLibrary.DocumentCollectionInfo monitoredCollectionInfo = new ChangeFeedProcessorLibrary.DocumentCollectionInfo()
{
    DatabaseName = databaseId,
    CollectionName = Program.monitoredContainer,
    Uri = new Uri(configuration["EndPointUrl"]),
    MasterKey = configuration["AuthorizationKey"]
};

ChangeFeedProcessorLibrary.DocumentCollectionInfo leaseCollectionInfo = new ChangeFeedProcessorLibrary.DocumentCollectionInfo()
{
    DatabaseName = databaseId,
    CollectionName = Program.leasesContainer,
    Uri = new Uri(configuration["EndPointUrl"]),
    MasterKey = configuration["AuthorizationKey"]
};

ChangeFeedProcessorLibrary.ChangeFeedProcessorBuilder builder = new ChangeFeedProcessorLibrary.ChangeFeedProcessorBuilder();
var oldChangeFeedProcessor = await builder
    .WithHostName("consoleHost")
    .WithProcessorOptions(new ChangeFeedProcessorLibrary.ChangeFeedProcessorOptions
    {
        StartFromBeginning = true,
        LeasePrefix = "MyLeasePrefix",
        MaxItemCount = 10,
        FeedPollDelay = TimeSpan.FromSeconds(1)
    })
    .WithFeedCollection(monitoredCollectionInfo)
    .WithLeaseCollection(leaseCollectionInfo)
    .WithObserver<ChangeFeedObserver>()
    .BuildAsync();

移轉後的程式碼會看起來像這樣：

Container leaseContainer = client.GetContainer(databaseId, Program.leasesContainer);
Container monitoredContainer = client.GetContainer(databaseId, Program.monitoredContainer);
ChangeFeedProcessor changeFeedProcessor = monitoredContainer
    .GetChangeFeedProcessorBuilder<ToDoItem>("MyLeasePrefix", Program.HandleChangesAsync)
        .WithInstanceName("consoleHost")
        .WithLeaseContainer(leaseContainer)
        .WithMaxItems(10)
        .WithPollInterval(TimeSpan.FromSeconds(1))
        .WithStartTime(DateTime.MinValue.ToUniversalTime())
        .Build();

針對委派，您可以利用靜態方法來接收事件。 如果您要從 IChangeFeedObserverContext 取用資訊，您可以移轉以使用 ChangeFeedProcessorContext：

  • 可以使用 ChangeFeedProcessorContext.LeaseToken 代替 IChangeFeedObserverContext.PartitionKeyRangeId
  • 可以使用 ChangeFeedProcessorContext.Headers 代替 IChangeFeedObserverContext.FeedResponse
  • ChangeFeedProcessorContext.Diagnostics 包含關於疑難排解要求延遲的詳細資訊
static async Task HandleChangesAsync(ChangeFeedProcessorContext context, IReadOnlyCollection<ToDoItem> changes, CancellationToken cancellationToken)
{
    Console.WriteLine($"Started handling changes for lease {context.LeaseToken}...");
    Console.WriteLine($"Change Feed request consumed {context.Headers.RequestCharge} RU.");
    // SessionToken if needed to enforce Session consistency on another client instance
    Console.WriteLine($"SessionToken ${context.Headers.Session}");

    // We may want to track any operation's Diagnostics that took longer than some threshold
    if (context.Diagnostics.GetClientElapsedTime() > TimeSpan.FromSeconds(1))
    {
        Console.WriteLine($"Change Feed request took longer than expected. Diagnostics:" + context.Diagnostics.ToString());
    }

    foreach (ToDoItem item in changes)
    {
        Console.WriteLine($"\tDetected operation for item with id {item.id}, created at {item.creationTime}.");
        // Simulate work
        await Task.Delay(1);
    }
}

健康情況事件和可檢視性

如果您先前使用 IHealthMonitor，或使用了 IChangeFeedObserver.OpenAsync 和 IChangeFeedObserver.CloseAsync，請使用通知 API。

  • IChangeFeedObserver.OpenAsync 可取代為 WithLeaseAcquireNotification。
  • IChangeFeedObserver.CloseAsync 可取代為 WithLeaseReleaseNotification。
  • IHealthMonitor.InspectAsync 可取代為 WithErrorNotification。

狀態與租用容器

和變更摘要處理器程式庫相似，.NET V3 SDK 中的變更摘要功能會使用租用容器來儲存狀態。 不過，結構描述則有所差異。

SDK V3 變更摘要處理器會偵測出舊的程式庫狀態，並在第一次執行移轉的應用程式程式碼時，自動將該狀態移轉至新的結構描述。

您可以使用舊的程式碼安全地停止應用程式，並將程式碼移轉至新的版本，然後啟動移轉的應用程式，而在應用程式停止期間所發生的所有變更，都會由新的版本接手並處理。

其他資源

下一步

您現在可以在下列文章中繼續深入了解變更摘要處理器：