عیب‌یابی

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

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

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

HTTP ۵۰۰ با:

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.

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

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

Document session not found. Please re-open document.

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

سرور درست کار می‌کند اما صفحه به‌درستی رفتار نمی‌کند — بدون هیچ خطایی

این‌ها حالت‌های شکست هستند که پس از انتقال یک برنامه باید ابتدا به آن‌ها توجه کرد. هر سه حالت سرور را کاملاً سالم می‌گذارند، سند را به‌درستی رندر می‌کنند و هیچ‌چیزی در کنسول مرورگر گزارش نمی‌شود.

یک چرخ‌دنده مشغول که هرگز متوقف نمی‌شود. توابع بازگشتی نمایشگر شما به‌صورت توابع سراسری با نام شناسهٔ کانتینر تعریف شده‌اند — ctlDoc_OnViewerReady() و دوستان. نمایشگر قبلی این نام‌ها را جستجو می‌کرد؛ این یکی این کار را نمی‌کند. هندلری که باید چرخ‌دنده را مخفی می‌کرد هرگز اجرا نمی‌شود. به‌جای آن توابع را به‌عنوان گزینه‌ها پاس دهید:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

سند پشت چرخ‌دنده سالم است. فهرست کامل گزینه‌ها در پیکربندی‌نمایشگر موجود است.

آیکون‌ها یا نوارهای نمایشگر گم شده‌اند، صفحات در غیر این صورت صحیح‌اند. ResPath خالی است یا به ریشهٔ برنامه اشاره می‌کند — در کتابخانهٔ قبلی صحیح بود، اینجا اشتباه. باید پیشوندی که UseDoconutResources() سوار می‌کند نام‌گذاری شود:

ResPath: 'doconut-res/images'   // or '<your ResourcesPath>/images'

کاشی‌های خراب برای صفحات بعدی هنگام سرو از ذخیره‌سازی مشترک. صفحاتی که هنوز در حال نوشتن هستند پاسخ 202 Accepted می‌دهند. یک کلاینت بدون retryOn409: true این را به‌عنوان تصویر ناموفق در نظر می‌گیرد. به استقرارهای توزیع‌شده مراجعه کنید.

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

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 را حل کردید بدون اینکه پلاگین مبدل را ثبت کنید.

راه‌اندازی ناموفق

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) انجام می‌شود — مسیر مشکل‌دار را اصلاح کنید.

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

پکیج به‌کل نصب نمی‌شود — Doconut.NETStandard نسخه 26.8.0 برای netstandard2.1 هدف‌گذاری شده است، بنابراین NuGet یک پروژه .NET Framework را رد می‌کند. این یک خطای بازگردانی (restore) قابل حل نیست: .NET Framework نمی‌تواند netstandard2.1 را مصرف کند. به‌جای آن از پکیج Doconut.NETFramework استفاده کنید.

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

Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

پروژه شما System.Text.Json یا System.Text.Encodings.Web را به نسخه‌ای پایین‌تر از 9.0.x که توسط Doconut.NETStandard اعلام شده، قفل کرده است. کاهش نسخه را حذف کنید و بگذارید NuGet گراف پکیج‌ها را بازگردانی کند (System.Text.Json 9.0.0 و System.Text.Encodings.Web 9.0.0 در پکیج 26.8.0 بررسی‌شده).

یک دیوار از خطاهای کامپایل بلافاصله پس از ارتقاء پکیج — این رفتار طبیعی است. نسخه 26.8.0 سطح API متفاوتی نسبت به 26.7.0 دارد و یک به‌روزرسانی سازگار نیست. بیشتر خطاها مربوط به خطوط using هستند که به فضای‌نام اصلی Doconut منتقل شده‌اند؛ به جای اصلاح دستی هرکدام، از مهاجرت به .NET Standard 2.1 استفاده کنید.

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 یک نقطه‌پایان آماده دارد.

سندهای قدیمی متن خراب نمایش می‌دهند — رمزگذاری‌های صفحه کد به‌صورت پیش‌فرض بارگذاری نمی‌شوند. یک بار در زمان راه‌اندازی اضافه کنید:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

فونت‌های نادرست یا جایگزین در Linux/Docker — کانتینر فاقد فونت‌های مورد نیاز سند است. FontFolders (در WordConfig/PptConfig) را به یک پوشه فونت سوارشده (mounted) اشاره دهید.

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