פתרון בעיות

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

הצופה מציג ריק

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

HTTP 500 עם:

Session middleware not configured. Call UseSession() before UseDoconut().

אבטחת האסימון של Doconut (פעילה כברירת מחדל) דורשת מצב סשן של ASP.NET. הוסיפו builder.Services.AddSession() ו‑app.UseSession() לפני סניף ה‑middleware של Doconut.

תמונת שגיאה באזור הדף מציגה:

You Are Not Authorized To View This Page.

האסימון נפתח על‑ידי סשן דפדפן שונה. גורמים נפוצים: קוביית הסשן אינה מגיעה לבקשות העמוד (הגדרה חוצת‑מקור, מדיניות SameSite, לקוח API ללא קוביית עוגיות), או שהאפליקציה הופעלה מחדש (מפתחות סשן חדשים). זהו שכבת האבטחה פועלת כמתוכנן — ראו מושגים בסיסיים → סשנים ואבטחה.

תמונת שגיאה מציגה:

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

אתחול נכשל

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.

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

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

שגיאת מהדר 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 בחבילה המ audited 26.7.0).

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

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. הוסיפו פעם אחת באתחול:

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 שלכם, ופלט האבחון של הרישיון.