פתרון בעיות

אבחון שגיאות נפוצות

כל הודעה למטה היא הטקסט המילולי שמייצר 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() לפני ענף ה‑middleware של 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.

האסימון פג (חלון זמן מתגלגל, ברירת מחדל 60 דקות — DocOptions.TimeOut) או שהסשן נסגר. פתחו מחדש את המסמך לקבלת אסימון חדש.

פתיחת מסמך נכשלת

LicenseException with a rejection message — קובץ הרישיון נמצא אך נדחה (חתימה לא תקפה, שונה, ברשימה שחורה, או בנייה מחוץ לחלון הגרסה/עדכון של הרישיון). מצב זה חוסם פתיחה (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 — הרישיון הנוכחי שאינו זמני אינו מעניק את היכולת לתוסף זה. הסר את הרישום או התקן רישיון שמעניק זאת. רישיון חסר וקובץ 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.

הטקסט רחב יותר או צר יותר מאשר ב‑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 שלך, ופלט האבחון של הרישיון.

האם דף זה היה מועיל?