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

كل رسالة أدناه هي النص الحرفي الذي ينتجه Doconut، منظمة حسب العرض. ابحث عن الخطأ الخاص بك، وطبق الإصلاح.

لا يعرض المشاهد شيئًا

منطقة المشاهد فارغة، وحدة تحكم المتصفح مليئة بأخطاء 404 لـ /doconut-res/...
UseDoconutResources() مفقودة، أو وضعت بعد UseDoconut(). يجب أن تكون أولاً في خط الأنابيب.

HTTP 500 مع:

Session middleware not configured. Call UseSession() before UseDoconut().

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

You Are Not Authorized To View This Page.

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

صورة خطأ تعرض النص:

Document session not found. Please re-open document.

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

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

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

LicenseException:

This document type requires the 'Dicom' plugin license.

الإضافة يتم التعامل معها فقط بواسطة مكوّن إضافي (هنا: DICOM) والقدرة لم تعد ممنوحة. سجّل المكوّن الإضافي وتحقق من lic.IsCapabilityGranted(LicenseCapability.Dicom). عادةً ما يفشل وجود ترخيص غير مؤقت مفقود أو غير كافٍ في وقت مبكر أثناء 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.NET6. أزل التخفيض ودع NuGet يستعيد رسم الحزم (System.Text.Json 8.0.6 و System.Text.Encodings.Web 8.0.0 في حزمة 26.7.0 المدققة).

TypeInitializationException على أول ملف عرض:

Could not load ... System.Drawing.Common, Version=6.0.0.0

محرك العرض يتطلب صراحةً System.Drawing.Common 6.0.0 (محدد من قبل الحزمة). لا تقم بإزالة أو تجاوز تلك الاعتماديات — كل فتح PPT/PPTX/PPS/POT/ODP سيفشل بدونه.

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

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

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

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

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

العروض تفتح لكن تفشل في العرض على Linux/macOS — المرسِّم الحالي لـ PPT/PPTX/PPS/POT/ODP يتطلب libgdiplus الأصلي بالإضافة إلى System.Drawing.EnableUnixSupport=true. الحزمة توفر System.Drawing.Common 6.0.0 لأن ذلك هو آخر إصدار يدعم هذا المفتاح.

الميزة تعمل في التقييم، صامتة في الإنتاج

المفاجأة الكلاسيكية عند الانتقال إلى الإنتاج: ترخيص مؤقت نشط يمنح كل القدرة؛ ترخيصك المشتراة يمنح فقط ما اشتريت. قد تختفي حزم البحث والتعليقات التوضيحية عندما تكون قدراتها غير موجودة. المكوّنات الإضافية Converter أو 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 بعد التهيئة — الصيغة المحلولة لا تملك مسار بحث قياسي. هذا الحكم منفصل عن ترخيص البحث؛ تحقق من كليهما.

ما زلت عالقًا؟

عزل المشكلة باستخدام تطبيق Quick Start الأدنى؛ إذا تكررت هناك، تواصل مع الدعم مع المستند، وملف Program.cs الخاص بك، ومخرجات تشخيص الترخيص.