استكشاف الأخطاء وإصلاحها
تشخيص الأخطاء الشائعة
كل رسالة أدناه هي النص الحرفي الذي ينتجه Doconut، مُنظمة حسب العرض. ابحث عن الخطأ الخاص بك، وطبق الإصلاح.
عارض لا يظهر شيئًا
منطقة عرض فارغة، وحدة تحكم المتصفح مليئة بأخطاء 404 لـ /doconut-res/...
UseDoconutResources() مفقود، أو موضوع بعد UseDoconut(). يجب أن يكون أولًا في خط الأنابيب.
العارض يُبلغ عن The viewer handler could not be reached (no response).
الطلب لم يتلق إجابة أبداً. سبب شائع هو BasePath يبدأ بـ /: يتحول '/doconut' إلى //doconut/DocImage.axd، وهو طلب إلى مضيف آخر. اكتبها بدون الشرطة المائلة في البداية (BasePath: 'doconut').
العارض يُبلغ عن Please make sure your middleware is configured.
نقطة نهاية الصفحة أجابت بـ 404: UseDoconut() غير مركبة في المكان الذي يشير إليه BasePath الخاص بالعميل. مع app.Map("/doconut", branch => branch.UseDoconut())، يستخدم العميل BasePath: 'doconut'.
HTTP 500 مع:
Session middleware not configured. Call UseSession() before UseDoconut().أمان الرمز المميز في Doconut (مفعل افتراضيًا) يحتاج إلى حالة جلسة ASP.NET. أضف builder.Services.AddSession() و app.UseSession() قبل فرع وسائط Doconut. حالة الجلسة تحتاج أيضًا إلى ذاكرة تخزين مؤقت: في تطبيق minimal-API أضف builder.Services.AddDistributedMemoryCache()، أو سيتوقف التطبيق عند بدء التشغيل مع Unable to resolve service for type 'IDistributedCache' (تطبيقات MVC و Razor Pages تسجل واحدة بالفعل).
صورة خطأ في منطقة الصفحة تعرض النص:
You Are Not Authorized To View This Page.تم فتح الرمز المميز بواسطة جلسة متصفح مختلفة. الأسباب الشائعة: ملف تعريف الارتباط للجلسة لا يصل إلى طلبات الصفحة (إعداد عبر الأصول، سياسة SameSite، عميل API بدون حاوية ملفات تعريف الارتباط)، أو أن التطبيق أعيد تشغيله (مفاتيح جلسة جديدة). هذا هو طبقة الأمان تعمل كما صُممت — راجع المفاهيم الأساسية → الجلسات والأمان. الرفض هو صورة تُقدم بحالة 200، لذا فإن المراقب الذي يتحقق من رموز الحالة فقط يعتبرها صفحة.
صورة خطأ تعرض النص:
Document session not found. Please re-open document.انتهت صلاحية الرمز المميز (نافذة منزلقة، الافتراضي 60 دقيقة — DocOptions.TimeOut) أو أُغلقت الجلسة. أعد فتح المستند للحصول على رمز مميز جديد.
الخادم سليم لكن الصفحة تتصرف بشكل غير صحيح — دون أي خطأ في أي مكان
هذه هي أوضاع الفشل التي يجب الشك فيها أولاً بعد نقل التطبيق إلى الأمام. الثلاثة جميعها تترك الخادم يعمل بشكل مثالي، وتعرض المستند بشكل صحيح، ولا تُبلغ عن أي شيء في وحدة تحكم المتصفح.
دوار تحميل مشغول لا يتوقف أبداً. تم إعلان ردود نداء العارض الخاصة بك كدوال عامة مسماة بعد معرف الحاوية — ctlDoc_OnViewerReady() وأصدقائه. العارض السابق كان يبحث عن تلك الأسماء؛ هذا لا يفعل ذلك. المعالج الذي كان سيخفي الدوار ببساطة لا يعمل أبداً. مرّر الدوال كخيارات بدلاً من ذلك:
function ctlDoc_OnViewerBusy() { /* اعرض مؤشر الانشغال الخاص بك */ }
function ctlDoc_OnViewerReady() { /* أخفِه */ }
function ctlDoc_Copy(text) { /* استخدم النص المنسوخ */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* أبلغ عن التقدم */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... خياراتك الحالية ...
onViewerBusy: ctlDoc_OnViewerBusy,
onViewerReady: ctlDoc_OnViewerReady,
onCopy: ctlDoc_Copy,
onAutoLoadStatus: ctlDoc_AutoLoadStatus
});المستند خلف الدوار سليم. قائمة الخيارات الكاملة موجودة في إعدادات العارض.
أيقونات العارض أو الواجهة مفقودة، الصفحات صحيحة بخلاف ذلك. ResPath فارغ أو يشير إلى جذر التطبيق — صحيح في المكتبة السابقة، خاطئ هنا. يجب أن يحدد البادئة التي يركّبها UseDoconutResources():
ResPath: 'doconut-res/images' // أو '<your ResourcesPath>/images'بلاطات مكسورة للصفحات اللاحقة عند الخدمة من تخزين مشترك. الصفحات التي لا تزال تُكتب تجيب بـ 202 Accepted. عميل بدون retryOn409: true يتعامل مع ذلك كصورة فاشلة. راجع النشر الموزع.
فشل فتح المستند
LicenseException مع رسالة رفض — تم العثور على ملف الترخيص لكنه رُفض (توقيع غير صالح، تم العبث به، مدرج على القائمة السوداء، أو بناء خارج نافذة الإصدار/التحديث للترخيص). هذه الحالة تمنع الفتح (فشل سريع) بدلاً من التحول إلى علامة مائية؛ اقرأ License.RejectionMessage للسبب.
LicenseException:
This document type requires the 'Dicom' plugin license.يتم التعامل مع الامتداد فقط عبر مكوّن إضافي (هنا: DICOM). المكوّن الإضافي مسجَّل، لكن لا ترخيص يمنح قدرته بعد الآن — عادةً ترخيص مؤقت انتهت صلاحيته بعد بدء التطبيق. قم بتثبيت ترخيص يمنحه وتحقق من IsCapabilityGranted(LicenseCapability.Dicom) على IDoconutLicenseService. عادةً ما يؤدي نقص أو عدم كفاية استحقاق غير مؤقت إلى فشل مبكر، أثناء AddDoconut().
FormatNotSupportedException:
Document format '<extension>' is not supported.لا يوجد عارض — مدمج، مكوّن إضافي، أو مخصص — يدعم هذا الامتداد. تحقق من قائمة الصيغ المدعومة؛ بالنسبة لصيغك الخاصة، يمكن لـ DoconutOptions.RegisterViewer إضافة واحدة.
InvalidDataException — محتوى الملف تالف أو لا يتطابق مع امتداده (مثلاً ملف تم إعادة تسميته). تحقق من صحة التحميلات قبل الفتح.
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().قمت بحل DocumentConverter دون تسجيل المكوّن الإضافي Converter.
فشل بدء التشغيل
InvalidOperationException يذكر مكوّنًا إضافيًا مسجَّلًا عبر AddPlugin — الترخيص غير المؤقت الحالي لا يمنح هذا المكوّن الإضافي القدرة. أزل التسجيل أو ثبّت ترخيصًا يمنحه. الترخيص المفقود وملف TRIAL القديم لا يمنحان أي قدرات للمكوّن الإضافي.
ArgumentException من AddDoconut():
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.تحقق من صحة خيارات الفشل السريع — أصلح المسار المخالف.
أخطاء البناء / التبعيات
الحزمة لن تُثبت نهائيًا — تستهدف Doconut.NETStandard
netstandard2.1، لذا يرفض NuGet مشروع .NET Framework. هذا ليس خطأ استعادة قابل للحل: لا يمكن لـ .NET Framework استهلاك netstandard2.1. استخدم حزمة Doconut.NETFramework بدلاً من ذلك.
خطأ المترجم CS1705، أو أثناء التشغيل عند فتح مستند:
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'قمت بتثبيت System.Text.Json أو System.Text.Encodings.Web بأقل من إصدارات 9.0.x المعتمدة من قبل Doconut.NETStandard. أزل التخفيض ودع NuGet يستعيد رسم الحزمة (System.Text.Json 9.0.0 وSystem.Text.Encodings.Web 9.0.0 كما هو معلن في الحزمة).
جدار من أخطاء التجميع يظهر مباشرةً بعد ترقية الحزمة — هذا متوقع.
الإصدار 26.8.0 يملك سطح API مختلف عن 26.7.0، وليس تحديثًا متوافقًا. معظم الأخطاء هي أسطر using التي انتقلت إلى مساحة الاسم الجذرية Doconut؛ عالجها عبر
الترحيل إلى .NET Standard 2.1 بدلاً من تصحيحها واحدةً تلو الأخرى.
TypeInitializationException على أول ملف عرض تقديمي:
Could not load ... System.Drawing.Common, Version=6.0.0.0محرك العرض يتطلب صراحةً System.Drawing.Common 6.0.0 (معلن من قبل الحزمة). لا تقم بإزالة أو تجاوز هذه الاعتمادية — كل محاولة فتح PPT/PPTX/PPS/POT/ODP ستفشل بدونها.
المخرجات تبدو خاطئة
الصفحات تحمل علامة مائية — التطبيق في حالة تقييم: لا يوجد ملف ترخيص، أو ترخيص مؤقت منتهي، أو نطاق غير صالح. تحت ترخيص مؤقت نشط، يتم وضع علامة مائية فقط على مخرجات المكوّن الإضافي. بناء تم إصداره بعد تاريخ اشتراك الترخيص المدفوع لا يحمل علامة مائية: الفتح يطرح LicenseException. افحص IDoconutLicenseService (License.IsLicenseFileFound، IsExpired، IsVersionValid، IsValidForDomain، License.RejectionMessage) — إشارة صفحة الترخيص إلى IDoconutLicenseService تُظهر نقطة نهاية جاهزة.
المستندات القديمة تُظهر نصًا مشوشًا — ترميزات صفحات الشيفرة لا تُحمَّل افتراضيًا. أضفها مرة واحدة عند بدء التشغيل:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);خطوط خاطئة أو مستبدلة — الخادم يفتقر إلى خطوط المستند. ثبِّتها، أو وجه FontFolders (على WordConfig/PptConfig) إلى مجلد يحتوي عليها.
تظهر تعليقة صورة في العارض لكن التصدير يحتوي على صندوق "Image blocked" — مضيف الصورة لديه عنوان خاص أو حلقة رجوع، ويُرفض الخادم جلبه. راجع التعليقات التوضيحية.
الميزة تعمل في التقييم، صامتة في الإنتاج
المفاجأة الكلاسيكية عند الانتقال إلى الإنتاج: ترخيص مؤقت نشط يمنح كل القدرة؛ ترخيصك المشتراة يمنح فقط ما اشتريت. يمكن أن تختفي حزم البحث والتعليق عندما تكون قدراتها غير موجودة. المبدل المسجل أو ملحقات DICOM مع ترخيص غير مؤقت غير كافٍ تفشل أثناء AddDoconut(). قارن IsCapabilityGranted(...) مع كل ميزة تقوم بتمكينها قبل النشر.
البحث لا يجد شيئًا (أو القليل جدًا)
- بالنسبة إلى PDF مباشر، لم يتم تمكين
AllowSearchعند وقت الفتح. Word وExcel وPowerPoint يعرضون نفس المفتاح عبرPdfConfigالمتداخلة الخاصة بهم. - المحتوى مُسح ضوئيًا/صورة فقط، لذا لا يحتوي البحث العادي على طبقة نصية للمطابقة. استخدم مصدرًا يحتوي نصًا أو إسقاط PDF يحافظ على النص.
- HTML وMS Project (MPP) غير قابلين للبحث في إعداداتهم الافتراضية — اضبط
DefaultRender = falseبحيث يتم عرضهم عبر إسقاط PDF بطبقة نصية أصلية. Word وExcel وPowerPoint وTXT وVisio والبريد الإلكتروني وEPUB وMHT يبحثون في إعداداتهم الافتراضية للكتالوج. objViewer.CanSearch()هوfalseبعد التهيئة — الصيغة المحلولة لا تملك مسار بحث قياسي. هذا الحكم منفصل عن ترخيص البحث؛ تحقق من كليهما.- الصفحة تقرأ القيمة المرجعة من
objViewer.Search(...)— العدد يصل في الوسيط الثالث، وهو رد نداء.
ما زلت عالقًا؟
عزل المشكلة مقابل تطبيق البداية السريعة الأدنى؛ إذا تكررت هناك، اتصل بالدعم مع المستند، Program.cs الخاص بك، ومخرجات تشخيص الترخيص.
هل كانت هذه الصفحة مفيدة؟