מציג – תיעוד 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` למציג הסטנדרטי.

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

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

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

המפענח מצפה בדיוק לשישה שדות אחרי ה-^ האופציונלי. הגדרה לא תקינה מוחלפת ב‑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 של PNGים לכל עמוד עם אנוטציות משולבות

מטא‑נתוני DICOM

text

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

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

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

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

text

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

CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

ScriptConfig flags: 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 }))