פתרון בעיות
אבחון שגיאות נפוצות
כל הודעה למטה היא הטקסט המילולי ש‑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 עם:
Session middleware not configured. Call UseSession() before UseDoconut().אבטחת האסימון של Doconut (פעילה כברירת מחדל) דורשת מצב סשן של ASP.NET. הוסיפו builder.Services.AddSession() ו‑app.UseSession() לפני ענף ה‑middleware של 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. הסירוב הוא תמונה שמוגשת עם סטטוס 200, ולכן מנגנון שמבצע בדיקה רק של קודי סטטוס סופר זאת כעמוד.
תמונת שגיאה עם הטקסט:
Document session not found. Please re-open document.האסימון פג (חלון זמן מתגלגל, ברירת מחדל 60 דקות — 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 בעמוד הרישוי מציגה נקודת קצה מוכנה.
מסמכים ישנים מציגים טקסט מעוות — קידודי דפי קוד אינם נטענים כברירת מחדל ב‑.NET 6. הוסף פעם אחת באתחול:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);גופנים שגויים או מוחלפים — השרת חסר את הגופנים של המסמך. התקן אותם, או הפנה את FontFolders (ב‑WordConfig/PptConfig) לתיקייה שמכילה אותם. בלינוקס, ראה למטה.
הערת תמונה מוצגת במציג אך הייצוא מציג תיבת "תמונה חסומה" — למארח התמונה יש כתובת פרטית או לולאה, שהשרת מסרב להביא. ראה הסברים.
לינוקס
פתיחת כל מסמך נכשלת עם:
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.
הטקסט רחב יותר או צמוד יותר מאשר ב‑Windows, או שהשורות נשברות באופן שונה — הגופנים של המסמך אינם מותקנים, ולכן 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(...)— הספירה מגיעה בארגומנט השלישי שלו, קריאת חוזרת.
עדיין תקועים?
בידדו את הבעיה מול אפליקציית Quick Start המינימלית; אם היא מתרחשת שם, פנו לתמיכה עם המסמך, ה‑Program.cs שלכם, ופלט האבחון של הרישיון.
האם דף זה היה מועיל?