عیب‌یابی

هر پیام زیر متن دقیق 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 بدون جعبه کوکی)، یا برنامه دوباره راه‌اندازی شد (کلیدهای جلسه جدید). این لایه امنیتی است که طبق طراحی کار می‌کند — به Core Concepts → Sessions & Security مراجعه کنید.

یک تصویر خطا که می‌گوید:

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 اشاره می‌کند — مجوز غیر موقت فعلی آن قابلیت افزونه را اعطا نمی‌کند. ثبت را حذف کنید یا مجوزی نصب کنید که آن را بدهد. یک مجوز گمشده و یک فایل legacy 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) — مرجع IDoconutLicenseService صفحه Licensing یک نقطه انتهایی آماده را نشان می‌دهد.

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

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

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