عیب‌یابی

تشخیص خطاهای رایج

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

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

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

نمایشگر گزارش می‌دهد The viewer handler could not be reached (no response).
درخواست هیچ پاسخی دریافت نکرد. یک دلیل رایج، BasePath است که با / شروع می‌شود: '/doconut' به //doconut/DocImage.axd تبدیل می‌شود، یک درخواست به میزبان دیگر. آن را بدون اسلش ابتدایی بنویسید (BasePath: 'doconut').

نمایشگر گزارش می‌دهد Please make sure your middleware is configured.
نقطه انتهایی صفحه پاسخ داد 404: UseDoconut() در جایی که BasePath مشتری اشاره می‌کند نصب نشده است. با app.Map("/doconut", branch => branch.UseDoconut())، مشتری از BasePath: 'doconut' استفاده می‌کند.

HTTP 500 با:

text
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 قبلاً یکی را ثبت کرده‌اند).

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

text
You Are Not Authorized To View This Page.

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

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

text
Document session not found. Please re-open document.

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

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

این‌ها حالت‌های شکست هستند که باید ابتدا پس از انتقال یک برنامه به‌دست بگیرید. هر سه باعث می‌شوند سرور به‌طور کامل کار کند، سند را به‌درستی رندر کند و هیچ‌چیزی در کنسول مرورگر گزارش ندهد.

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

javascript
function ctlDoc_OnViewerBusy() { /* نشانگر مشغولیت شما را نمایش بده */ }
function ctlDoc_OnViewerReady() { /* آن را مخفی کن */ }
function ctlDoc_Copy(text) { /* از متن کپی شده استفاده کنید */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* گزارش پیشرفت */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... گزینه‌های موجود شما ...
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

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

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

javascript
ResPath: 'doconut-res/images'   // یا '<your ResourcesPath>/images'

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

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

LicenseException با پیام رد — فایل لایسنس یافت شد اما رد شد (امضای نامعتبر، دستکاری شده، در لیست سیاه، یا ساختی خارج از بازه نسخه/به‌روزرسانی لایسنس). این وضعیت باز کردن را مسدود می‌کند (fail-fast) به جای تبدیل به واترمارک؛ برای دلیل به License.RejectionMessage مراجعه کنید.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

این پسوند فقط توسط یک افزونه (در اینجا: DICOM) مدیریت می‌شود. افزونه ثبت شده است، اما دیگر هیچ لایسنس‌ایی قابلیت آن را اعطا نمی‌کند — معمولاً یک لایسنس موقت که پس از شروع برنامه منقضی شده است. یک لایسنس که این قابلیت را بدهد نصب کنید و IsCapabilityGranted(LicenseCapability.Dicom) را روی IDoconutLicenseService تأیید کنید. یک حق‌الامتیاز غیر موقت گمشده یا ناکافی معمولاً زودتر، در زمان AddDoconut()، شکست می‌خورد.

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

هیچ نمایشگری — داخلی، افزونه یا سفارشی — این پسوند را ادعا نمی‌کند. فهرست فرمت‌های پشتیبانی‌شده را بررسی کنید؛ برای فرمت‌های خودتان، DoconutOptions.RegisterViewer می‌تواند یکی اضافه کند.

InvalidDataException — محتوای فایل خراب است یا با پسوند آن مطابقت ندارد (مثلاً فایلی که نامش تغییر یافته). قبل از باز کردن، بارگذاری‌ها را اعتبارسنجی کنید.

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

شما DocumentConverter را بدون ثبت افزونه Converter حل کردید.

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

InvalidOperationException که افزونه‌ای را از طریق AddPlugin ثبت کرده است — لایسنس غیر موقت فعلی این قابلیت افزونه را اعطا نمی‌کند. ثبت را حذف کنید یا لایسنس‌ای نصب کنید که این قابلیت را بدهد. یک لایسنس گمشده و یک فایل legacy TRIAL هیچ قابلیت افزونه‌ای را اعطا نمی‌کند.

ArgumentException از AddDoconut():

text
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 هدف‌گیری می‌کند netstandard2.1، بنابراین NuGet یک پروژه .NET Framework را رد می‌کند. این یک خطای بازگردانی قابل حل نیست: .NET Framework نمی‌تواند netstandard2.1 را مصرف کند. به جای آن از پکیج Doconut.NETFramework استفاده کنید.

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

text
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 سطح API متفاوتی نسبت به 26.7.0 دارد و به‌روزرسانی سازگاری نیست. بیشتر خطاها خطوط using هستند که به فضای نام ریشه‌ای Doconut منتقل شده‌اند؛ به جای اصلاح تک‌تک، از مهاجرت به .NET Standard 2.1 استفاده کنید.

TypeInitializationException در اولین فایل ارائه:

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

موتور ارائه به شدت به System.Drawing.Common نسخه 6.0.0 نیاز دارد (اعلام‌شده توسط پکیج). این وابستگی را حذف یا بازنویسی نکنید — هر باز کردن PPT/PPTX/PPS/POT/ODP بدون آن شکست می‌خورد.

خروجی به‌نظر نادرست می‌آید

صفحات دارای واترمارک هستند — برنامه در حالت ارزیابی است: فایل لایسنس یافت نشد، لایسنس موقت منقضی شده، یا دامنه نامعتبر. تحت یک لایسنس موقت فعال، فقط خروجی افزونه‌ها واترمارک می‌شود. یک ساخت که پس از تاریخ اشتراک لایسنس پرداختی منتشر شده است واترمارک نمی‌شود: باز کردن خطای LicenseException می‌دهد. به IDoconutLicenseService (License.IsLicenseFileFound، IsExpired، IsVersionValid، IsValidForDomain، License.RejectionMessage) نگاهی بیندازید — مرجع IDoconutLicenseService صفحه Licensing یک نقطه انتهایی آماده را نشان می‌دهد.

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

فونت‌های نادرست یا جایگزین — سرور فاقد فونت‌های سند است. آن‌ها را نصب کنید، یا FontFolders (در WordConfig/PptConfig) را به پوشه‌ای که حاوی آن‌هاست اشاره دهید.

یک حاشیه‌نویسی تصویر در نمایشگر نشان داده می‌شود اما خروجی دارای جعبه «Image blocked» است — میزبان تصویر دارای آدرس خصوصی یا لوپ‌بک است که سرور از دریافت آن خودداری می‌کند. به حاشیه‌نویسی‌ها مراجعه کنید.

ویژگی در ارزیابی کار می‌کرد، در تولید بی‌صدا است

سورپرایز کلاسیک راه‌اندازی: یک مجوز موقت فعال تمام قابلیت‌ها را می‌دهد؛ مجوز خریداری‌شده شما فقط آنچه را که خریدید، می‌دهد. بسته‌های جستجو و حاشیه‌نویسی می‌توانند وقتی قابلیت‌هایشان موجود نیست، ناپدید شوند. مبدل‌های ثبت‌شده یا افزونه‌های 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 است — فرمت حل‌شده مسیر جستجوی استانداردی ندارد. این تصمیم جدا از مجوز Search است؛ هر دو را تأیید کنید.
  • صفحه مقدار بازگشتی objViewer.Search(...) را می‌خواند — شمارش در آرگومان سوم آن، یک callback، می‌رسد.

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

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

آیا این صفحه مفید بود؟