פתרון בעיות

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

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

You Are Not Authorized To View This Page.

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

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

Compiler error CS1705, or at runtime when opening a document:

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 on the first presentation file:

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