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

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

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

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

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

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

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

הזרק אותו בכל מקום שבו אתה צריך אותו:

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

מה קורה בתוך OpenDocumentAsync

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

שלושת העומסים השונים נבדלים רק בקלט: נתיב קובץ, נתיב קובץ בתוספת תצורת פורמט‑פרטית (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 ב‑.NET 6
?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.

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

סגירת מסמך

csharp
viewer.CloseDocument(token);

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

מסקנות

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

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