استكشاف الأخطاء وإصلاحها
تشخيص الأخطاء الشائعة
كل رسالة أدناه هي النص الحرفي الذي ينتجه 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) أو أُغلقت الجلسة. أعد فتح المستند للحصول على رمز مميز جديد.
فشل فتح مستند
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.التحقق من صحة خيارات الفشل السريع — أصلح المسار المخالف.
أخطاء البناء / التبعيات
خطأ المترجم CS1705، أو أثناء التشغيل عند فتح مستند:
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'مشروعك قام بتثبيت System.Text.Json أو System.Text.Encodings.Web بأقل من إصدارات 8.0.x التي أعلن عنها Doconut.NET8. احذف التخفيض ودع NuGet يستعيد رسم الحزم (System.Text.Json 8.0.5 و System.Text.Encodings.Web 8.0.0).
المخرجات تبدو خاطئة
الصفحات تحمل علامة مائية — التطبيق في حالة تقييم: لا ملف ترخيص موجود، أو ترخيص مؤقت منتهي الصلاحية، أو نطاق غير صالح. تحت ترخيص مؤقت نشط، فقط مخرجات الإضافة تكون مائية. بناء تم إصداره بعد تاريخ اشتراك ترخيص مدفوع لا يكون مائيًا: الفتح يطرح LicenseException. افحص IDoconutLicenseService (License.IsLicenseFileFound، IsExpired، IsVersionValid، IsValidForDomain، License.RejectionMessage) — إشارة صفحة الترخيص إلى IDoconutLicenseService تُظهر نقطة نهاية جاهزة.
المستندات القديمة تعرض نصًا مشوشًا — ترميزات صفحات الشيفرة لا تُحمَّل افتراضيًا على .NET 8. أضف مرة واحدة عند بدء التشغيل:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);خطوط خاطئة أو مستبدلة — الخادم يفتقر إلى خطوط المستند. ثبّتها، أو وجه FontFolders (على WordConfig/PptConfig) إلى مجلد يحتويها. على لينكس، انظر أدناه.
تظهر تعليقة صورة في العارض لكن التصدير يحتوي على صندوق "صورة محظورة" — مضيف الصورة لديه عنوان خاص أو حلقة رجوع، ويُرفض الخادم جلبه. انظر التعليقات التوضيحية.
لينكس
فتح أي مستند يفشل مع:
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.ثبّت مكتبة تكوين الخطوط: apt-get install -y libfontconfig1 (fontconfig على RHEL/Fedora). انظر التثبيت.
فتح أي مستند يفشل مع:
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.التطبيق يشير إلى SkiaSharp أحدث، مباشرة أو عبر مكتبة أخرى. أضف SkiaSharp.NativeAssets.Linux بنفس إصدار ذلك SkiaSharp.
فتح أي مستند يفشل مع:
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.المضيف ليس منصة مدعومة. توزيعات Alpine وغيرها القائمة على musl غير مدعومة: استخدم صورة مبنية على Debian أو Ubuntu.
النص أوسع أو أضيق من Windows، أو تنكسر الأسطر بشكل مختلف — خطوط المستند غير مثبتة، لذا Doconut يستخدم أقرب خط مثبت. ثبّت خطوط متوافقة مع المقاييس (fonts-liberation لـ Arial، Times New Roman و Courier New؛ fonts-crosextra-carlito و fonts-crosextra-caladea لـ Calibri و Cambria)، أو انسخ خطوطك المرخصة إلى /usr/share/fonts/ وشغّل fc-cache -f. النص الآسيوي المعروض كمربعات فارغة يحتاج إلى fonts-noto-cjk.
الميزة تعمل في التقييم، صامتة في الإنتاج
المفاجأة الكلاسيكية عند الانتقال إلى الإنتاج: ترخيص مؤقت نشط يمنح كل القدرة؛ ترخيصك المشتراة يمنح فقط ما اشتريت. قد تختفي حزم البحث والتعليقات التوضيحية عندما تكون قدراتها غير موجودة. فشل المحول المسجل أو ملحقات 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 الخاص بك، ومخرجات تشخيص الترخيص.
هل كانت هذه الصفحة مفيدة؟