استكشاف الأخطاء وإصلاحها
تشخيص الأخطاء الشائعة
العديد من فشل System.Web لا ترفع استثناء يمكنك رؤيته: الصفحة تُعيد 500 فارغًا، أو أيقونة تُظهر خطأ 404، أو طلب لا يعود أبدًا. تم تنظيم هذه الصفحة وفقًا لما تلاحظه. الرسائل المقتبسة هي النص الحرفي الذي ينتجه Doconut.
لمحة سريعة عن الأعراض
| ما تراه | السبب الأكثر احتمالًا | الحل |
|---|---|---|
كل طلب يُجيب بـ 500 فارغ | استثناء في Application_Start: مكوّن إضافي بدون ترخيصه، خيار غير صالح، تكوين مزرعة غير مكتمل — أو إعادة توجيه ربط يحدد نسخة غير موجودة في bin\ | سجل أحداث Windows، Application، المصدر ASP.NET. راجع فشل بدء التشغيل |
بعض صفحات MVC تُجيب بـ 500 فارغ | يقوم Razor بترجمة العروض في وقت التشغيل: الواجهة netstandard مفقودة من <compilation>، أو العرض يستخدم C# أحدث من 5 (?., $"...", nameof) | أضف الواجهة (التثبيت); انقل المنطق من العرض إلى المتحكم |
الصفحات تُظهر —، … أو ما شابه بدلاً من الشرطات واللكنات | ملفات الصفحات بدون علامة ترتيب البايت تُقرأ بصفحة الترميز ANSI الخاصة بالخادم | <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" /> |
وحدة تحكم المتصفح تُظهر 404 لـ HEAD /DocImage.axd?...&page=1 | المعالج مسجل بدون الفعل HEAD | verb="GET,HEAD,POST" على المعالج |
| المستند يُعرض، لكن أيقونات شريط الأدوات ومؤشر التحميل مفقودان | ResPath يشير إلى جذر المورد، أو يبدأ بـ / | ResPath: 'doconut-res/images' |
طلبات /doconut-res/... تُجيب بـ 404 | وحدة المورد غير مسجلة، runAllManagedModulesForAllRequests معطلة، أو توجيه MVC يلتقط المسار | إدخال <modules>، و routes.IgnoreRoute("doconut-res/{*pathInfo}") |
العارض يُبلغ عن The viewer handler could not be reached (no response). | BasePath يبدأ بـ / ('/myapp' يصبح //myapp/…، مضيف آخر) | BasePath: '/' في جذر الموقع؛ 'myapp' في دليل افتراضي |
العارض يُبلغ عن Please make sure your middleware is configured. | DocImage.axd أجاب بـ 404: المعالج غير موجود في Web.config، توجيه MVC التقطه، أو BasePath يشير إلى مكان آخر | إدخال <handlers>، routes.IgnoreRoute("{resource}.axd/{*pathInfo}")، و BasePath |
كل صفحة تُظهر You Are Not Authorized To View This Page. | تم فتح المستند في طلب بدون حالة جلسة، حالة الجلسة معطلة، أو ملف تعريف الارتباط للجلسة لا يصل إلى DocImage.axd | راجع غير مخول |
| تحويل Web Forms لا يعود أبدًا | الصفحة تتعطل عند ConvertAsync — حالة توقف (deadlock) | Async="true" + RegisterAsyncTask (ملحق التحويل) |
| كل صفحة تحمل علامة مائية للتقييم | لم يُعثر على ترخيص — غير موجود في <site root>\wwwroot | إعداد الترخيص |
الأداة تُحمَّل، لكن الإجراء الأول لها يُجيب بـ 404 | الأداة غير مفعلة، أو basePath الخاص بها ليس '/DocImage.axd' | options.Add…Widget()، و basePath: '/DocImage.axd' |
| المستند الأول بعد بدء الموقع أو إعادة تدويره يستغرق دقيقة أو أكثر؛ المستندات اللاحقة سريعة | محركات المستندات تُحمَّل عند الفتح الأول، ومكافحات الفيروسات في الوقت الحقيقي تفحصها أثناء التحميل | قم بتسخين الموقع واحتفظ بالمجمع قيد التشغيل — راجع المستند الأول بعد بدء التشغيل |
| تحميل كبير يُظهر صفحة خطأ IIS | التحميل يتجاوز maxRequestLength (KB) أو maxAllowedContentLength (بايت) | ارتقِ بالقيم لتجاوز أكبر ملف أو حد الأداة لديك |
فشل بدء التشغيل
استثناء يُرمى في Application_Start لا يصل إلى المتصفح: كل طلب يُجيب بـ 500 فارغ، وسجل IIS لا يظهر شيئًا مفيدًا. الاستثناء موجود في سجل أحداث Windows (عارض الأحداث → سجلات Windows → التطبيق، المصدر ASP.NET). الأنواع الشائعة:
مكوّن إضافي بدون ترخيصه:
The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.يجب أن يكون Doconut.Viewer.<Capability>.lic الخاص بالمكوّن الإضافي في wwwroot، بجوار Doconut.Viewer.lic. الترخيص المفقود وملف TRIAL القديم لا يمنح أي قدرات للمكوّن الإضافي.
خيارات غير صالحة:
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.مجموعة لا يمكن تحميلها. يقوم ASP.NET بتحميل كل مجموعة في bin\ عند بدء التطبيق، لذا فإن إعادة توجيه ربط في Web.config التي تحدد نسخة غير موجودة في bin\ توقف الموقع بأكمله. انسخ عمليات إعادة التوجيه التي أنشأها NuGet (لمشروع بنمط SDK، من bin\<YourApp>.dll.config) بدلاً من تعديلها يدويًا، ونسخها مرة أخرى بعد تحديث الحزم.
غير مصرح لك بعرض هذه الصفحة.
تم رفض الصفحة لأن جلسة ASP.NET المطلوبة لم تُمنح المستند أبداً. تحقق، بالترتيب:
- تم تشغيل الفتح بحالة الجلسة. تحكمات MVC وصفحات Web Forms لديها ذلك. يجب على
IHttpHandlerالمخصص الذي يفتح المستندات تنفيذSystem.Web.SessionState.IRequiresSessionState، وإلا لن تكون لديه جلسة لمنحها. - حالة الجلسة مفعلة.
<sessionState mode="Off" />يرفض كل صفحة. - الكوكي يصل إلى المعالج. طلبات الودجت ذات الأصل نفسه تحمل
ASP.NET_SessionId؛ بينما لا يحملها سكريبت أو نداء من خادم إلى خادم، أو صفحة عبر أصل مختلف بدون كوكيز. - مزرعة الويب: الفتح يربط المتصفح (
DocOptions.BrowserId) وتُمرر الصفحة التذكرة (objViewer.View(token, access))؛ كل عقدة تستخدم نفس مفتاح التوقيع.
الرفض هو صورة تُقدَّم بحالة 200، بحجم حوالي 2 كيلوبايت. المراقب الذي يتحقق فقط من رموز الحالة يعتبرها صفحة.
لم يتم العثور على جلسة المستند. يرجى إعادة فتح المستند.
انتهت صلاحية الرمز (نافذة منزلقة، DocOptions.TimeOut، الافتراضي 60 دقيقة)، أو تم إغلاق المستند، أو — على خادم واحد — تم إعادة تدوير مجموعة التطبيقات. يحدث إعادة التدوير وفق جدول، عند كل تعديل Web.config، وبعد انتهاء مهلة الخمول للمجموعة (20 دقيقة افتراضياً في IIS). افتح المستند مرة أخرى للحصول على رمز جديد.
فشل فتح المستند
LicenseException مع سبب الرفض — تم العثور على ملف الترخيص لكنه رُفض (توقيع غير صالح، تلاعب، إدراج في القائمة السوداء، أو بناء خارج نافذة إصدار الترخيص). يتم حظر الفتح بدلاً من وضع علامة مائية.
LicenseException:
This document type requires the 'Dicom' plugin license.الامتداد يُعالج فقط بواسطة ملحق (هنا DICOM). الملحق مسجل، لكن لا ترخيص يمنح قدرته بعد الآن — عادةً ترخيص مؤقت انتهت صلاحيته بعد بدء الموقع. قم بتثبيت ترخيص يمنحه.
FormatNotSupportedException — لا يوجد عارض (مدمج، ملحق، أو مخصص) يدعم هذا الامتداد. يمكن لـ DoconutOptions.RegisterViewer إضافة واحد لتنسيقاتك الخاصة.
InvalidDataException — المحتوى فاسد أو لا يتطابق مع امتداده (ملف أعيد تسميته). تحقق من صحة التحميلات قبل الفتح.
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().تم حل DocumentConverter دون تسجيل ملحق Converter.
المخرجات تبدو خاطئة
الصفحات تحمل علامة مائية — لم يُعثر على ترخيص، أو انتهت صلاحية الترخيص المؤقت. مع ترخيص مؤقت فعال، يتم وضع علامة مائية فقط على مخرجات الملحق. الترخيص الذي لا يغطي هذا الإصدار لا يُوضع عليه علامة مائية: الفتح يثير LicenseException. في IIS، يجب أن يكون الترخيص في wwwroot تحت جذر الموقع (AppContext.BaseDirectory\wwwroot)، وليس في bin\. تحقق من IDoconutLicenseService (License.IsLicenseFileFound، IsExpired، IsVersionValid، License.RejectionMessage).
المستندات القديمة تعرض نصاً مشوّشاً — سجّل ترميزات صفحات الشيفرة مرة واحدة، عند بدء التشغيل:
// Global.asax.cs, Application_Start - قبل DoconutHost.Initialize.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);خطوط خاطئة أو مستبدلة — الخادم يفتقر إلى خطوط المستند. خادم Windows بدون Office يحتوي على خطوط أقل بكثير من جهاز التطوير. قم بتثبيت الخطوط، أو وجه FontFolders (على WordConfig و PptConfig) إلى مجلد يحتوي عليها.
تظهر توضيحات الصورة في العارض لكن التصدير يحتوي على صندوق "الصورة محظورة" — مضيف الصورة لديه عنوان خاص أو حلقة رجوع، ويُرفض الخادم جلبه. انظر التعليقات التوضيحية.
الميزة تعمل في التقييم، صامتة في الإنتاج
ترخيص مؤقت نشط يمنح كل القدرة؛ ترخيصك المشتراة يمنح فقط ما اشتريته. بدون قدرة، لا تُصدر ملفات البحث أو التوضيح الخاصة به، ويتوقف ملحق مسجل الموقع عند بدء التشغيل. قارن IsCapabilityGranted(...) مع كل ميزة تستخدمها قبل النشر.
لا يجد البحث شيئًا (أو القليل جدًا)
- لملف PDF، لم يتم تمكين
AllowSearchعند فتح المستند — فهو ي默认 إلىfalse. يتيح Word وExcel وPowerPoint نفس المفتاح. - المحتوى ممسوح ضوئيًا أو صورة فقط، لذا لا توجد طبقة نصية للمطابقة.
- HTML وMicrosoft Project (MPP) غير قابلين للبحث في إعداداتهم الافتراضية: اضبط
DefaultRender = falseلكي يتم عرضهم عبر إسقاط PDF يحتوي على نص. objViewer.CanSearch()هوfalseبعد التهيئة: الصيغة المحلولة لا تحتوي على مسار بحث. هذا منفصل عن ترخيص البحث؛ تحقق من كليهما.- الصفحة تقرأ القيمة المرجعة من
objViewer.Search(...)— العدد يصل في معاملها الثالث، وهو استدعاء رد.
ما زلت عالقًا؟
أعد إنتاج المشكلة باستخدام الإعداد الأدنى من البدء السريع. إذا تكررت هناك، تواصل مع الدعم مع المستند، وGlobal.asax.cs الخاص بك، وأجزاء Doconut من Web.config، وإدخال سجل أحداث Windows إذا كان موجودًا.
هل كانت هذه الصفحة مفيدة؟