יישום ניהול מסמכים עם Doconut

תהליך ניהול מסמכים בפורטל .NET בדרך כלל דורש שלושה דברים:

1. דרך לטעון קבצי PDF, קבצי Office, שרטוטי CAD או תמונות מבלי לכתוב מציג מאפס.
2. אסימון מאובטח שמקשר את המסמך הטעון למפגש הדפדפן הנוכחי.
3. שלב ניקוי שמשחרר זיכרון ברגע שהמשתמש מסיים.

Doconut מספק את כל שלוש האפשרויות דרך שירות Viewer יחיד, סשן IMemoryCache קל משקל, וקריאות CloseDocument מפורשות.

---

1. רישום המציג במכולת ה‑DI

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

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

---

2. הוספת ה‑middleware שמשרת תמונות עמודים, תמונות ממוזערות ונתוני הערות

הגדר את ה‑middleware של Doconut בצינור הבקשות כך שכל בקשה שמכילה מחרוזת שאילתה ?token= תטופל על‑ידי Doconut. ה‑middleware אוכף את סמן האבטחה ברירת המחדל (secure-{token}) כאשר UnsafeMode הוא false (ברירת המחדל) ומשרת תמונות עמודים, תמונות ממוזערות ונתוני הערות.

מיקום ה‑middleware בסניף ייעודי משאיר את שאר הצינור ללא שינוי ומאפשר סקיילינג אופקי ללא סשנים דביקים.

---

3. פתיחת מסמך וקבלת אסימון סשן אטום

צור נקודת קצה יחידה שמקבלת נתיב קובץ (או זרם) ומחזירה את האסימון. האסימון הוא האישור היחיד שהווידג'ט של הלקוח רואה.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // הטוקן הוא אטום — העבר אותו לווידג'ט, לעולם אל תתעד או תשמר אותו.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Contract.pdf");
    return Results.Ok(new { token });
});

מה קורה בתוך OpenDocumentAsync

1. שער הרישיון – רישיון לא תקין זורק LicenseException מיידית.
2. יצירת סשן – Doconut בוחר את מציג הפורמט המתאים (PDF, Word, DWG, …) ושומר את המנוע ב‑IMemoryCache תחת אסימון GUID.
3. רישום אבטחה – עם UnsafeMode = false האסימון קשור לסשן ASP.NET של הקורא דרך סמן secure-{token}. רק סשן הדפדפן הזה יכול לבקש עמודים.
4. החזרת אסימון – הלקוח מקבל את האסימון ומשתמש בו לכל בקשה נוספת (/DocImage.axd?token=…).

תוקף ההחלקה ברירת המחדל הוא 60 דקות (ניתן להגדירו דרך DocOptions.TimeOut). כל בקשת עמוד מאפסת את השעון, כך שסשנים במצב המתנה נעלמים אוטומטית.

---

4. הצגת המסמך בצד הלקוח

מהדפדפן אתה קורא לנקודת הקצה, תופס את האסימון, ומעביר אותו לווידג'ט של Doconut:

fetch('/api/open', { method: 'POST' })
    .then(r => r.json())
    .then(d => {
        const token = d.token;
        objViewer.View(token);   // ווידג'ט JavaScript המסופק על‑ידי Doconut
    });

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

---

5. סגירת המסמך ברגע שהמשתמש עוזב את המציג

לקבצי PDF או CAD גדולים יש לשחרר את מנוע הרינדור מיידית. קרא CloseDocument מנקודת קצה בצד השרת או מאירוע “unload” של הווידג'ט.

// נקודת קצה בצד השרת
app.MapPost("/api/close", (Viewer viewer, string token) =>
{
    viewer.CloseDocument(token);
    return Results.Ok();
});

// קריאה ישירה מהווידג'ט (אם אתה חושף את הטוקן לבקאנד)
viewer.CloseDocument(token);

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

---

6. אופציונלי: המרת מסמך בשרת

אם תהליך העבודה שלך דורש ייצוא PDF של קובץ Word שהועלה, אפשר את תוסף ה‑Converter בתצורת Doconut (ראה תיעוד). לאחר שהתוסף נרשם תוכל להזריק DocumentConverter ולקרוא למתודה ConvertAsync שלו. ההמרה מתבצעת בשרת, ולכן אינך צריך Office מותקן על שרת האינטרנט.

---

7. שיקולי סקיילינג לניהול מסמכים ברמת ארגון

• חזיתות ללא מצב – ווידג'ט המציג לעולם לא מחזיק נתוני מסמך; כל העיבוד הכבד נשאר על השרת.
• מטמון מבוזר – החלף את המטמון בזיכרון ברירת המחדל עם ספק מבוזר (Redis, NCache) אם אתה מריץ מספר צמתים של חוות אינטרנט. מיפוי האסימון‑לסשן פועל ללא שינוי מכיוון שה‑middleware קורא מה‑IMemoryCache המוגדר.
• משימות רקע – אתה יכול לפתוח מסמכים מראש בעובד רקע, לאחסן את האסימון במטמון, ולהעביר אותו לממשק משתמש מאוחר יותר. רק לזכור שכל אסימון הוא לשימוש יחיד לכל סשן; שימוש חוזר דורש קריאה חדשה ל‑OpenDocumentAsync.

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

---

8. רשימת בדיקה מהירה ליישום מוכן לייצור

שלב	פעולה
1	רשום שירותי Doconut בProgram.cs (אמת רישיון).
2	הוסף middleware של Doconut בסניף ייעודי.
3	חשוף נקודת קצה /api/open שמקראת OpenDocumentAsync.
4	העבר את האסימון שהוחזר לobjViewer.View(token) בצד הלקוח.
5	קרא CloseDocument(token) כאשר המציג מוסתר או שהדף מתנתק.
6	(אופציונלי) אפשר ConverterPlugin אם אתה צריך המרה בצד השרת.
7	(אופציונלי) החלף IMemoryCache במטמון מבוזר לסקיילינג אופקי.

עקוב אחרי הרשימה, ויש לך זרימת ניהול מסמכים מלאה, מאובטחת וביצועים גבוהים שנבנתה על מציג .NET הטבעי של Doconut.

---