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

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

الخادم يعمل بشكل جيد لكن الصفحة تتصرف بشكل غير صحيح — دون أي خطأ في أي مكان

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

شريط تحميل مستمر لا يتوقف أبداً. تم إعلان ردود نداء العارض الخاصة بك كدوال عالمية مسماة بعد معرف الحاوية — ctlDoc_OnViewerReady() وغيرها. العارض السابق كان يبحث عن هذه الأسماء؛ هذا العارض لا يفعل ذلك. المعالج الذي كان سيخفي شريط التحميل ببساطة لا يُنفّذ أبداً. مرّر الدوال كخيارات بدلاً من ذلك:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

المستند خلف شريط التحميل سليم. القائمة الكاملة للخيارات موجودة في تكوين العارض.

أيقونات العارض أو الإطار مفقودة، والصفحات صحيحة بخلاف ذلك. ResPath فارغ أو يشير إلى جذر التطبيق — كان صحيحًا في المكتبة السابقة، وخاطئًا هنا. يجب أن يحدد البادئة التي يركبها UseDoconutResources():

ResPath: 'doconut-res/images'   // or '<your ResourcesPath>/images'

بلاطات مكسورة للصفحات اللاحقة عند الخدمة من تخزين مشترك. الصفحات التي لا تزال تُكتب تُجيب بـ 202 Accepted. عميل بدون retryOn409: true يتعامل مع ذلك كصورة فاشلة. راجع النشر الموزع.

فشل فتح مستند

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

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

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

الحزمة لن تُثبت مطلقًا — Doconut.NETStandard 26.8.0 تستهدف netstandard2.1، لذا يرفض NuGet مشروع .NET Framework. هذا ليس خطأ استعادة يمكن حله: .NET Framework لا يمكنه استهلاك netstandard2.1. استخدم حزمة Doconut.NETFramework بدلاً من ذلك.

خطأ المترجم CS1705، أو أثناء التشغيل عند فتح مستند:

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

مشروعك قام بتثبيت System.Text.Json أو System.Text.Encodings.Web بإصدار أقل من 9.0.x التي يعلن عنها Doconut.NETStandard. أزل التخفيض ودع NuGet يستعيد رسم الحزمة (System.Text.Json 9.0.0 و System.Text.Encodings.Web 9.0.0 في الحزمة المدققة 26.8.0).

جدار من أخطاء التجميع مباشرةً بعد ترقية الحزمة — هذا متوقع. 26.8.0 لديها سطح API مختلف عن 26.7.0، ليست تحديثًا متوافقًا. معظم الأخطاء هي أسطر using التي انتقلت إلى مساحة الاسم الجذرية Doconut؛ اعمل عبر ترحيل إلى .NET Standard 2.1 بدلاً من تعديلها واحدةً تلو الأخرى.

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 تُظهر نقطة نهاية جاهزة.

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

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 بعد التهيئة — الصيغة المحلولة لا تملك مسار بحث قياسي. هذا الحكم منفصل عن ترخيص البحث؛ تحقق من كليهما.

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

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