Udostępnij za pośrednictwem

Migrowanie z biblioteki procesora przepływu zmian do zestawu SDK .NET V3 usługi Azure Cosmos DB

DOTYCZY: NoSQL

W tym artykule opisano kroki wymagane do przeprowadzenia migracji kodu istniejącej aplikacji, który używa biblioteki procesora zestawienia zmian do funkcji zestawienia zmian w najnowszej wersji zestawu .NET SDK (nazywanego również zestawem SDK platformy .NET w wersji 3).

Wymagane zmiany kodu

Zestaw .NET V3 SDK zawiera kilka zmian łamiących zgodność. Oto kluczowe kroki do migracji aplikacji:

  1. Przekształć instancje DocumentCollectionInfo na odwołania Container dla monitorowanych i dzierżawionych kontenerów.
  2. Dostosowania, które używają WithProcessorOptions, powinny być aktualizowane do używania WithLeaseConfiguration i WithPollInterval dla interwałów, WithStartTimedla czasu rozpoczęcia oraz WithMaxItems do zdefiniowania maksymalnej liczby elementów.
  3. Ustaw processorName na GetChangeFeedProcessorBuilder tak, aby dopasować wartość skonfigurowaną w elemencie ChangeFeedProcessorOptions.LeasePrefix, lub użyj string.Empty w przeciwnym razie.
  4. Zmiany nie są już dostarczane jako IReadOnlyList<Document>. Zamiast tego jest używane IReadOnlyCollection<T>, gdzie T to typ, który należy zdefiniować. Nie ma już klasy elementu bazowego.
  5. Aby obsłużyć zmiany, nie potrzebujesz już implementacji elementu IChangeFeedObserver, zamiast tego musisz zdefiniować delegata. Delegat może być funkcją statyczną lub, jeśli musisz zachować stan pomiędzy uruchomieniami, możesz utworzyć własną klasę i przekazać metodę instancji jako delegata.

Jeśli na przykład oryginalny kod do utworzenia procesora strumienia zmian wygląda następująco:

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();

Zmigrowany kod będzie wyglądać następująco:

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();

Dla delegata możesz mieć statyczną metodę odbierania zdarzeń. Jeśli korzystasz z IChangeFeedObserverContext, możesz przejść do używania ChangeFeedProcessorContext.

  • ChangeFeedProcessorContext.LeaseToken można użyć zamiast IChangeFeedObserverContext.PartitionKeyRangeId
  • ChangeFeedProcessorContext.Headers można użyć zamiast IChangeFeedObserverContext.FeedResponse
  • ChangeFeedProcessorContext.Diagnostics zawiera szczegółowe informacje o opóźnieniu żądania na potrzeby rozwiązywania problemów
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);
    }
}

Zdarzenia dotyczące kondycji i możliwość obserwacji

Jeśli wcześniej używałeś IHealthMonitor lub korzystałeś z IChangeFeedObserver.OpenAsync i IChangeFeedObserver.CloseAsync, użyj interfejsu API powiadomień.

  • IChangeFeedObserver.OpenAsync można zastąpić WithLeaseAcquireNotification.
  • IChangeFeedObserver.CloseAsync można zastąpić WithLeaseReleaseNotification.
  • IHealthMonitor.InspectAsync można zastąpić WithErrorNotification.

Kontener stanowy i dzierżawowy

Podobnie jak w bibliotece procesora zestawienia zmian, funkcja w .NET V3 SDK używa kontenera dzierżawy do przechowywania stanu. Schematy są jednak różne.

Procesor zestawienia zmian zestawu SDK w wersji 3 wykryje każdy stary stan biblioteki i przeprowadzi migrację go do nowego schematu automatycznie po pierwszym wykonaniu zmigrowanego kodu aplikacji.

Aplikację można bezpiecznie zatrzymać przy użyciu starego kodu, zmigrować kod do nowej wersji, uruchomić zmigrowaną aplikację i wszelkie zmiany, które wystąpiły podczas zatrzymania aplikacji, zostaną pobrane i przetworzone przez nową wersję.

Dodatkowe zasoby

Następne kroki

Teraz możesz dowiedzieć się więcej o procesorze strumienia zmian w następujących artykułach.