عیب‌یابی

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

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

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

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

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

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

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

LicenseException با پیام رد — فایل لایسنس پیدا شد اما رد شد (امضای نامعتبر، دست‌کاری شده، فهرست سیاه، یا ساختی خارج از بازه نسخه/به‌روزرسانی لایسنس). این وضعیت باز کردن را مسدود می‌کند (به‌سرعت‑شکست) به‌جای کاهش به واترمارک؛ برای دلیل، 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 ثبت شده است — مجوز غیر موقت فعلی آن قابلیت افزونه را اعطا نمی‌کند. ثبت را حذف کنید یا مجوزی نصب کنید که آن را بدهد. یک مجوز گمشده و یک فایل 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.

اعتبارسنجی گزینه‌های سریع‌الاجرا — مسیر مشکل‌ساز را اصلاح کنید.

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

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

text
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.NET8 ثابت کرده است. کاهش نسخه را حذف کنید و بگذارید NuGet گراف بسته‌ها را بازگرداند (System.Text.Json 8.0.5 و System.Text.Encodings.Web 8.0.0).

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

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

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

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

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

لینوکس

باز کردن هر سندی با خطا مواجه می‌شود:

text
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

کتابخانهٔ پیکربندی فونت را نصب کنید: apt-get install -y libfontconfig1 (fontconfig در RHEL/Fedora). ببینید نصب.

باز کردن هر سندی با خطا مواجه می‌شود:

text
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.

برنامه به SkiaSharp جدیدتری ارجاع می‌دهد، به‌صورت مستقیم یا از طریق کتابخانهٔ دیگری. SkiaSharp.NativeAssets.Linux را با همان نسخهٔ SkiaSharp اضافه کنید.

باز کردن هر سندی با خطا مواجه می‌شود:

text
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.

میزبان یک پلتفرم پشتیبانی‌شده نیست. توزیع‌های Alpine و دیگر توزیع‌های مبتنی بر musl پشتیبانی نمی‌شوند: از یک تصویر مبتنی بر Debian یا Ubuntu استفاده کنید.

متن در مقایسه با ویندوز عریض‌تر یا باریک‌تر است، یا خطوط به‌صورت متفاوتی شکسته می‌شوند — فونت‌های سند نصب نشده‌اند، بنابراین Doconut نزدیک‌ترین فونت نصب‌شده را استفاده می‌کند. فونت‌های سازگار با متریک را نصب کنید (fonts-liberation برای Arial، Times New Roman و Courier New؛ fonts-crosextra-carlito و fonts-crosextra-caladea برای Calibri و Cambria)، یا فونت‌های دارای مجوز خود را به /usr/share/fonts/ کپی کنید و fc-cache -f را اجرا کنید. متن‌های آسیایی که به صورت جعبه‌های خالی نشان داده می‌شوند، به fonts-noto-cjk نیاز دارند.

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

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

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

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

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