استثناءات مراسلة ناقل خدمة Microsoft Azure (مهملة)
تسرد هذه المقالة استثناءات NET. التي تم إنشاؤها بواسطة واجهات برمجة التطبيقات NET. Framework.
في 30 سبتمبر 2026، سنتقاعد مكتبات SDK ناقل خدمة Azure WindowsAzure.ServiceBus وMicrosoft.Azure.ServiceBus و com.microsoft.azure.servicebus، والتي لا تتوافق مع إرشادات Azure SDK. سننهي أيضا دعم بروتوكول SBMP، لذلك لن تتمكن من استخدام هذا البروتوكول بعد 30 سبتمبر 2026. قم بالترحيل إلى أحدث مكتبات Azure SDK، والتي توفر تحديثات أمان هامة وقدرات محسنة، قبل ذلك التاريخ.
على الرغم من أنه لا يزال من الممكن استخدام المكتبات القديمة بعد 30 سبتمبر 2026، إلا أنها لن تتلقى بعد ذلك الدعم والتحديثات الرسمية من Microsoft. لمزيد من المعلومات، راجع إعلان إيقاف الدعم.
فئات الاستثناء
تنشئ واجهات برمجة تطبيقات المراسلة استثناءات يمكن أن تندرج في الفئات التالية، إلى جانب الإجراء المرتبط الذي يمكنك اتخاذه لمحاولة إصلاحها. يمكن أن يختلف معنى الاستثناء وأسبابه وفقاً لنوع كيان المراسلة:
- خطأ ترميز المستخدم (System.ArgumentException، System.InvalidOperationException، System.OperationCanceledException، System.Runtime.Serialization.SerializationException). الإجراء العام: حاول إصلاح التعليمة البرمجية قبل المتابعة.
- خطأ في الإعداد/التكوين (Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException، System.UnauthorizedAccessException. الإجراء العام: راجع التكوين الخاص بك وقم بالتغيير إذا لزم الأمر.
- استثناءات عابرة (Microsoft.ServiceBus.Messaging.MessagingException، Microsoft.ServiceBus.Messaging.ServerBusyException، Microsoft.ServiceBus.Messaging.MessagingCommunicationException). الإجراء العام: أعد محاولة العملية أو قم بإعلام المستخدمين. يمكن تكوين الفئة
RetryPolicy
في عدة تطوير برامج العميل لمعالجة عمليات إعادة المحاولة تلقائياً. لمزيد من المعلومات، راجع إرشادات إعادة المحاولة. - استثناءات أخرى (System.Transactions.TransactionException، System.TimeoutException، Microsoft.ServiceBus.Messaging.MessageLockLostException، Microsoft.ServiceBus.Messaging.SessionLockLostException). الإجراء العام: خاص بنوع الاستثناء؛ راجع الجدول في القسم التالي:
هام
- لا يعيد ناقل خدمة Microsoft Azure محاولة أي عملية في حالة وجود استثناء عندما تكون العملية في نطاق المعاملة.
- للحصول على إرشادات إعادة المحاولة الخاصة ناقل خدمة Azure، راجع إعادة محاولة إرشادات ناقل خدمة Microsoft Azure.
أنواع الاستثناءات
يسرد الجدول التالي أنواع استثناء المراسلة وأسبابه، ويلاحظ الإجراء المقترح الذي يمكنك اتخاذه.
نوع الاستثناء | الوصف/السبب/الأمثلة | الإجراء المقترح | ملاحظة حول إعادة المحاولة التلقائية/الفورية |
---|---|---|---|
TimeoutException | لم يستجب الخادم للعملية المطلوبة خلال الوقت المحدد، والذي يتم التحكم فيه بواسطة OperationTimeout. ربما يكون الخادم قد أكمل العملية المطلوبة. يمكن أن يحدث بسبب الشبكة أو التأخيرات الأخرى في البنية الأساسية. | تحقق من حالة النظام من أجل التناسق وأعد المحاولة إذا لزم الأمر. راجع استثناءات المهلة. | قد تساعد إعادة المحاولة في بعض الحالات؛ إضافة منطق إعادة المحاولة إلى التعليمات البرمجية. |
InvalidOperationException | عملية المستخدم المطلوبة غير مسموح بها داخل الخادم أو الخدمة. انظر رسالة الاستثناء للحصول على التفاصيل. على سبيل المثال، يقوم الخيار Complete ()بإنشاء هذا الاستثناء إذا تم استلام الرسالة في وضع ReceiveAndDelete. | تحقق من التعليمة البرمجية والوثائق. تأكد من صحة العملية المطلوبة. | إعادة المحاولة لا تساعد. |
OperationCanceledException | جرت محاولة لاستدعاء عملية على عملية تم إغلاقه بالفعل أو إجهاضه أو التخلص منه. في حالات نادرة، يتم بالفعل التخلص من العملية المحيطة. | تحقق من التعليمة البرمجية وتأكد من أنه لا يستدعي عمليات على كائن تم التخلص منه. | إعادة المحاولة لا تساعد. |
UnauthorizedAccessException | تعذر على العنصر TokenProvider الحصول على رمز مميز، أو أن الرمز المميز غير صالح أو أن الرمز المميز لا يحتوي على المطالبات المطلوبة لإجراء العملية. | تأكد من إنشاء موفر الرمز المميز بالقيم الصحيحة. تحقق من تكوين خدمة التحكم بالوصول. | قد تساعد إعادة المحاولة في بعض الحالات؛ إضافة منطق إعادة المحاولة إلى التعليمات البرمجية. |
ArgumentException ArgumentNullException ArgumentOutOfRangeException |
هناك وسيطة واحدة أو أكثر غير صالحة تم توفيرها للطريقة. يحتوي URI الذي تم توفيره إلى NamespaceManager أو Create على مقاطع المسار. مخطط URI المقدم إلى NamespaceManager أو Create غير صالح. قيمة الخاصية أكبر من 32 كيلوبايت. |
تحقق من كود الاستدعاء وتأكد من صحة المعطيات. | إعادة المحاولة لا تساعد. |
MessagingEntityNotFoundException | الكيان المرتبط بالعملية غير موجود أو تم حذفه. | تأكد من وجود الكيان. | إعادة المحاولة لا تساعد. |
MessageNotFoundException | محاولة تلقي رسالة برقم تسلسل معين. لم يتم العثور على هذه الرسالة. | تأكد من عدم تلقي الرسالة بالفعل. تحقق من قائمة انتظار الرسائل المهملة لمعرفة ما إذا كانت الرسالة غير مفعلة. | إعادة المحاولة لا تساعد. |
MessagingCommunicationException | لا يمكن للعميل إنشاء اتصال بناقل خدمة Azure. | تأكد من أن اسم المضيف المقدم صحيح وأن المضيف يمكن الوصول إليه. إذا كانت التعليمة البرمجية تعمل في بيئة مع جدار حماية/وكيل، فتأكد من أن نسبة استخدام الشبكة إلى مجال ناقل خدمة Azure/عنوان IP والمنافذ غير محظورة. |
قد تساعد إعادة المحاولة في حالة وجود مشكلات اتصال متقطعة. |
ServerBusyException | الخدمة غير قادرة على معالجة الطلب في الوقت الحالي. | يمكن للعميل الانتظار لفترة من الوقت، ثم إعادة محاولة العملية. | قد يعيد العميل المحاولة بعد فاصل زمني معين. إذا أدت إعادة المحاولة إلى استثناء مختلف، فتحقق من سلوك إعادة المحاولة لهذا الاستثناء. |
MessagingException | استثناء المراسلة العامة التي قد يتم طرحها في الحالات التالية: جرت محاولة لإنشاء QueueClient باستخدام اسم أو مسار ينتمي إلى نوع كيان مختلف (على سبيل المثال، موضوع). يتم إجراء محاولة لإرسال رسالة أكبر من 256 كيلو بايت. واجه الخادم أو الخدمة خطأ أثناء معالجة الطلب. انظر رسالة الاستثناء للحصول على التفاصيل. إنه عادة استثناء عابر.تم إنهاء الطلب بسبب تقييد مساحة الاسم الخاصة بك. رمز الخطأ: 50001، 50002، 50008. |
تحقق من التعليمة البرمجية وتأكد من استخدام العناصر القابلة للتسلسل فقط لنص الرسالة (أو استخدم محول تسلسلي مخصص). تحقق من الوثائق الخاصة بأنواع القيم المدعومة للخصائص واستخدم الأنواع المدعومة فقط. تحقق من الخاصية IsTransient. إذا كانت true، فيمكنك إعادة محاولة العملية. |
إذا كان الاستثناء بسبب التقييد، فانتظر لبضع ثوانٍ ثم أعد محاولة العملية مرة أخرى. سلوك إعادة المحاولة غير محدد وقد لا يفيد في السيناريوهات الأخرى. |
MessagingEntityAlreadyExistsException | محاولة إنشاء كيان باسم مستخدم بالفعل بواسطة كيان آخر في مساحة اسم الخدمة هذه. | احذف الكيان الحالي أو اختر اسماً مختلفاً للكيان الذي سيتم إنشاؤه. | إعادة المحاولة لا تساعد. |
QuotaExceededException | وصل كيان المراسلة إلى الحد الأقصى المسموح به من الحجم، أو تم تجاوز الحد الأقصى لعدد الاتصالات بمساحة الاسم. | قم بإنشاء مساحة في الكيان من خلال تلقي رسائل من الكيان أو قوائمه الفرعية. راجع QuotaExceededException. | قد تساعد إعادة المحاولة إذا تمت إزالة الرسائل في هذه الأثناء. |
RuleActionException | يعيد ناقل خدمة Azure هذا الاستثناء إذا حاولت إنشاء إجراء قاعدة غير صالح. يقوم ناقل خدمة Azure بإرفاق هذا الاستثناء برسالة غير مفعلة في حالة حدوث خطأ أثناء معالجة إجراء القاعدة لتلك الرسالة. | تحقق من إجراء القاعدة للتأكد من الصحة. | إعادة المحاولة لا تساعد. |
FilterException | يعيد ناقل خدمة Azure هذا الاستثناء إذا حاولت إنشاء عامل تصفية غير صالح. يقوم ناقل خدمة Azure بإرفاق هذا الاستثناء برسالة غير مفعلة في حالة حدوث خطأ أثناء معالجة عامل تصفية تلك الرسالة. | تحقق من عامل التصفية للتأكد من الصحة. | إعادة المحاولة لا تساعد. |
SessionCannotBeLockedException | محاولة قبول جلسة مع معرف جلسة معين، ولكن الجلسة مؤمنة حالياً من قبل عميل آخر. | تأكد من إلغاء تأمين الجلسة من قبل عملاء آخرين. | قد تساعد إعادة المحاولة إذا تم إصدار الجلسة في الفترة المؤقتة. |
TransactionSizeExceededException | الكثير من العمليات جزء من العملية. | تقليل عدد العمليات التي هي جزء من هذه العملية. | إعادة المحاولة لا تساعد. |
MessagingEntityDisabledException | طلب عملية وقت التشغيل على كيان معطل. | تفعيل الكيان. | قد تساعد إعادة المحاولة إذا تم تنشيط الكيان في الفترة المؤقتة. |
NoMatchingSubscriptionException | يقوم ناقل خدمة Microsoft Azure بإرجاع هذا الاستثناء إذا أرسلت رسالة إلى موضوع تم تمكين التصفية المسبقة فيه ولم تتطابق أي من عوامل التصفية. | تأكد من تطابق عامل تصفية واحد على الأقل. | إعادة المحاولة لا تساعد. |
MessageSizeExceededException | تتجاوز البيانات الأساسية للرسالة حد 256 كيلوبايت. هذا الحد الذي يبلغ 256 كيلوبايت مخصص للرسائل الإجمالية، والتي يمكن أن تتضمن خصائص النظام وأي حمل إضافي لـ NET. | قم بتقليل حجم بيانات الرسالة الأساسية، ثم أعد محاولة العملية. | إعادة المحاولة لا تساعد. |
TransactionException | العملية المحيطة (Transaction.Current ) غير صالحة. ربما تم إكماله أو إجهاضه. قد يوفر الاستثناء الداخلي معلومات إضافية. |
إعادة المحاولة لا تساعد. | |
TransactionInDoubtException | تتم محاولة إجراء عملية على عملية موضع شك، أو يتم إجراء محاولة لتثبيت العملية وتصبح العملية موضع شك. | يجب أن يتعامل تطبيقك مع هذا الاستثناء (كحالة خاصة)، حيث قد تكون المعاملة قد تم تنفيذها بالفعل. | - |
QuotaExceededException
يشير QuotaExceededException إلى أنه تم تجاوز حصة كيان معين.
إشعار
للحصول على حصص ناقل خدمة Microsoft Azure، راجع الحصص النسبية.
قوائم الانتظار والموضوعات
بالنسبة لقوائم الانتظار والموضوعات، غالباً ما يكون حجم قائمة الانتظار. تحتوي خاصية رسالة الخطأ على مزيد من التفاصيل، كما في المثال التالي:
Microsoft.ServiceBus.Messaging.QuotaExceededException
Message: The maximum entity size has been reached or exceeded for Topic: 'xxx-xxx-xxx'.
Size of entity in bytes:1073742326, Max entity size in bytes:
1073741824..TrackingId:xxxxxxxxxxxxxxxxxxxxxxxxxx, TimeStamp:3/15/2013 7:50:18 AM
تنص الرسالة على أن الموضوع تجاوز حد حجمه، في هذه الحالة 1 غيغابايت (الحد الأقصى للحجم الافتراضي).
مساحة الاسم
لمساحات الأسماء، يمكن أن تشير QuotaExceedException إلى أن تطبيق قد تجاوز الحد الأقصى لعدد الاتصالات إلى مساحة اسم. على سبيل المثال:
Microsoft.ServiceBus.Messaging.QuotaExceededException: ConnectionsQuotaExceeded for namespace xxx.
<tracking-id-guid>_G12 --->
System.ServiceModel.FaultException`1[System.ServiceModel.ExceptionDetail]:
ConnectionsQuotaExceeded for namespace xxx.
أسباب شائعة
هناك سببان شائعان لهذا الخطأ: قائمة انتظار الرسائل المهملة، وأجهزة استقبال الرسائل غير الوظيفية.
قائمة انتظار غير مفعلة فشل قارئ إكمال الرسائل ويتم إرجاع الرسائل إلى قائمة الانتظار/الموضوع عند انتهاء صلاحية التأمين. يمكن أن يحدث إذا واجه القارئ استثناء يمنعه من استدعاء BrokeredMessage.Complete. بعد قراءة رسالة 10 مرات، ينتقل إلى قائمة انتظار غير مفعلة بشكل افتراضي. يتم التحكم في هذا السلوك بواسطة الخاصية QueueDescription.MaxDeliveryCount ولديه قيمة افتراضية 10. بينما تتراكم الرسائل في قائمة الانتظار غير المفعلة، فإنها تأخذ مساحة.
لحل المشكلة، اقرأ وأكمل الرسائل من قائمة الانتظار غير المفعلة كما تفعل من أي قائمة انتظار أخرى. يمكنك استخدام الأسلوب FormatDeadLetterPath للمساعدة في تنسيق مسار قائمة الانتظار غير المفعلة.
توقف جهاز الاستقبال. توقف المتلقي عن تلقي الرسائل من قائمة انتظار أو اشتراك. الطريقة لتعريف هذا هو أن ننظر إلى الخاصية QueueDescription.MessageCountDetails، التي تعرض التوزيع الكامل للرسائل. إذا كانت الخاصية ActiveMessageCount عالية أو متزايدة، فلن تتم قراءة الرسائل بالسرعة التي تتم كتابتها بها.
TimeoutException
يشير TimeoutException إلى أن العملية التي بدأها المستخدم تستغرق وقتاً أطول من مهلة العملية.
يجب عليك التحقق من قيمة الخاصية ServicePointManager.DefaultConnectionLimit، كما يمكن أن يؤدي أيضاً الوصول إلى هذا الحد إلى TimeoutException.
من المتوقع أن تحدث المهلات أثناء عمليات الصيانة أو فيما بينها مثل تحديثات خدمة ناقل خدمة Azure (أو) تحديثات نظام التشغيل على الموارد التي تقوم بتشغيل الخدمة. أثناء تحديثات نظام التشغيل، يتم نقل الكيانات ويتم تحديث العقد أو إعادة تشغيلها، ما قد يؤدي إلى انقضاء المهلات. للحصول على تفاصيل اتفاقية على مستوى الخدمة (SLA) لخدمة ناقل خدمة Azure، راجع SLA لناقل خدمة Microsoft Azure.
قوائم الانتظار والموضوعات
بالنسبة إلى قوائم الانتظار والموضوعات، يتم تحديد المهلة إما في الخاصية MessagingFactorySettings.OperationTimeout، كجزء من سلسلة الاتصال، أو من خلال ServiceBusConnectionStringBuilder. قد تختلف رسالة الخطأ نفسها، لكنها تحتوي دائماً على قيمة المهلة المحددة للعملية الحالية.
MessageLockLostException
السبب
يتم طرح MessageLockLostException عند تلقي رسالة باستخدام وضع تلقي PeekLock وتنتهي صلاحية التأمين الذي يحمله العميل على جانب الخدمة.
قد تنتهي صلاحية التأمين على رسالة لأسباب مختلفة:
- انتهت صلاحية مؤقت التأمين قبل أن يتم تجديده من قبل تطبيق العميل.
- حصل تطبيق العميل على التأمين وحفظه في مخزن مستمر ثم تم إعادة تشغيله. بمجرد إعادة التشغيل، نظر تطبيق العميل إلى الرسائل الطائرة وحاول إكمالها.
قد تتلقى أيضا هذا الاستثناء في السيناريوهات التالية:
- تحديث الخدمة
- تحديث نظام التشغيل
- تغيير الخصائص على الكيان (قائمة الانتظار والموضوع والاشتراك) أثناء الاحتفاظ بالقفل.
الحل
عندما يتلقى تطبيق عميل MessageLockLostException، فإنه لم يعد قادرا على معالجة الرسالة. قد يفكر تطبيق العميل اختياريا في تسجيل الاستثناء للتحليل، ولكن يجب على العميل التخلص من الرسالة.
نظرا لأن التأمين على الرسالة قد انتهت صلاحيته، فإنه سيعود إلى قائمة الانتظار (أو الاشتراك) ويمكن معالجته بواسطة تطبيق العميل التالي الذي يتلقى المكالمات.
إذا تجاوز MaxDeliveryCount، فقد يتم نقل الرسالة إلى DeadLetterQueue.
SessionLockLostException
السبب
يتم طرح SessionLockLostException عند قبول جلسة وتنتهي صلاحية التأمين الذي يحتفظ به العميل على جانب الخدمة.
قد تنتهي صلاحية التأمين على جلسة العمل لأسباب مختلفة:
- انتهت صلاحية مؤقت التأمين قبل أن يتم تجديده من قبل تطبيق العميل.
- حصل تطبيق العميل على التأمين وحفظه في مخزن مستمر ثم تم إعادة تشغيله. بمجرد إعادة التشغيل، نظر تطبيق العميل إلى الرسائل الطائرة وحاول معالجة الرسائل في هذه الجلسات.
قد تتلقى أيضا هذا الاستثناء في السيناريوهات التالية:
- تحديث الخدمة
- تحديث نظام التشغيل
- تغيير الخصائص على الكيان (قائمة الانتظار والموضوع والاشتراك) أثناء الاحتفاظ بالقفل.
الحل
عندما يتلقى تطبيق عميل SessionLockLostException، فإنه لم يعد قادرا على معالجة الرسائل في جلسة العمل. قد يفكر تطبيق العميل في تسجيل الاستثناء للتحليل، ولكن يجب على العميل التخلص من الرسالة.
نظرا لأن التأمين على جلسة العمل قد انتهت صلاحيته، فإنه سيعود إلى قائمة الانتظار (أو الاشتراك) ويمكن تأمينه بواسطة تطبيق العميل التالي الذي يقبل الجلسة. نظراً لأن تأمين الجلسة يحتفظ به تطبيق عميل واحد في أي وقت معين، فإن المعالجة بالترتيب مضمونة.
SocketException
السبب
يتم طرح SocketException في الحالات التالية:
- عندما تفشل محاولة اتصال لأن المضيف لم يستجيب بشكل صحيح بعد وقت محدد (رمز خطأ TCP 10060).
- فشل اتصال تم تأسيسه بسبب فشل المضيف المتصل في الاستجابة.
- حدث خطأ أثناء معالجة الرسالة أو تجاوز المهلة من قبل المضيف البعيد.
- مشكلة مورد الشبكة الأساسية.
الحل
تشير أخطاء SocketException إلى أن استضافة الجهاز الظاهري للتطبيقات غير قادر على تحويل الاسم <mynamespace>.servicebus.windows.net
إلى عنوان IP المطابق.
تحقق لمعرفة ما إذا كان الأمر التالي ينجح في التعيين إلى عنوان IP.
PS C:\> nslookup <mynamespace>.servicebus.windows.net
والتي يجب أن توفر مخرجات مثل:
Name: <cloudappinstance>.cloudapp.net
Address: XX.XX.XXX.240
Aliases: <mynamespace>.servicebus.windows.net
إذا لم يتم حل الاسم أعلاه إلى IP والاسم المستعار لمساحة الاسم، فتحقق من مسؤول الشبكة لمزيد من التحقيق. يتم تحليل الاسم من خلال خادم DNS عادةً ما يكون مورداً في شبكة العميل. إذا تم تحليل DNS بواسطة Azure DNS، فاتصل بدعم Azure.
إذا كان تحليل الاسم يعمل كما هو متوقع، فتحقق مما إذا كان يسمح بالاتصالات ناقل خدمة Azure هنا.
MessagingException
السبب
MessagingException هو استثناء عام قد يتم طرحه لأسباب مختلفة. بعض الأسباب هي:
- يتم إجراء محاولة لإنشاء QueueClient على موضوع أو اشتراك.
- حجم الرسالة المرسلة أكبر من الحد الأقصى للمستوى المحدد. اقرأ المزيد عن حصص وقيود ناقل خدمة Azure.
- تم إنهاء طلب محدد لطائرة البيانات (إرسال، استقبال، إكمال، تخلي) بسبب التقييد.
- مشاكل عابرة بسبب ترقيات الخدمة وإعادة التشغيل.
إشعار
قائمة الاستثناءات المذكورة أعلاه ليست شاملة.
الحل
تعتمد خطوات الحل على سبب طرح MessagingException.
- بالنسبة للمشكلات العابرة (حيث يتم تعيين isTransient إلى true) أو لمشكلات التقييد، قد تؤدي إعادة محاولة العملية إلى حلها. يمكن استخدام نهج إعادة المحاولة الافتراضي على SDK لهذا.
- بالنسبة لمشكلات أخرى، تشير التفاصيل في الاستثناء إلى أن خطوات المشكلة والدقة يمكن استنتاجها من نفس الشيء.
StorageQuotaExceededException
السبب
يتم إنشاء StorageQuotaExceedException عندما يتجاوز الحجم الإجمالي للكيانات في مساحة اسم متميزة الحد الأقصى 1 تيرابايت لكل وحدة مراسلة.
الحل
- زيادة عدد وحدات المراسلة المعينة لمساحة الاسم المميزة
- إذا كنت تستخدم بالفعل الحد الأقصى المسموح به لوحدات المراسلة لمساحة الاسم، فبادر بإنشاء مساحة اسم منفصلة.
الخطوات التالية
للحصول على مرجع واجهة برمجة تطبيقات ناقل خدمة Azure ".NET"، راجع مرجع Azure .NET API. للحصول على تلميحات حول استكشاف الأخطاء وإصلاحها، راجع دليل استكشاف الأخطاء وإصلاحها.