عیب‌یابی

هر پیام زیر متن دقیق 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 اضافه کنید. وضعیت جلسه همچنین به یک کش نیاز دارد: در یک برنامه minimal‑API builder.Services.AddDistributedMemoryCache() را اضافه کنید، یا برنامه در زمان راه‌اندازی با خطای Unable to resolve service for type 'IDistributedCache' متوقف می‌شود (برنامه‌های MVC و Razor Pages قبلاً یکی را ثبت کرده‌اند).

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

You Are Not Authorized To View This Page.

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

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

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 خود و خروجی تشخیص لایسنس با پشتیبانی تماس بگیرید.