مشاركة عبر

SDK لـ .NET معالج موجز التغيير: التنزيل وملاحظات حول الإصدار

  • مقالة

ينطبق على: NoSQL

الارتباطات
تنزيل SDK NuGet
مستندات API الوثائق المرجعية لواجهة برمجة التطبيقات المرجعية لمكتبة معالج موجز التغيير
‏‫بدء الاستخدام بدء استخدام معالج موجز التغيير .NET SDK
الإطار الحالي المدعوم مايكروسوفت .NET Framework 4.5مايكروسوفت.نت
كور

إشعار

إذا كنت تستخدم معالج موجز التغيير، يُرجى الاطلاع على أحدث إصدار 3.x من .NET SDK، والذي يحتوي على موجز تغيير مضمن في SDK.

ملاحظات الإصدار

سلسلة الإصدارات 2

2.5.0

  • تمت إضافة منشئ جديد للفئة Microsoft.Azure.Documents.ChangeFeedProcessor.Logging.TraceLogProvider التي تأخذ مثيلا ل System.Diagnostics.TraceSource كوسيطة. يسمح هذا بإنشاء TraceLogProvider، الذي يتم استخدامه للتتبع .net، برمجيا من مثيل مخصص TraceSource تمت تهيئته في التعليمات البرمجية المصدر. قبل هذا التغيير، كان من الممكن فقط تكوين تتبع .net باستخدام ملف App.config.

2.4.0

  • تمت إضافة دعم لمجموعات التأجير التي يمكن تقسيمها باستخدام مفتاح القسم المحدد باسم / partitionKey. قبل هذا التغيير، يجب تعريف مفتاح القسم الخاص بمجموعة التأجير على أنه /id.
  • يسمح هذا الإصدار باستخدام مجموعات التأجير مع واجهة برمجة التطبيقات ل Gremlin، حيث لا يمكن أن تحتوي مجموعات Gremlin على مفتاح قسم معرف على أنه /id.

2.3.2

  • تمت إضافة توافق متجر التأجير مع [V3 SDK الذي يتيح مسارات الترحيل السريعة. يمكن لأحد التطبيقات الانتقال إلى SDK الإصدار 3 والترحيل مرة أخرى إلى مكتبة معالج موجز التغيير دون فقد أي حالة.

2.3.1

  • تم تصحيح الحالة عند إرسال سبب الإغلاق FeedProcessing.ChangeFeedObserverCloseReason.Unknown إلى FeedProcessing.IChangeFeedObserver.CloseAsync إذا تعذر العثور على القسم أو إذا كانت النسخة المتماثلة الهدف غير محدثة بجلسة القراءة. في هذه الحالات، يتم استخدام أسباب الإغلاق FeedProcessing.ChangeFeedObserverCloseReason.ResourceGone وFeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable.
  • تمت إضافة سبب إغلاق جديد FeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable يتم إرساله لإغلاق مراقب موجز التغيير عندما لا تكون النسخة المتماثلة المستهدفة محدثة بجلسة القراءة.

2.3.0

  • تمت إضافة أسلوب ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory جديد والواجهة العامة المقابلة ICheckpointPartitionProcessorFactory. يسمح ذلك بتنفيذ واجهة IPartitionProcessor لاستخدام آلية نقاط التفتيش المضمنة. المصنع الجديد مشابه لـ IPartitionProcessorFactory الحالي، فيما عدا أن أسلوبه Createيأخذ المعلمة ILeaseCheckpointer أيضًا.
  • يمكن استخدام أحد الأسلوبين، إما ChangeFeedProcessorBuilder.WithPartitionProcessorFactory أو ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory لنفس مثيل ChangeFeedProcessorBuilder.

2.2.8

  • تحسينات الاستقرار والتشخيص:
    • تمت إضافة دعم لاكتشاف قراءة موجز التغيير التي تستغرق وقتاً طويلاً. عندما يستغرق وقتا أطول من القيمة المحددة بواسطة الخاصية ChangeFeedProcessorOptions.ChangeFeedTimeout ، يتم اتخاذ الخطوات التالية:
      • تم إحباط عملية قراءة موجز التغيير على القسم الذي به مشكلات.
      • يُسقط مثيل معالج موجز التغيير ملكية الإيجار الذي يُحدث المشكلة. سيتم انتقاء الإيجار الذي تم إسقاطه خلال خطوة الحصول على الإيجار التالي والتي سيتم إجراؤها بواسطة نفس مثيل معالج تغذية التغيير أو مثيل غيره. بهذه الطريقة، ستبدأ قراءة موجز التغيير من جديد.
      • يتم الإبلاغ عن مشكلة إلى مراقب السلامة. يقوم جهاز مراقبة السلامة الافتراضي بإرسال كافة المشكلات التي تم الإبلاغ عنها إلى سجل التعقب.
    • تمت إضافة خاصية عامة جديدة: ChangeFeedProcessorOptions.ChangeFeedTimeout. وتكون القيمة الافتراضية لهذه الخاصية 10 دقائق.
    • تمت إضافة قيمة تعداد عام جديدة: Monitoring.MonitoredOperation.ReadChangeFeed. عندما يتم تعيين قيمة HealthMonitoringRecord.Operation على Monitoring.MonitoredOperation.ReadChangeFeed، يشير ذلك إلى أن المشكلة السلامة تتعلق بقراءة موجز التغيير.

2.2.7

  • استراتيجية موازنة التحميل المحسنة للسيناريو عند الحصول على جميع عقود الإيجار تستغرق وقتا أطول من الفاصل الزمني لانتهاء صلاحية الإيجار، على سبيل المثال، بسبب مشكلات الشبكة:
    • في هذا السيناريو، يتم استخدام خوارزمية موازنة التحميل للنظر بشكل خاطئ في الإيجارات باعتبارها منتهية الصلاحية، مما يتسبب في السطو على الإيجارات من المالكين النشطين. قد يؤدي هذا إلى إعادة التوازن غير الضروري للعديد من الإيجارات.
    • تم إصلاح هذه المشكلة في هذا الإصدار من خلال تجنب إعادة المحاولة عند حدوث تعارض أثناء الحصول على عقد إيجار منتهي الصلاحية لم يغيره المالك وتأجيل الحصول على عقد إيجار منتهي الصلاحية إلى تكرار موازنة التحميل التالي.

2.2.6

  • تحسين التعامل مع استثناءات المراقب.
  • معلومات أكثر ثراء حول أخطاء المراقب:
    • عندما يتم إغلاق مراقب بسبب استثناء تم طرحه بواسطة ProcessChangesAsync من Observer، سيتلقى CloseAsync الآن معلمة السبب التي تم تعيينها على ChangeFeedObserverCloseReason.ObserverError.
    • تمت إضافة تتبعات لتحديد الأخطاء داخل كود المستخدم في المراقب.

2.2.5

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

2.2.4

  • تمت إضافة خاصية جديدة ChangeFeedProcessorOptions.StartContinuation لدعم بدء موجز التغيير من الرمز المميز لمتابعة الطلب. يستخدم هذا فقط عندما يكون جمع الإيجار فارغًا أو عندما لا يحتوي عقد الإيجار على مجموعة ContinuationToken. بالنسبة لعقود الإيجار في مجموعة التأجير التي تحتوي على مجموعة ContinuationToken، يتم استخدام ContinuationToken ويتم تجاهل ChangeFeedProcessorOptions.StartContinuation.

2.2.3

  • دعم إضافي لاستخدام مخزن مخصص للمحافظة على استمرارية الرموز المميزة لكل قسم.
    • على سبيل المثال، يمكن أن يكون متجر التأجير المخصص عبارة عن مجموعة تأجير Azure Cosmos DB مقسمة بأي طريقة مخصصة.
    • يمكن لمخازن التأجير المخصصة استخدام نقطة التوسعة الجديدة ChangeFeedProcessorBuilder.WithLeaseStoreManager (ILeaseStoreManager) وواجهة ILeaseStoreManager العامة.
    • تمت إعادة تشكيل واجهة ILeaseManager إلى واجهات أدوار متعددة.
  • تغيير طفيف في التفاصيل: تمت إزالة نقطة التوسعة ChangeFeedProcessorBuilder.WithLeaseManager (ILeaseManager)، استخدم ChangeFeedProcessorBuilder.WithLeaseStoreManager (ILeaseStoreManager) بدلاً من ذلك.

2.2.2

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

2.2.1

  • حساب مقدر ثابت للحسابات ذات مناطق كتابة متعددة وتنسيق رمز الجلسة الجديد.

2.2.0

  • دعم إضافي لمجموعات الإيجار المقسمة. يجب تحديد مفتاح القسم على أنه /id.
  • تغيير بسيط في التفصيل: تغيرت أساليب واجهة IChangeFeedDocumentClient وفئة ChangeFeedDocumentClient لتشمل معلمات RequestOptions وCancellationToken. IChangeFeedDocumentClient هي نقطة تمدد متقدمة تتيح لك توفير تنفيذ مخصص لعميل المستند لاستخدامه مع تغيير معالج موجز التغيير، على سبيل المثال، تحسين DocumentClient واعتراض جميع المكالمات إليه للقيام بمزيد من التتبع ومعالجة الأخطاء وما إلى ذلك. مع هذا التحديث، يجب تغيير التعليمات البرمجية التي تنفذ IChangeFeedDocumentClient لتضمين معلمات جديدة في التطبيق.
  • تحسينات طفيفة في التشخيص.

2.1.0

  • تمت إضافة واجهة برمجة تطبيقات جديدة، مهمة <IReadOnlyList<RemainingPartitionWork >> IRemainingWorkEstimator.GetEstimatedRemainingWorkPerPartitionAsync (). يمكن استخدام هذا للحصول على العمل المقدر لكل قسم.
  • يدعم Microsoft.Azure.DocumentDB SDK الإصدار 2.0. يتطلب Microsoft.Azure.DocumentDB الإصدار 2.0 أو أحدث.

2.0.6

  • تمت إضافة خاصية ChangeFeedEventHost.HostName العامة للتوافق مع الإصدار 1.

2.0.5

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

2.0.4

  • GA SDK

الإصدار التجريبي من الإصدار 2.0.3

  • تم إصلاح المشكلات التالية:

    • عند حدوث انقسام في القسم، قد تكون هناك معالجة مكررة للمستندات التي تم تعديلها قبل التقسيم.
    • أرجع GetEstimatedRemainingWork API القيمة 0 في حالة عدم وجود عقود إيجار في مجموعة التأجير.

  • يتم الإعلان عن الاستثناءات التالية. يمكن للإضافات التي تقوم بتطبيق IPartitionProcessor طرح هذه الاستثناءات.

    • Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.LeaseLostException.
    • Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.PartitionException.
    • Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.PartitionNotFoundException.
    • Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.PartitionSplitException.

الإصدار التجريبي من الإصدار 2.0.2

  • تغييرات طفيفة في واجهة برمجة التطبيقات:
    • تمت إزالة ChangeFeedProcessorOptions.IsAutoCheckpointEnabled الذي تم تعليمه على أنه قديم.

الإصدار التجريبي من الإصدار 2.0.1

  • تحسينات الاستقرار:
    • التعامل بشكل أفضل مع تهيئة مخزن الإيجار. عندما يكون مخزن الإيجار فارغًا، يمكن لمثيل واحد فقط من المعالج تهيئته، بينما ينتظر الآخرون.
    • تجديد / تحرير عقد إيجار أكثر استقرارًا / كفاءة. تجديد عقد إيجار وتحرير قسم واحد مستقل عن تجديده. في الإصدار 1 تم ذلك بالتتابع لجميع الأقسام.
  • واجهة برمجة تطبيقات الإصدار 2 الجديدة:
    • نمط Builder لبناء مرن للمعالج: فئة ChangeFeedProcessorBuilder.
      • يمكن أن تأخذ أي مجموعة من المعلمات.
      • يمكن أن تأخذ مثيل DocumentClient للمراقبة و/ أو جمع الإيجار (غير متوفر في الإصدار 1).
    • IChangeFeedObserver.ProcessChangesAsync now takes CancellationToken.
    • IRemainingWorkEstimator - يمكن استخدام مقدر العمل المتبقي بشكل منفصل عن المعالج.
    • نقاط القابلية للتوسعة الجديدة:
      • IPartitionLoadBalancingStrategy - لموازنة التحميل المخصصة للأقسام بين مثيلات المعالج.
      • ILease، ILeaseManager - لإدارة عقود الإيجار المخصصة.
      • IPartitionProcessor - لإجراء تغييرات معالجة مخصصة على القسم.
  • تسجيل الدخول - يستخدم مكتبة LibLog.
  • متوافق مع الإصدارات السابقة بنسبة 100٪ مع واجهة برمجة التطبيقات الإصدار 1.
  • قاعدة كود جديدة.
  • متوافق مع إصدارات SQL .NET SDK الإصدار 1.21.1 والإصدارات الأحدث.

عوامل البناء الإصدار 1

1.3.3

  • تمت إضافة المزيد من التسجيل.
  • تم إصلاح تسرب DocumentClient عند استدعاء تقدير العمل المعلق عدة مرات.

1.3.2

  • إصلاحات في تقدير العمل المعلق.

⁦⁩⁦⁩1.3.1

  • تحسينات الاستقرار.
    • إصلاح للتعامل مع مشكلة المهام الملغاة التي قد تؤدي إلى توقف المراقبين في بعض الأقسام.
  • دعم نقاط التفتيش اليدوية.
  • متوافق مع إصدارات SQL .NET SDK الإصدار 1.21 والإصدارات الأحدث.

1.2.0

  • يضيف دعماً لـ .NET Standard 2.0. تدعم الحزمة الآن ألقاب إطار العمل netstandard2.0 وnet451.
  • متوافق مع إصدارات SQL .NET SDK الإصدار 1.17.0 والإصدارات الأحدث.
  • متوافق مع إصدارات SQL .NET SDK الإصدار 1.5.1 والإصدارات الأحدث.

1.1.1

  • يعمل على إصلاح مشكلة في حساب تقدير العمل المتبقي عندما كان موجز التغيير فارغاً أو لم يكن هناك عمل معلق.
  • متوافق مع إصدارات SQL .NET SDK الإصدار 1.13.2 والإصدارات الأحدث.

1.1.0

  • تمت إضافة طريقة للحصول على تقدير للعمل المتبقي المراد معالجته في موجز التغيير.
  • متوافق مع إصدارات SQL .NET SDK الإصدار 1.13.2 والإصدارات الأحدث.

1.0.0

  • GA SDK
  • متوافق مع إصدارات SQL .NET SDK الإصدار 1.14.1 والإصدارات الأقل.

تواريخ الإصدار وإيقاف الدعم

ستقدم Microsoft إشعاراً قبل 12 شهراً على الأقل من إنهاء العمل بأداة SDK من أجل تسهيل الانتقال إلى إصدار أحدث / مدعوم. تتم إضافة الميزات والوظائف والتحسينات الجديدة فقط إلى SDK الحالي؛ لذلك يوصى بالترقية دائماً إلى أحدث إصدار من SDK في أقرب وقت ممكن.

تحذير

بعد 31 أغسطس 2022، لن يقوم Azure Cosmos DB بإجراء إصلاحات الأخطاء وإضافة ميزات جديدة وتوفير الدعم للإصدارات 1.x من Azure Cosmos DB .NET أو .NET Core SDK لواجهة برمجة التطبيقات ل NoSQL. إذا كنت تفضل عدم الترقية، فسيستمر تقديم الطلبات المرسلة من الإصدار 1.x من SDK بواسطة خدمة Azure Cosmos DB.


إصدار تاريخ الإصدار تاريخ الإيقاف
2.5.0 15 مايو 2023 ---
2.4.0 6 مايو 2021 ---
2.3.2 11 أغسطس 2020 ---
2.3.1 30 يوليو 2020 ---
2.3.0 2 أبريل 2020 ---
2.2.8 28 أكتوبر 2019 ---
2.2.7 14 مايو 2019 ---
2.2.6 29 يناير 2019 ---
2.2.5 13 ديسمبر 2018 ---
2.2.4 29 نوفمبر 2018 ---
2.2.3 19 نوفمبر 2018 ---
2.2.2 31 أكتوبر 2018 ---
2.2.1 24 أكتوبر 2018 ---
1.3.3 8 مايو 2018 ---
1.3.2 18 أبريل 2018 ---
1.3.1 13 مارس 2018 ---
1.2.0 31 أكتوبر 2017 ---
1.1.1 29 أغسطس 2017 ---
1.1.0 13 أغسطس 2017 ---
1.0.0 07 يوليو 2017 ---

الأسئلة المتداولة

كيف سيتم إخطاري بانتهاء حزمة SDK؟

ستقدم Microsoft إشعاراً مسبقاً قبل 12 شهراً من انتهاء دعم SDK المتقاعد لتسهيل الانتقال السلس إلى SDK المدعوم. سنعلمك من خلال قنوات الاتصال المختلفة: مدخل Azure وتحديثات Azure والاتصال المباشر بمسؤولي الخدمة المعينين.

هل يمكنني تأليف تطبيقات باستخدام حزمة Azure Cosmos DB SDK التي سيتم إيقاف العمل بها خلال فترة 12 شهراً؟

نعم، ستكون قادراً على تأليف التطبيقات ونشرها وتعديلها باستخدام Azure Cosmos DB SDK الذي سيتم إيقافه خلال فترة الإشعار التي تبلغ 12 شهراً. نوصي بالترحيل إلى إصدار أحدث مدعوم من Azure Cosmos DB SDK خلال فترة الإشعار التي تبلغ 12 شهراً، حسب الاقتضاء.

بعد تاريخ التقاعد، ماذا يحدث للتطبيقات التي تستخدم Azure Cosmos DB SDK غير المدعوم؟

بعد تاريخ التقاعد، لن يقوم Azure Cosmos DB بعد الآن بإجراء إصلاحات للأخطاء أو إضافة ميزات جديدة أو تقديم الدعم لإصدارات SDK المتوقفة. إذا كنت تفضل عدم الترقية، فسيستمر تقديم الطلبات المرسلة من الإصدارات المتوقفة من SDK بواسطة خدمة Azure Cosmos DB.

ما إصدارات SDK التي ستحتوي على أحدث الميزات والتحديثات؟

ستتم إضافة الميزات والتحديثات الجديدة فقط إلى أحدث إصدار ثانوي من أحدث إصدار SDK رئيسي مدعوم. نوصي دائماً باستخدام أحدث إصدار للاستفادة من الميزات الجديدة وتحسينات الأداء وإصلاحات الأخطاء. إذا كنت تستخدم إصداراً قديماً غير متقاعد من SDK، فستظل طلباتك إلى Azure Cosmos DB تعمل، ولكن لن تتمكن من الوصول إلى أي إمكانات جديدة.

ماذا أفعل إذا لم أتمكن من تحديث طلبي قبل الموعد النهائي؟

نوصي بالترقية إلى أحدث إصدار من SDK في أقرب وقت ممكن. بعد وضع علامة على SDK للتقاعد، سيكون لديك 12 شهراً لتحديث تطبيقك. إذا لم تتمكن من التحديث بحلول تاريخ التقاعد، فسيستمر Azure Cosmos DB في تقديم الطلبات المرسلة من الإصدارات المتقاعدة من SDK، لذلك ستستمر تطبيقاتك قيد التشغيل. لكن Azure Cosmos DB لن يُجري إصلاحات للأخطاء أو يضيف ميزات جديدة أو يوفر دعماً لإصدارات SDK المتقاعدة.

إذا كانت لديك خطة دعم وتحتاج إلى دعم فني، فاتصل بنا عن طريق ملء بطاقة دعم.

كيف يمكنني طلب إضافة ميزات إلى SDK أو موصل؟

لا تتم دائماً إضافة ميزات جديدة إلى كل SDK أو موصل على الفور. إذا كانت هناك ميزة غير مدعمة وتريد إضافتها، يرجى إضافة تعليقات إلى منتدى المجتمع.

(راجع أيضًا )

لمعرفة المزيد حول Azure Cosmos DB، راجع صفحة خدمة Microsoft Azure Cosmos DB .