مشاركة عبر

ترحيل من مكتبة معالج موجز التغيير إلى Azure Cosmos DB .NET V3 SDK

  • مقالة

ينطبق على: NoSQL

توضح هذه المقالة الخطوات المطلوبة لترحيل التعليمات البرمجية لتطبيق موجود يستخدم مكتبة معالج موجز التغيير إلى ميزة موجز التغيير في أحدث إصدار من عدة تطوير البرامج .NET (يشار إليها أيضاً باسم .NET V3 SDK).

تغييرات التعليمات البرمجية المطلوبة

يشمل .NET V3 SDK عدة تغييرات فاصلة، وفيما يلي الخطوات الرئيسية لترحيل التطبيق لديك:

  1. تحويل DocumentCollectionInfo المثيلات إلى Container مراجع للحاويات المراقبة والمؤجرة.
  2. يجب تحديث التخصيصات التي تستخدم WithProcessorOptions لكي تستخدم WithLeaseConfiguration وWithPollInterval للفترات الزمنية، وWithStartTime لوقت البدء، وWithMaxItems لتحديد الحد الأقصى لعدد العناصر.
  3. قم بتعيين processorName على GetChangeFeedProcessorBuilder لمطابقة القيمة التي تم تكوينها على 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، فاستخدم واجهة برمجة تطبيقات الإعلامات.

  • IChangeFeedObserver.OpenAsync يمكن استبداله ب WithLeaseAcquireNotification.
  • IChangeFeedObserver.CloseAsync يمكن استبداله ب WithLeaseReleaseNotification.
  • IHealthMonitor.InspectAsync يمكن استبداله ب WithErrorNotification.

حاوية الحالة والتأجير

على غرار مكتبة معالج موجز التغيير، تستخدم ميزة موجز التغيير في NET V3 SDK حاوية تأجير لتخزين الحالة. ومع ذلك، فإن المخططات مختلفة.

سيقوم معالج موجز التغيير SDK V3 بالكشف عن أي حالة مكتبة قديمة وترحيلها إلى المخطط الجديد تلقائياً عند تنفيذ التعليمات البرمجية للتطبيق الذي تم ترحيله لأول مرة.

يمكنك إيقاف التطبيق بأمان باستخدام التعليمات البرمجية القديمة وترحيل التعليمات البرمجية إلى الإصدار الجديد وبدء تشغيل التطبيق الذي تم ترحيله وسيتم جمع أي تغييرات حدثت أثناء إيقاف التطبيق ومعالجتها بواسطة الإصدار الجديد.

الموارد الإضافية

الخطوات التالية

يمكنك الآن المتابعة لمعرفة المزيد حول معالج موجز التغيير في المقالات التالية: