מציג – Doconut תיעוד

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

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

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

OpenDocumentAsync

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

עומס	מתי להשתמש
`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)

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

Capability flags

חבר	משמעות
`bool IsSearchEnabled`	הרישיון הנוכחי מעניק `Search`
`bool IsAnnotationEnabled`	הרישיון הנוכחי מעניק `Annotation`

השתמשו בזה בתצוגת Razor כדי להציג Ribbon מורשה רק כאשר השרת אכן ישרת אותו — ראה התחלה מהירה.

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`	מסמן את פעולת הפתיחה כתרחיש אחסון משותף. שימו לב להבדל באיות — הספרייה הקודמת כתבה זאת `IsWebfarm`.
`string`	`WebFarmPath`	`""`	נתיב משותף המשמש בתרחיש זה. בעבר נכתב `WebfarmPath`. ריק במציג של מארח יחיד רגיל, ולא נדרש בנתיב הפרסום המתואר ב-פריסות מבוזרות.
`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 של PNG לכל דף עם ההערות משולבות

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

מטא‑נתוני DICOM

text

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

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

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

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

text

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

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

ScriptConfig דגלים: IncludeJQuery (נדרש על‑ידי כל האחרים), IncludeBootstrap, IncludeViewerScripts (ליבת: docViewer.js + splitter + links), 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 }))

עוזרים אלה הם הדרך הנתמכת לספק את משאבי הדפדפן. יישומים שהעתיקו את docViewer.js, documentLinks.js, ו‑docViewer.UI.js לתוך wwwroot צריכים להסיר את ההעתקים האלה ברגע שהדף מוצג מהתגים שהופקו.