מציג – Doconut תיעוד

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

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

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

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

csharp

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

// עם תצורת per-format ואפשרויות
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)

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

GetWorksheetNames

text

IReadOnlyList<string> GetWorksheetNames(string token)

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

רק גליונות שמורנדים מופיעים ברשימה: גליונות מוסתרים וריקים מוחרמים, וכאשר ExcelConfig.SheetNames מגביל רינדור, רק הגליונות הללו מוצגים. גליון אינו תמיד עמוד אחד — גליון גדול מאוד מורנד על פני כמה עמודים. זורק חריגה אם האסימון אינו ידוע או פג תוקף.

הוסף ב‑26.9.0.

דגלי יכולת

חבר	משמעות
`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` (ראה Core Concepts → Sessions & Security).

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

סוג	מאפיין	ברירת מחדל	תיאור
`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
    });

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

כל אחד מהם דורש את אסימון המפגש. הספרייה הקודמת שהייתה ללא תלות במפגש
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 + מציג + חיפוש + הערה
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 צריכים
להסיר את ההעתקים הללו לאחר שהדף מוצג מהתגים שהופקו.