Troubleshooting

Diagnose common errors

כל ההודעות למטה הן הטקסט המילולי ש‑Doconut מייצר, מאורגנות לפי סימפטום. מצאו את השגיאה שלכם, יישמו את התיקון.

המציג אינו מציג דבר

אזור מציג ריק, קונסול הדפדפן מלא ב‑404 עבור /doconut-res/...
UseDoconutResources() חסר, או ממוקם אחרי UseDoconut(). הוא חייב לבוא ראשון בצינור.

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(), אחרת האפליקציה תפסיק ב‑startup עם Unable to resolve service for type 'IDistributedCache' (אפליקציות MVC ו‑Razor Pages רושמות אחד כבר).

תמונה עם הודעת שגיאה באזור העמוד:

text
You Are Not Authorized To View This Page.

האסימון נפתח על‑ידי סשן דפדפן שונה. גורמים נפוצים: קוביית הסשן אינה מגיעה לבקשות העמוד (הגדרות cross‑origin, מדיניות SameSite, לקוח API ללא cookie jar), או שהאפליקציה הופעלה מחדש (מפתחות סשן חדשים). זהו שכבת האבטחה פועלת כמתוכנן — ראו Core Concepts → Sessions & Security.

תמונה עם הודעת שגיאה:

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

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

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

LicenseException עם הודעת דחייה — קובץ הרישיון נמצא אך נדחה (חתימה לא תקינה, שינוי, ברשימת שחור, או בנייה מחוץ לחלון הגרסה/עדכון של הרישיון). מצב זה חוסם פתיחה (fail‑fast) במקום להחליש למים; קראו License.RejectionMessage לקבלת הסיבה.

LicenseException:

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

ההרחבה נתמכת רק על‑ידי תוסף (כאן: DICOM) והיכולת אינה ניתנת יותר. רשמו את התוסף ואמתו lic.IsCapabilityGranted(LicenseCapability.Dicom). חוסר או חוסר זכאות זמנית בדרך כלל נכשל מוקדם יותר במהלך 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 ללא רישום תוסף הממיר.

אתחול נכשל

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.

אימות אפשרויות fail‑fast — תקנו את הנתיב הפוגע.

שגיאות בנייה / תלות

שגיאת מהדר 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.NET6. הסירו את ההורדה והניחו ל‑NuGet לשחזר את גרף החבילות (System.Text.Json 8.0.6 ו‑System.Text.Encodings.Web 8.0.0 בחבילה המ audited 26.7.0).

TypeInitializationException על קובץ המצגת הראשון:

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

מנוע המצגות דורש בחובה System.Drawing.Common 6.0.0 (כפי שמוגדר בחבילה). אל תסירו או תעקפו תלות זו — כל פתיחה של PPT/PPTX/PPS/POT/ODP תיכשל בלעדיה.

הפלט נראה שגוי

דפים נושאים סימן מים — האפליקציה במצב הערכה: לא נמצא קובץ רישיון, חלון זמני או מנוי פג, או דומיין לא תקין. בחנו IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — הפנייה של דף הרישוי ל‑IDoconutLicenseService מציגה נקודת קצה מוכנה.

מסמכים ישנים מציגים טקסט מעוות — קידודי דפי קוד אינם נטענים כברירת מחדל ב‑.NET 6. הוסיפו פעם אחת באתחול:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

גופנים שגויים או מוחלפים ב‑Linux/Docker — המכולה חסרה את הגופנים של המסמך. הפנו FontFolders (ב‑WordConfig/PptConfig) לתיקיית גופנים מותקנת.

מצגות נפתחות אך אינן מציגות ב‑Linux/macOS — מנוע PPT/PPTX/PPS/POT/ODP דורש libgdiplus מקומי בנוסף ל‑System.Drawing.EnableUnixSupport=true. החבילה מספקת System.Drawing.Common 6.0.0 מכיוון שזו הגרסה האחרונה שמכבדת את המתג הזה.

תכונה עבדה בהערכה, שקטה בייצור

הפתעה קלאסית ב‑go‑live: רישיון זמני פעיל מעניק כל יכולת; הרישיון שנרכש מעניק רק מה שנקנה. חבילות חיפוש והערות יכולות להיעלם כאשר היכולות חסרות. תוספי 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 לאחר האתחול — הפורמט שנפתר אינו בעל נתיב חיפוש סטנדרטי. פסק דין זה נפרד מרישיון החיפוש; אמתו את שניהם.

עדיין תקועים?

בודדו את הבעיה מול אפליקציית Quick Start המינימלית; אם היא מתרחשת שם, פנו לתמיכה עם המסמך, קובץ Program.cs שלכם, ופלט האבחון של הרישיון.

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