מציג – תיעוד Doconut

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

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

פתיחת מסמך (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)`	המסמך אינו קובץ על הדיסק (העלאה, מסד נתונים, blob). `fileInfo` חייב לכלול את ההרחבה הנכונה — היא מניעה את זיהוי הפורמט

csharp

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
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` (ראו מושגים מרכזיים → סשנים ואבטחה).

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

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

סימן מים מותאם (Custom watermark)

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
    });

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

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

החלטת רישיון (License decision)

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

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

API של הערות (Annotations 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 של PNGים לכל עמוד עם הערות משולבות

מטא‑נתוני DICOM (DICOM metadata)

text

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

מחזיר מטא‑נתוני תגיות DICOM עבור סשנים שנפתחו דרך תוסף DICOM; null עבור מסמכים שאינם DICOM.

עוזרי משאבים — ReferenceCss / ReferenceScripts (Resource helpers)

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

text

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

דגלי CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

דגלי ScriptConfig: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts and IncludeSearchBar (search-gated), IncludeAnnotationScripts and IncludeAnnotationBar (annotation-gated).

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 }))