איך הצופה עובד

מחזור חיי בקשת המסמך

Doconut מציג מסמכים כתמונות מדורגות המוגשות דרך middleware של ASP.NET Core. הבנת מחזור החיים — פתיחה, אסימון, בקשות דף, סגירה — מסבירה כמעט כל התנהגות שתראו, כולל הודעות השגיאה.

שלושת החלקים הפועלים

  • Viewer — השירות הציבורי שאתה מוזרק. הוא פותח מסמכים ומחזיר אסימוני סשן.
  • סשן המסמך — אובייקט בצד השרת המחזיק את המסמך הטעון, ממופה באמצעות אסימון ב-IMemoryCache.
  • ה‑middleware של Doconut — נוסף על ידי UseDoconut(); משיב לכל בקשה שהווידג'ט של הדפדפן מבצע (pages, thumbnails, search, annotations, …), תמיד מאומת באמצעות האסימון.

Viewer הוא חסר מצב — לפי תכנון

Viewer סגור, אינו מחזיק במצב מסמך לכל בקשה, ובכוונה אינו מממש את IDisposable. סשנים קיימים באופן עצמאי במנהל הסשנים ומנוקים עם תפוגת המטמון או באמצעות CloseDocument(token) מפורש.

אתה כבר לא בונה אותו. AddDoconut() רושמת אותו כשירות זמני; מוזרק אותו בכל מקום שבו אתה זקוק לו:

csharp
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

ביישום MVC, קח אותו כפרמטר של בנאי; בתצוגת Razor, השתמש ב-@inject Doconut.Viewer Viewer. מטמוני אפליקציה של מופעי Viewer אינם נדרשים יותר — ואינם נכונים יותר, מכיוון שהם אינם מחזיקים דבר שכדאי לשמור במטמון.

מה קורה בתוך OpenDocumentAsync

  1. שער הרישיון. רישיון שנדחה או שפג תוקפו (ברשימה שחורה, שונה, או גרסה מחוץ לחלון העדכון של הרישיון) זורק LicenseException מיד, עם סיבת הדחייה כהודעה — הפתיחה לעולם לא מתדרדרת בשקט עבור רישיון לא תקף (בניגוד לחסר). רישיון זמני או מנוי שפג תוקפו בלוח השנה הוא החריגה: הוא אינו זורק — הוא מתדרדר למים.
  2. יצירת סשן. מפעל הצופה בוחר את צופה הפורמט המתאים עבור סיומת הקובץ וטוען את המסמך (ראו Rendering Pipeline). הסשן נשמר ב-IMemoryCache תחת אסימון GUID חדש עם תפוגה מתזזת — DocOptions.TimeOut דקות, ברירת מחדל 60. כל בקשת דף מאפסת את השעון.
  3. רישום אבטחה. עם UnsafeMode = false (ברירת המחדל), האסימון קשור לסשן ASP.NET של הקורא: סמן secure-{token} נכתב לתוך הסשן, כך שרק סשן הדפדפן שפתח את המסמך יכול לבקש את הדפים שלו.
  4. האסימון מוחזר. הוא האישור היחיד לכל מה שמגיע לאחריו.

אין שלב חימום נפרד. הספרייה הקודמת חשפה את InitCache() למטרה זו; הוא אינו קיים יותר, ואין שום דבר שמחליף אותו.

שלושת העומסים השונים נבדלים רק בקלט: נתיב קובץ, נתיב קובץ בתוספת תצורת פורמט לכל פורמט (PdfConfig, WordConfig, …), או Stream בתוספת FileInfo שהרחבה שלו מניעה את זיהוי הפורמט.

איך הווידג'ט מקבל דפים

הווידג'ט של הלקוח קורא ל‑middleware של Doconut עם האסימון במחרוזת השאילתה. מה שה‑middleware עושה תלוי בבקשה:

שאילתהמטרה
?token=…&page=Nתמונת דף מרונדרת (PNG)
?token=…&page=N&thumb=1תמונת ממוזערת
?token=…&zoom=…רינדור דף מוגדל
?token=…&search=termחיפוש טקסט מלא (מבוסס רישיון)
?token=…&bookmarksמתאר המסמך/סימניות
?token=…&copy / &showlinks / &fileFormatהעתקת טקסט, קישורים ומידע על הפורמט
?token=…&metaמטא‑נתונים טכניים של DICOM; מחזיר 501 עבור סשן DICOM בחבילה זו
?token=…&action=rotate/flip/closeפעולות דף וסגירה מפורשת
?token=…&AnnSave=… / &AnnLoadשמירה/טעינה של אנוטציות

כל אחד מהנתיבים הללו מתבצע אימות תחילה:

  • אין אסימון → ה‑middleware מחזיר 404 (או באנר גרסה כאשר ShowDoconutInfo = true).
  • אסימון לא ידוע או שפג → תמונת שגיאה עם Document session not found. Please re-open document.
  • middleware של סשן חסר (עם UnsafeMode = false) → HTTP 500 עם Session middleware not configured. Call UseSession() before UseDoconut().
  • אסימון נפתח על ידי סשן דפדפן שונה → תמונת שגיאה עם You Are Not Authorized To View This Page.

היכן ה‑middleware מותקן

UseDoconut() משיב לבקשות שנושאות אסימון, בכל מקום שבו אתה מתקין אותו. הגדרה נפוצה שומרת על צורת הבקשה ההיסטורית של DocImage.axd על ענף MapWhen, כך שלקוח קיים ממשיך לקרוא ל‑URL שהוא תמיד קרא. מה שתבחר, ה‑BasePath של הלקוח חייב להתאים אליו — ראה תצורת הצופה.

שרת דפים מאחסון משותף במקום מהצומת הפותח הוא סידור שונה לחלוטין; ראה פריסות מבוזרות.

סגירת מסמך

csharp
viewer.CloseDocument(token);

CloseDocument מסיר את הסשן מהמטמון (שמשחרר את מנוע המסמך הבסיסי ומשחרר את הזיכרון שלו מייד), מוחק את הסמן secure-{token}, ומבטל את ההרשאה לגישה. קריאה אליו היא אופציונלית — תפוגה מתזזת עושה את אותו ניקוי אוטומטית — אך עבור מסמכים גדולים זהו הדרך המנומסת לשחרר זיכרון ברגע שהמשתמש מסיים.

הוא נקרא על ה‑Viewer המוזרק. הדפוס הקודם — בניית Viewer קצר-חיים בתוך בלוק using רק כדי לסגור אסימון — אין לו מקביל ואינו נדרש.

מסקנות

  • מסמך פתוח אחד = סשן אחד = אסימון אחד. אסימונים הם לכל סשן דפדפן, לא ל‑URL גלובליים.
  • האסימון פוג בתפוגה מתזזת; צופה שנשאר במצב חוסר פעילות מעבר ל‑DocOptions.TimeOut צריך פתיחה מחדש.
  • Viewer ניתן להזרקה ושיתוף בחופשיות; סשנים נושאים את כל המצב.

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