מציג – Doconut תיעוד

Viewer (namespace Doconut) הוא נקודת הכניסה הציבורית לפתיחת מסמכים מדפי Razor, בקרים של MVC, רכיבי Blazor, או API מינימליים. הוא סגור, נרשם כשירות זמני על‑ידי AddDoconut(), ונפתר באמצעות הזרקת קונסטרקטור — לעולם אל תבנה אותו ישירות.

Viewer אינו מחזיק במצב per‑request ומתכוון לא לממש IDisposable: סשני המסמכים חיים באופן עצמאי במטמון הסשנים, ולכן השמדת השירות לא יכולה לפגוע במסמך פתוח (ראה Core Concepts → How the Viewer Works).

OpenDocumentAsync

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

גרסה	מתי להשתמש
`Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)`	פתיחה מהדיסק עם זיהוי פורמט אוטומטי והגדרת ברירת המחדל של הפורמט
`Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)`	נדרשות אפשרויות רינדור לכל פורמט (`PdfConfig`, `WordConfig`, …)
`Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)`	המסמך אינו קובץ על הדיסק (העלאה, מסד נתונים, בלוב). `fileInfo` חייב לשאת את ההרחבה הנכונה — היא מניעה את זיהוי הפורמט

csharp

// פתיחה פשוטה
string token = await viewer.OpenDocumentAsync(path);

// עם תצורה ואפשרויות לכל פורמט
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// מתוך העלאה
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

חריגות לטיפול:

LicenseException — רישיון שנמצא נדחה (ההודעה נושאת את סיבת הדחייה), או שהפורמט זקוק ליכולת תוסף שאינה ניתנת יותר. פקיעת לוח שנה ללא הודעת דחייה מתרסקת לרינדור עם סימן מים במקום לזרוק חריגה.
FormatNotSupportedException — Document format '<extension>' is not supported.
InvalidDataException — תוכן הקובץ פגום או אינו תואם להרחבה שלו.

CloseDocument

text

void CloseDocument(string token)

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

GetPageCount

text

int GetPageCount(string token)

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

DocOptions

אפשרויות לכל פתיחה, בלתי תלויות בפורמט (namespace Doconut):

סוג	מאפיין	ברירת מחדל	תיאור
`string`	`Password`	`""`	סיסמה למסמכים מוגנים (מועתקת לתצורת הפורמט אוטומטית).
`int`	`ImageResolution`	`0`	מיושן. נשמר רק לצורך תאימות — במקום זאת הגדר `ImageResolution` בתצורת הפורמט.
`string`	`Watermark`	`""`	טקסט סימן מים מותאם אישית המצויר על דפים מרונדרים. מחרוזת פורמט: `"^Text~Color~FontSize~FontName~Opacity~Angle"`, לדוגמה `"^Sample Copy~Red~24~Verdana~80~-45"`.
`int`	`TimeOut`	`60`	פג תוקף החלקה של הסשן בדקות.
`bool`	`IsSecured`	`true`	לא נאכף כרגע — שמור. קשירת אסימון נשלטת גלובלית על‑ידי `DoconutOptions.UnsafeMode` (ראה Core Concepts → Sessions & Security).

המחלקה גם חושפת מאפיינים מיוחדים שנועדו להיות מחוץ לזרימת הצפייה הרגילה של מארח יחיד:

סוג	מאפיין	ברירת מחדל	תיאור
`bool`	`IsWebFarm`	`false`	מסמן את פעולת הפתיחה כתרחיש web‑farm. השתמש רק עם ארכיטקטורת האחסון/סשן המשותפת המתאימה.
`string`	`WebFarmPath`	`""`	נתיב משותף המשמש בתהליך העבודה המיוחד של web‑farm. ריק במציג הרגיל של מארח יחיד.
`bool`	`EditMode`	`false`	שמורה לתהליך העבודה של העורך המופץ בנפרד; השאר את `false` למציג הסטנדרטי.

סימן מים מותאם אישית

DocOptions.Watermark משתמש בשישה שדות מופרדים בקו תחתי. קידומת אופציונלית ^ מבקשת פריסת כל הפינות:

text

^Text~Color~FontSize~FontName~Opacity~Angle

csharp

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

שדה	דוגמה	משמעות
קידומת `^`	`^`	פריסת כל הפינות אופציונלית. ללא זה, נעשה שימוש במיקום סימן המים הרגיל.
טקסט	`Confidential`	טקסט שמוצג בכל עמוד. אסור שיהיה ריק.
צבע	`Red`	צבע בשם שמובן על ידי שכבת הציור.
גודל גופן	`24`	גודל הגופן; קלט מספרי לא תקין חוזר לברירת המחדל של המנוע.
שם גופן	`Verdana`	משפחת הגופנים המבוקשת. ודא שהיא מותקנת בסביבת הפריסה.
שקיפות	`80`	ערך בייט מ-0 עד 255. חייב להתפרש בהצלחה.
זווית	`-45`	זווית סיבוב במעלות; קלט מספרי לא תקין חוזר לברירת המחדל.

ה-parser מצפה בדיוק לשישה שדות אחרי ה-^ האופציונלי. הגדרה לא תקינה מוחלפת ב-Invalid Watermark הגיבוי הגלוי של ה-SDK במקום להיעלם בשקט.

החלטת רישיון

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

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

ממשק API של הערות

טעינת והייצוא של הערות בצד השרת. המדריך המלא נמצא במדריכים → הערות; המבט הכללי הוא:

חבר	מטרה
`AnnotationManager GetAnnotationManager(string token)`	מנהל הקשור למימדי העמוד של הסשן הפתוח
`AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)`	מנהל עם מימדי עמוד מפורשים
`AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)`	מנהל בלתי תלוי בסשן
`void LoadAnnotationData(string token, AnnotationManager manager)`	טען הערות שנבנו ב-C# לתוך הסשן
`void LoadAnnotationData(string token, string annotationData)`	טען הערות מהדף המוצפן/מעטפת Base64 שמוחזרת על ידי `AnnotationManager.GetAnnotationData()`
`void LoadAnnotationXML(string token, XmlDocument annotationXml)`	טען הערות מ-XML
`XmlDocument GetAnnotationXML(string token)`	ייצא את ההערות של הסשן כ-XML
`Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)`	PDF עם ההערות משולבות
`Task<int> ExportAnnotationsToPngAsync(…)`	קבצי PNG עם ההערות משולבות
`Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)`	קובץ ZIP של PNGs לכל עמוד עם ההערות משולבות

מטא-נתוני DICOM

text

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

המתודה קיימת למטרת התאמת API, אך צופה ה-DICOM של .NET 6 אינו יכול לספק תגיות טכניות. הוא מחזיר null עבור סשנים של DICOM ולא-DICOM; בסשן DICOM הוא גם כותב אזהרה חד-פעמית שמסבירה את מגבלת הפלטפורמה. רינדור של עמודים, פריימים והנפשות נשאר נתמך.

עוזרי משאבים — ReferenceCss / ReferenceScripts

הפץ את תגי <link>/<script> עבור המשאבים המוטמעים שמסופקים על ידי UseDoconutResources(), בסדר תלות נכון. חבילות לתכונות המוגבלות ברישיון כגון חיפוש והערות נשלחות רק כאשר הרישיון מאפשר אותן, כדי לשמור על ממשק המשתמש של הלקוח תואם להתנהגות השרת.

text

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + מציג + חיפוש + הערה
string ReferenceScripts(ScriptConfig? config = null)

דגלי CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (מוגבל לחיפוש), IncludeAnnotationCss (מוגבל להערות).

דגלי ScriptConfig: IncludeJQuery (נדרש על ידי כל האחרים), IncludeBootstrap, IncludeViewerScripts (ליבה: docViewer.js + מפצל + קישורים), IncludeSearchScripts ו-IncludeSearchBar (מוגבל לחיפוש), IncludeAnnotationScripts ו-IncludeAnnotationBar (מוגבל להערות).

html

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

GetWorksheetNames – קבלת שמות הגיליונות

text

IReadOnlyList<string> GetWorksheetNames(string token)

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

הוספה ב‑26.9.0.