Memigrasikan dari pustaka prosesor umpan perubahan ke Microsoft Azure Cosmos DB .NET V3 SDK

  • Artikel

BERLAKU UNTUK: NoSQL

Artikel ini menjelaskan langkah-langkah yang diperlukan untuk memigrasikan kode aplikasi yang menggunakan pustaka prosesor umpan perubahan ke fitur umpan perubahan di versi terbaru .NET SDK (juga disebut .NET V3 SDK).

Perubahan kode yang diperlukan

.NET V3 SDK memiliki beberapa terobosan, berikut ini adalah langkah-langkah kunci untuk memigrasikan aplikasi Anda:

  1. Konversikan DocumentCollectionInfo instans menjadi Container referensi untuk kontainer yang dipantau dan disewakan.
  2. Penyesuaian yang menggunakan WithProcessorOptions harus diperbarui untuk menggunakan WithLeaseConfiguration dan WithPollInterval untuk interval, WithStartTimeuntuk waktu mulai, dan WithMaxItems untuk menentukan jumlah item maksimum.
  3. Atur processorName pada GetChangeFeedProcessorBuilder untuk mencocokkan nilai yang dikonfigurasi pada ChangeFeedProcessorOptions.LeasePrefix, atau malah gunakan string.Empty.
  4. Perubahan tidak lagi dikirimkan sebagai IReadOnlyList<Document>, gantinya, itu adalah IReadOnlyCollection<T> di mana T sebagai jenis yang perlu Anda tentukan, tidak ada kelas item dasar lagi.
  5. Untuk menangani perubahan, Anda tidak lagi memerlukan implementasi IChangeFeedObserver, tetapi Anda perlu menetapkan delegasi. Delegasi dapat menjadi Fungsi statis atau, jika Anda perlu mempertahankan status di seluruh eksekusi, Anda dapat membuat kelas Anda sendiri dan meloloskan metode instans sebagai delegasi.

Misalnya, jika kode asli untuk membangun prosesor umpan perubahan terlihat sebagai berikut:

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

Kode yang dimigrasikan akan terlihat seperti:

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

Untuk delegasi, Anda dapat memiliki metode statis untuk menerima acara. Jika Anda menggunakan informasi dari IChangeFeedObserverContext, Anda dapat bermigrasi untuk menggunakan ChangeFeedProcessorContext:

  • ChangeFeedProcessorContext.LeaseToken dapat digunakan sebagai pengganti IChangeFeedObserverContext.PartitionKeyRangeId
  • ChangeFeedProcessorContext.Headers dapat digunakan sebagai pengganti IChangeFeedObserverContext.FeedResponse
  • ChangeFeedProcessorContext.Diagnostics berisi informasi mendetail tentang latensi permintaan untuk pemecahan masalah
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);
    }
}

Peristiwa dan pengamatan kesehatan

Jika sebelumnya Anda menggunakan IHealthMonitor atau anda memanfaatkan IChangeFeedObserver.OpenAsync dan IChangeFeedObserver.CloseAsync, gunakan Notifications API.

  • IChangeFeedObserver.OpenAsync dapat diganti dengan WithLeaseAcquireNotification.
  • IChangeFeedObserver.CloseAsync dapat diganti dengan WithLeaseReleaseNotification.
  • IHealthMonitor.InspectAsync dapat diganti dengan WithErrorNotification.

Kontainer status dan sewa

Mirip dengan pustaka prosesor umpan perubahan, fitur umpan perubahan di .NET V3 SDK menggunakan kontainer sewa untuk menyimpan status. Namun, skemanya berbeda.

Prosesor umpan perubahan SDK V3 akan mendeteksi status pustaka lama dan memigrasikannya ke skema baru secara otomatis setelah eksekusi pertama kode aplikasi yang dimigrasikan.

Anda dapat menghentikan aplikasi dengan aman menggunakan kode lama, memigrasikan kode ke versi baru, memulai aplikasi yang dimigrasikan, dan setiap perubahan yang terjadi saat aplikasi dihentikan, akan diambil dan diproses oleh versi baru.

Sumber Daya Tambahan:

Langkah berikutnya

Sekarang Anda bisa melanjutkan untuk mempelajari selengkapnya tentang prosesor umpan perubahan di artikel berikut ini: