מציג – Doconut תיעוד

Viewer (namespace Doconut) הוא נקודת הכניסה הציבורית לפתיחת מסמכים מבקרי MVC, דפי Web Forms, ומטפלים. זהו שירות זמני המורכב מ-DoconutHost.Initialize; קבל אותו במקום שבו אתה משתמש בו:

csharp

var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() גם עובד לאחר ש-DoconutHost.Initialize רץ — הוא פותר את אותן השירותים — מה ששומר על קוד שהועבר מהחבילה הקלאסית בזמן הקומפילציה. לפני Initialize, הוא זורק InvalidOperationException.

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

OpenDocumentAsync

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

גרסה	מתי להשתמש
`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 });

// מתוך העלאה (HttpPostedFileBase ב‑MVC; HttpPostedFile ב‑Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

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

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

OpenDocument (סינכרוני)

לקוד‑ביק-אחורי של Web Forms וקוד אחר שאינו משתמש בדפים אסינכרוניים:

text

string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

כל אחד מחזיר את האסימון וגם מאחסן אותו ב-viewer.Token. fileName חייב לשאת את ההרחבה הנכונה. עטיפות אלו בטוחות לקריאה מדף Web Forms: נתיב הפתיחה לעולם אינו מתחדש בהקשר הבקשה של ASP.NET, ולכן המתנה עליו אינה יכולה לגרום לחסימה. הדבר לא נכון עבור כל API אסינכרוני של Doconut — ראה את סעיף Web Forms של תוסף הממיר.

סגירת מסמך

text

void CloseDocument(string token)

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

שאילתות סשן

חבר	מחזיר
`int GetPageCount(string token)`	סך כל העמודים של המסמך הפתוח
`(int Width, int Height) GetPageDimensions(string token, int page = 1)`	גודל העמוד המוצג כברירת מחדל ב‑100% זום — מרחב הקואורדינטות להערות שנבנו בקוד
`IReadOnlyList<string> GetWorksheetNames(string token)`	גיליונות העבודה המוצגים של גליון אלקטרוני, בסדר חוברת העבודה; ריק עבור מסמכים אחרים

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

אפשרויות מסמך

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

סוג	מאפיין	ברירת מחדל	תיאור
`string`	`Password`	`""`	סיסמה למסמכים מוגנים (מועתקת לתצורת הפורמט באופן אוטומטי).
`string`	`Watermark`	`""`	טקסט סימן מים מותאם אישית המצורף לעמודים המוצגים — ראה למטה.
`int`	`TimeOut`	`60`	תפוגת סשן מחליקה, בדקות.
`string`	`BrowserId`	`""`	חוות אינטרנט: הדפדפן שהכרטיס החתום קשור אליו. הגדר זאת עם `DoconutFarmBinding.EnsureBrowserId` (ראה Sessions & Security).
`string`	`UserId`	`""`	חוות אינטרנט: המשתמש המחובר שהכרטיס קשור אליו, מ`DoconutFarmBinding.ResolveUserId`.
`int`	`ImageResolution`	`0`	מיושן. הגדר `ImageResolution` בתצורת הפורמט במקום זאת.
`bool`	`IsSecured`	`true`	שמורה; לא מאוכזבת. בקרת גישה היא `DoconutOptions.UnsafeMode`.
`bool`	`IsWebFarm` / `string` `WebFarmPath`	`false` / `""`	נשמר עבור קוד שהועבר מהחבילה הקלאסית. הם לא מפעילים מצב חווה — `AddDoconutDistributed` עושה זאת.
`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`	משפחת גופנים. חייב להיות מותקן על השרת — ל‑Windows Server יש פחות גופנים מאשר למחשב שולחני.
Opacity	`80`	0 עד 255. חייב להיות ניתן לפירוש.
Angle	`-45`	סיבוב במעלות; קלט מספרי לא תקין חוזר לברירת המחדל.

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

החלטת רישיון

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

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

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)`	טען את המעטפה המוצפנת שהוחזרה על‑ידי `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)

בחבילה זו היא תמיד מחזירה null, ובקשת המטא‑נתונים של הווידג'ט משיבה 501 Not Implemented: קריאת תגיות DICOM אינה זמינה ב‑.NET Framework. הצגה DICOM — דפים, מסגרות והנפשה — עובדת. ראה תוסף DICOM.

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

הפץ את התגים <link> ו‑<script> עבור המשאבים שמודול המשאבים משרת תחת DoconutOptions.ResourcesPath, לפי סדר תלות. הקבצים לתכונות המוגבלות ברישיון (Search, Annotation) מופצים רק כאשר הרישיון מעניק אותם.

text

string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + מציג + חיפוש + הערה
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // מצב רישיון, לשמירה על קוד אתחול ribbon
bool IsAnnotationEnabled { get; }

CssConfig דגלים: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (מוגבל חיפוש), IncludeAnnotationCss (מוגבל אנוטציה).

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

שניהם מחזירים HTML: כתוב אותם עם @Html.Raw(...) ב‑MVC 5 (צור אותם בבקר — לתצוגות אין @inject) או <%= %> ב‑Web Forms. התחלה מהירה מציגה את שניהם.

RenderViewer

text

string RenderViewer(string elementId, string token, ViewerConfig? config = null)

מחזיר בלוק <script> שמאתחל את הווידג'ט על האלמנט עם המזהה elementId ומציג את המסמך: docViewer({...}) שנבנה מה‑ViewerConfig (ברירת מחדל: BasePath: '/', ResPath: 'doconut-res/images'), ואז .View(token). כתוב זאת אחרי סקריפטי הצופה. הסקריפט שנוצר אינו שומר הפניה לאובייקט הצופה, ולכן דף עם סרגל כלים משלו צריך לאתחל את הווידג'ט ידנית במקום זאת. ראה ViewerConfig.

חוות רשת

string? AccessToken מחזיק את הכרטיס החתום שהונפק על ידי הפתיחה האחרונה כאשר מצב מבוזר פעיל ו‑UnsafeMode הוא false; הוא null בשרת יחיד. שלח אותו לווידג'ט עם הטוקן: objViewer.View(token, access).