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

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

المنطقة لا تعرض شيئًا

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

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 بدون حاوية ملفات تعريف الارتباط)، أو أن التطبيق أعيد تشغيله (مفاتيح جلسة جديدة). هذه هي طبقة الأمان تعمل كما هو مصمم — راجع المفاهيم الأساسية → الجلسات والأمان.

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

Document session not found. Please re-open document.

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

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

LicenseException with a rejection message — تم العثور على ملف الترخيص لكنه رُفض (توقيع غير صالح، تم التلاعب به، مدرج في القائمة السوداء، أو بناء خارج نافذة الإصدار/التحديث للترخيص). هذه الحالة تمنع الفتح (فشل سريع) بدلاً من التحول إلى علامة مائية؛ اطلع على 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 mentioning a plugin registered via AddPlugin — الترخيص غير المؤقت الحالي لا يمنح قدرة ذلك المكوّن الإضافي. احذف التسجيل أو ثبّت ترخيصًا يمنحه. الترخيص المفقود وملف TRIAL القديم لا يمنح أي قدرات للمكوّنات الإضافية.

ArgumentException from 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.

تحقق سريع من صحة الخيارات — صحح المسار المخالف.

أخطاء البناء / الاعتماديات

Compiler error CS1705, or at runtime when opening a document:

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 on the first presentation file:

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