Share via

Migrowanie z biblioteki procesora zestawienia zmian do zestawu SDK platformy .NET w wersji 3 usługi Azure Cosmos DB

  • Artykuł

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 powodujących niezgodność. Poniżej przedstawiono kluczowe kroki migracji aplikacji:

  1. Przekonwertuj DocumentCollectionInfo wystąpienia na Container odwołania do monitorowanych kontenerów i dzierżaw.
  2. Dostosowania, których używaszWithProcessorOptions, powinny być aktualizowane tak, aby używały WithPollIntervalWithLeaseConfiguration interwałów, WithStartTimeczasu rozpoczęcia oraz WithMaxItems aby zdefiniować maksymalną liczbę elementów.
  3. processorName Ustaw wartość włączoneGetChangeFeedProcessorBuilder, aby dopasować wartość skonfigurowaną w elemocie ChangeFeedProcessorOptions.LeasePrefixlub użyj string.Empty w inny sposób.
  4. Zmiany nie są już dostarczane jako , IReadOnlyList<Document>zamiast tego IReadOnlyCollection<T> jest to miejsce, w którym T należy zdefiniować typ, nie ma już klasy elementu podstawowego.
  5. Aby obsłużyć zmiany, nie potrzebujesz już implementacji IChangeFeedObserverelementu , zamiast tego musisz zdefiniować delegata. Delegat może być funkcją statyczną lub, jeśli musisz zachować stan między wykonaniami, możesz utworzyć własną klasę i przekazać metodę wystąpienia jako delegata.

Jeśli na przykład oryginalny kod do skompilowania procesora zestawienia 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 informacji z programu IChangeFeedObserverContext , możesz przeprowadzić migrację, aby użyć polecenia 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żywano IHealthMonitor narzędzia lub korzystasz IChangeFeedObserver.OpenAsync z interfejsu IChangeFeedObserver.CloseAsyncAPI powiadomień i , użyj interfejsu API powiadomień.

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

Kontener stanu i dzierżawy

Podobnie jak w bibliotece procesora zestawienia zmian funkcja zestawienia zmian w zestawie .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 zestawienia zmian w następujących artykułach: