פתרון בעיות

אבחון שגיאות נפוצות

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

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

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

הצופה מדווח The viewer handler could not be reached (no response).
הבקשה מעולם לא קיבלה תשובה. גורם נפוץ הוא BasePath שמתחיל ב‑/: '/doconut' הופך ל‑//doconut/DocImage.axd, בקשה למארח אחר. כתוב זאת ללא הקו המוביל (/), כלומר BasePath: 'doconut'.

הצופה מדווח Please make sure your middleware is configured.
קצה העמוד השיב 404: UseDoconut() אינו מותקן במקום שה‑BasePath של הלקוח מצביע אליו. עם app.Map("/doconut", branch => branch.UseDoconut()), הלקוח משתמש ב‑BasePath: 'doconut'.

HTTP 500 עם:

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

אבטחת האסימון של Doconut (פעילה כברירת מחדל) דורשת מצב סשן של ASP.NET. הוסף את builder.Services.AddSession() ו‑app.UseSession() לפני ענף ה‑middleware של Doconut. למצב הסשן נדרש גם מטמון: באפליקציית minimal‑API הוסף את builder.Services.AddDistributedMemoryCache(), או שהאפליקציה תפסיק ב‑הפעלה עם Unable to resolve service for type 'IDistributedCache' (אפליקציות MVC ו‑Razor Pages כבר רושמות אחד).

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

text
You Are Not Authorized To View This Page.

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

תמונת שגיאה עם הטקסט:

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

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

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

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

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

javascript
function ctlDoc_OnViewerBusy() { /* הצג את מחוון העומס שלך */ }
function ctlDoc_OnViewerReady() { /* הסתר אותו */ }
function ctlDoc_Copy(text) { /* השתמש בטקסט שהועתק */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* דווח על התקדמות */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... האפשרויות הקיימות שלך ...
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

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

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

javascript
ResPath: 'doconut-res/images'   // או '<your ResourcesPath>/images'

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

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

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

LicenseException:

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

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

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

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

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

text
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 הוא ממשק API שונה מ‑26.7.0, לא עדכון תואם. רוב ה שגיאות הן שורות using שהועברו למרחב השמות השורש Doconut; עבוד דרך העבר ל‑.NET Standard 2.1 במקום לתקן אותן אחת אחת.

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

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

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

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

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

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

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

הערת תמונה מוצגת במציג אך הייצוא מציג תיבת "Image blocked" — למארח התמונה יש כתובת פרטית או לופבק, שהשרת מסרב לקבל. ראה הערות.

תכונה פעלה במצב הערכה, שקטה בייצור

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

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

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

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