عیب‌یابی

هر پیام زیر متن دقیق Doconut است که تولید می‌کند، بر اساس علائم سازماندهی شده است. خطای خود را پیدا کنید و راه‌حل را اعمال کنید.

نمایشگر چیزی نشان نمی‌دهد

ناحیه خالی نمایشگر، کنسول مرورگر پر از خطاهای 404 برای /doconut-res/...
UseDoconutResources() وجود ندارد، یا پس از UseDoconut() قرار گرفته است. باید اولین در خط لوله باشد.

HTTP 500 با:

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

یک تصویر خطا در ناحیه صفحه با متن:

You Are Not Authorized To View This Page.

توکن توسط یک نشست مرورگر متفاوت باز شده بود. دلایل معمول: کوکی نشست به درخواست‌های صفحه نمی‌رسد (پیکربندی کراس‑اورجین، سیاست SameSite، یا یک کلاینت API بدون کوکی)، یا برنامه دوباره راه‌اندازی شد (کلیدهای نشست جدید). این لایه امنیتی به‌گونه‌ای که طراحی شده کار می‌کند — به مفاهیم اصلی → نشست‌ها و امنیت مراجعه کنید.

یک تصویر خطا با متن:

Document session not found. Please re-open document.

توکن منقضی شده است (پنجره لغزشی، پیش‌فرض ۶۰ دقیقه — DocOptions.TimeOut) یا نشست بسته شده است. سند را دوباره باز کنید تا توکن جدیدی دریافت کنید.

باز کردن سند ناموفق است

LicenseException با پیام رد — فایل لایسنس پیدا شد اما رد شد (امضای نامعتبر، دست‌کاری شده، در لیست سیاه، یا ساختی خارج از بازه نسخه/به‌روزرسانی لایسنس). این وضعیت باز کردن را مسدود می‌کند (fail‑fast) به‌جای کاهش به واترمارک؛ برای دلیل به 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.

اعتبارسنجی گزینه‌ها به‌صورت fail‑fast — مسیر مشکل‌ساز را اصلاح کنید.

خطاهای ساخت / وابستگی

خطای کامپایلر CS1705، یا در زمان اجرا هنگام باز کردن سند:

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 در اولین فایل ارائه:

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 در صفحه Licensing یک نقطه انتهایی آماده را نشان می‌دهد.

اسناد قدیمی متن‌های خراب نمایش می‌دهند — رمزگذاری‌های صفحه کد به‌صورت پیش‌فرض در .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 است — فرمت حل‌شده مسیر جستجوی استانداردی ندارد. این verdict جدا از لایسنس Search است؛ هر دو را بررسی کنید.

هنوز گیر کرده‌اید؟

مشکل را در مقابل برنامهٔ حداقل Quick Start جدا کنید؛ اگر در آن نیز تکرار شد، با سند، Program.cs خود و خروجی تشخیص لایسنس، با پشتیبانی تماس بگیرید.