פתרון בעיות

כל הודעה למטה היא הטקסט המילולי ש‑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.

הטוקן נפתח על ידי מושב דפדפן שונה. גורמים נפוצים: קוביית ההפעלה (session cookie) אינה מגיעה לבקשות העמוד (הגדרת cross-origin, מדיניות 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 מבלי לרשום את תוסף ה‑Converter.

אתחול נכשל

InvalidOperationException שמזכיר תוסף שנרשם באמצעות AddPlugin — הרישיון הלא‑זמני הנוכחי אינו מעניק את היכולת לתוסף זה. הסר את הרישום או התקן רישיון שמעניק זאת. רישיון חסר וקובץ TRIAL מורשת אינם מעניקים יכולות תוסף.

ArgumentException from 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=10.0.0.0'

הפרויקט שלך קבע גרסה קבועה של System.Text.Json / System.Text.Encodings.Web מתחת ל‑10.0.x. הסר את ההורדה והתרן ל‑NuGet לשחזר את הגרסאות שה‑Doconut.NET8 מצהיר עליהן.

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

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 מכיוון שזו הגרסה האחרונה שמכבדת את המתג הזה.

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

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