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

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

العارض لا يظهر شيئًا

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

HTTP 500 مع:

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

أمان الرمز المميز في Doconut (مفعل افتراضيًا) يحتاج إلى حالة جلسة ASP.NET. أضف builder.Services.AddSession() و app.UseSession() قبل فرع Middleware الخاص بـ Doconut.

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

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=10.0.0.0'

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

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 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 ي expose نفس المفتاح عبر PdfConfig المتداخل.
• المحتوى مُسح ضوئيًا/صورة فقط، لذا لا يمتلك البحث العادي طبقة نصية للمطابقة. استخدم مصدرًا يحتوي نصًا أو إسقاط PDF يحافظ على النص.
• HTML وMS Project (MPP) غير قابلين للبحث في إعداداتهم الافتراضية — اضبط DefaultRender = false لتُعرض عبر إسقاط PDF بطبقة نصية أصلية. Word وExcel وPowerPoint وTXT وVisio والبريد الإلكتروني وEPUB وMHT تُبحث في إعداداتهم الافتراضية للكتالوج.
• objViewer.CanSearch() هو false بعد التهيئة — الصيغة التي تم حلها لا تملك مسار بحث قياسي. هذا الحكم منفصل عن ترخيص البحث؛ تحقق من كلاهما.

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

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