פתרון בעיות

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

הצופה מציג שום דבר

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

HTTP 500 עם:

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

אבטחת האסימון של Doconut (פעילה כברירת מחדל) דורשת מצב סשן של ASP.NET. הוסיפו builder.Services.AddSession() ו‑app.UseSession() לפני ענף האמצעי של Doconut. מצב הסשן דורש גם מטמון: באפליקציית minimal‑API הוסיפו builder.Services.AddDistributedMemoryCache() , או שהאפליקציה תפסיק ב‑הפעלה עם 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) או שהסשן נסגר. פתחו מחדש את המסמך לקבלת אסימון חדש.

השרת תקין אך העמוד מתנהג בצורה שגויה — ללא שגיאות כלל

אלו מצבי הכשל שכדאי לחשוד בהם תחילה לאחר העברת יישום. שלושת המקרים משאירים את השרת פועל באופן מושלם, מציגים את המסמך כראוי, ולא מדווחים על שום דבר בקונסולת הדפדפן.

ספינר עסוק שלעולם לא מפסיק.
הקריאות חזרה של הצופה שלכם מוגדרות כפונקציות גלובליות בשם מזהה המכולה — ctlDoc_OnViewerReady() והחברים. הצופה הקודם חיפש שמות אלה; הצופה הנוכחי אינו עושה זאת. המטפל שהיה מסתיר את הספינר פשוט אף פעם לא רץ. העבירו את הפונקציות כאופציות במקום זאת:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

המסמך מאחורי הספינר תקין. רשימת האופציות המלאה נמצאת ב‑תצורת הצופה.

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

ResPath: 'doconut-res/images'   // or '<your ResourcesPath>/images'

אריחים שבורים לדפים מאוחרים יותר כאשר מגישים מאחסון משותף.
דפים שעדיין נכתבים משיבים 202 Accepted. לקוח ללא retryOn409: true מתייחס לכך כתמונה שנכשלה. ראו פריסות מבוזרות.

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

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.

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

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

החבילה לא תותקן כלל — Doconut.NETStandard 26.8.0 ממקמת את netstandard2.1, ולכן NuGet דוחה פרויקט .NET Framework. זו אינה שגיאת שחזור שניתנת לתיקון: .NET Framework אינו יכול לצרוך netstandard2.1. השתמש בחבילה Doconut.NETFramework במקום.

שגיאת מהדר CS1705, או בזמן ריצה בעת פתיחת מסמך:

Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

הפרויקט שלך קבע גרסה של System.Text.Json או System.Text.Encodings.Web מתחת לתלות 9.0.x שהוגדרה על ידי Doconut.NETStandard. הסר את ההורדה והתרן ל‑NuGet לשחזר את גרף החבילות (System.Text.Json 9.0.0 ו‑System.Text.Encodings.Web 9.0.0 בחבילה 26.8.0 שנבדקה).

קיר של שגיאות קומפילציה מיד לאחר עדכון החבילה — זה צפוי. גרסה 26.8.0 מציגה ממשק API שונה מ‑26.7.0, ולא מדובר בעדכון תואם. רוב השגיאות הן שורות using שהועברו למרחב השמות הראשי Doconut; התמודד עם זה דרך הגירה ל‑.NET Standard 2.1 במקום לתקן אחת אחת.

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 מציגה נקודת קצה מוכנה.

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

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