استكشاف الأخطاء وإصلاحها

تشخيص الأخطاء الشائعة

كل رسالة أدناه هي النص الحرفي الذي ينتجه 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 مع:

text
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 تسجل واحدة بالفعل).

صورة خطأ في منطقة الصفحة تظهر النص:

text
You Are Not Authorized To View This Page.

تم فتح الرمز المميز بواسطة جلسة متصفح مختلفة. الأسباب الشائعة: ملف تعريف الارتباط للجلسة لا يصل إلى طلبات الصفحة (إعداد عبر الأصل، سياسة SameSite، عميل API بدون حاوية ملفات تعريف الارتباط)، أو أن التطبيق أعيد تشغيله (مفاتيح جلسة جديدة). هذه هي طبقة الأمان التي تعمل كما هو مصمم — راجع المفاهيم الأساسية → الجلسات والأمان. الرفض هو صورة تُقدَّم بالحالة 200، لذا فإن المراقب الذي يتحقق فقط من رموز الحالة يعتبرها صفحة.

صورة خطأ تظهر النص:

text
Document session not found. Please re-open document.

انتهت صلاحية الرمز المميز (نافذة منزلقة، 60 دقيقة افتراضيًا — DocOptions.TimeOut) أو أُغلقت الجلسة. أعد فتح المستند للحصول على رمز مميز جديد.

فشل فتح المستند

LicenseException مع رسالة رفض — تم العثور على ملف الترخيص لكنه رُفض (توقيع غير صالح، تم العبث به، مدرج في القائمة السوداء، أو بناء خارج نافذة الإصدار/التحديث للترخيص). هذه الحالة تمنع الفتح (فشل سريع) بدلاً من التحول إلى علامة مائية؛ اقرأ License.RejectionMessage للسبب.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

الامتداد يُعالج فقط بواسطة مكوّن إضافي (هنا: DICOM). المكوّن الإضافي مسجل، لكن لا ترخيص يمنح قدرته بعد الآن — عادةً ترخيص مؤقت انتهت صلاحيته بعد بدء التطبيق. ثبّت ترخيصًا يمنحه وتحقق من IsCapabilityGranted(LicenseCapability.Dicom) على IDoconutLicenseService. إذا كان هناك استحقاق غير مؤقت مفقود أو غير كافٍ، عادةً ما يفشل ذلك في وقت سابق، أثناء AddDoconut().

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

لا عارض — مدمج، مكوّن إضافي، أو مخصص — يدعم هذا الامتداد. تحقق من قائمة الصيغ المدعومة؛ بالنسبة لصيغك الخاصة، يمكن لـ DoconutOptions.RegisterViewer إضافة واحدة.

InvalidDataException — محتوى الملف فاسد أو لا يتطابق مع امتداده (مثلاً ملف أُعيد تسميته). تحقق من صحة التحميلات قبل الفتح.

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

قمت بحل DocumentConverter دون تسجيل مكوّن التحويل Converter.

فشل بدء التشغيل

InvalidOperationException يذكر مكوّنًا إضافيًا مسجلاً عبر AddPlugin — الترخيص غير المؤقت الحالي لا يمنح تلك القدرة للمكوّن الإضافي. أزل التسجيل أو ثبّت ترخيصًا يمنحه. الترخيص المفقود وملف TRIAL القديم لا يمنحان أي قدرات للمكوّن الإضافي.

ArgumentException من AddDoconut():

text
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، أو أثناء التشغيل عند فتح مستند:

text
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.NET6. أزل التخفيض ودع NuGet يستعيد رسم الحزمة (System.Text.Json 8.0.6 وSystem.Text.Encodings.Web 8.0.0 كما هو معلن في الحزمة).

المخرجات تبدو خاطئة

الصفحات تحمل علامة مائية — التطبيق في حالة تقييم: لا يوجد ملف ترخيص، أو ترخيص مؤقت منتهي الصلاحية، أو نطاق غير صالح. تحت ترخيص مؤقت نشط، يتم وضع علامة مائية فقط على مخرجات المكوّن الإضافي. بناء تم إصداره بعد تاريخ اشتراك ترخيص مدفوع لا يحمل علامة مائية: الفتح يرمى LicenseException. افحص IDoconutLicenseService (License.IsLicenseFileFound، IsExpired، IsVersionValid، IsValidForDomain، License.RejectionMessage) — إشارة IDoconutLicenseService في صفحة الترخيص تُظهر نقطة نهاية جاهزة.

المستندات القديمة تعرض نصًا مشوشًا — ترميزات صفحات الكود لا تُحمَّل افتراضيًا في .NET 6. أضف مرة واحدة عند بدء التشغيل:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

خطوط خاطئة أو مستبدلة — الخادم يفتقر إلى خطوط المستند. ثبّتها، أو وجه FontFolders (على WordConfig/PptConfig) إلى مجلد يحتويها. على لينكس، راجع أدناه.

تظهر تعليقة صورة في العارض لكن التصدير يحتوي على صندوق "صورة محجوبة" — مضيف الصورة لديه عنوان خاص أو حلقة رجوع، يرفض الخادم جلبه. راجع التعليقات التوضيحية.

لينكس

فشل فتح أي مستند مع:

text
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). راجع التثبيت.

فشل فتح أي مستند مع:

text
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.

فشل فتح أي مستند مع:

text
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 الخاص بك، ومخرجات تشخيص الترخيص.

هل كانت هذه الصفحة مفيدة؟