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

كل رسالة أدناه هي النص الحرفي الذي ينتجه 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 مع رسالة رفض — تم العثور على ملف الترخيص لكنه رُفض (توقيع غير صالح، تم العبث به، مدرج في القائمة السوداء، أو بناء خارج نافذة الإصدار/التحديث للترخيص). هذه الحالة تمنع الفتح (فشل سريع) بدلاً من التحول إلى علامة مائية؛ اقرأ 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.

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

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

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

Could not load file or assembly 'System.Text.Json, Version=10.0.0.0'

قام مشروعك بتثبيت System.Text.Json / System.Text.Encodings.Web بأقل من 10.0.x. أزل التخفيض ودع NuGet يستعيد الإصدارات التي يعلن عنها Doconut.NET8.

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 8. أضف مرة واحدة عند بدء التشغيل:

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