عیب‌یابی

هر پیام زیر متن دقیق 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 اضافه کنید.

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

You Are Not Authorized To View This Page.

توکن توسط یک جلسه مرورگر متفاوت باز شده است. دلایل معمول: کوکی جلسه به درخواست‌های صفحه نمی‌رسد (پیکربندی cross‑origin، سیاست 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=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) را بررسی کنید — مرجع صفحه Licensing یک نقطهٔ انتهایی آماده دارد.

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

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

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