عیبیابی
تشخیص خطاهای رایج
هر پیام زیر متن دقیق Doconut است که تولید میکند، بر اساس علائم سازماندهی شده است. خطای خود را پیدا کنید و راهحل را اعمال کنید.
نمایشگر چیزی نشان نمیدهد
ناحیه نمایشگر خالی، کنسول مرورگر پر از ۴۰۴ برای /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 با:
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 بدون جعبه کوکی)، یا برنامه دوباره راهاندازی شد (کلیدهای جلسه جدید). این لایه امنیتی همانطور که طراحی شده کار میکند — به مفاهیم اصلی → جلسات و امنیت مراجعه کنید. رد شدن یک تصویر است که با وضعیت 200 سرو میشود، بنابراین مانیتوری که فقط کدهای وضعیت را بررسی میکند، آن را بهعنوان یک صفحه میشمارد.
یک تصویر خطا با متن:
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) پردازش میشود. افزونه ثبت شده است، اما هیچ لایسنی دیگر قابلیت آن را اعطا نمیکند — معمولاً یک لایسنس موقت که پس از شروع برنامه منقضی شده است. یک لایسنس که آن را اعطا میکند نصب کنید و IsCapabilityGranted(LicenseCapability.Dicom) را روی IDoconutLicenseService تأیید کنید. یک حق دسترسی غیر موقت گم شده یا ناکافی معمولاً زودتر، در طول 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.اعتبارسنجی گزینههای سریعالاجرا — مسیر مشکلساز را اصلاح کنید.
خطاهای ساخت / وابستگی
خطای کامپایلر 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 همانطور که اعلام شده توسط بسته).
خروجی بهنظر نادرست میآید
صفحات دارای واترمارک هستند — برنامه در حالت ارزیابی است: فایل مجوز یافت نشد، مجوز موقت منقضی شده، یا دامنه نامعتبر. در زیر یک مجوز موقت فعال، فقط خروجی افزونه واترمارک میشود. یک ساخت که پس از تاریخ اشتراک مجوز پرداختشده منتشر شده باشد واترمارک نمیشود: باز کردن خطای LicenseException را ایجاد میکند. بررسی کنید IDoconutLicenseService (License.IsLicenseFileFound، IsExpired، IsVersionValid، IsValidForDomain، License.RejectionMessage) — مرجع IDoconutLicenseService صفحه Licensing یک نقطه انتهایی آماده را نشان میدهد.
اسناد قدیمی متن خراب نمایش میدهند — رمزگذاریهای صفحه کد بهطور پیشفرض در .NET 6 بارگذاری نمیشوند. یکبار در زمان راهاندازی اضافه کنید:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);فونتهای اشتباه یا جایگزین — سرور فاقد فونتهای سند است. آنها را نصب کنید، یا FontFolders (در WordConfig/PptConfig) را به پوشهای که حاوی آنهاست اشاره دهید. در لینوکس، به زیر نگاه کنید.
یک حاشیهنویسی تصویر در نمایشگر نشان داده میشود اما خروجی یک جعبه «Image blocked» دارد — میزبان تصویر دارای آدرس خصوصی یا لوپبک است که سرور از دریافت آن خودداری میکند. ببینید حاشیهنویسیها.
لینوکس
باز کردن هر سندی با خطا مواجه میشود:
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). ببینید نصب.
باز کردن هر سندی با خطا مواجه میشود:
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 اضافه کنید.
باز کردن هر سندی با خطا مواجه میشود:
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 نیاز دارند.
ویژگی در ارزیابی کار میکرد، در تولید بیصدا است
شگفتی کلاسیک هنگام راهاندازی: یک مجوز موقت فعال تمام قابلیتها را اعطا میکند؛ مجوز خریداریشده شما فقط آنچه را خریداری کردهاید، میدهد. بستههای جستجو و حاشیهنویسی میتوانند وقتی قابلیتهایشان موجود نیستند، ناپدید شوند. مبدل ثبتشده یا افزونههای 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 خود، و خروجی تشخیصهای مجوز با پشتیبانی تماس بگیرید.
آیا این صفحه مفید بود؟