מציג
מחלקת מציג המסמכים הראשית
Viewer (namespace Doconut) הוא נקודת הכניסה הציבורית לפתיחת מסמכים מבקרי MVC, דפי Web Forms, ומטפלים. זהו שירות זמני המורכב מ‑DoconutHost.Initialize; קבל אותו במיקום שבו אתה משתמש בו:
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 חייב לשאת את ההרחבה הנכונה — הוא בוחר את הפורמט |
// פתיחה פשוטה
string token = await viewer.OpenDocumentAsync(path);
// עם תצורה ואפשרויות לכל פורמט
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// מתוך העלאה (HttpPostedFileBase in MVC; HttpPostedFile in 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 וקוד אחר שאינו משתמש בדפים אסינכרוניים:
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 ב‑תוסף ממיר.
סגור מסמך
void CloseDocument(string token)מסיר את ההפעלה (משחרר את מנוע המסמך מיידית), מסיר את ההרשאה של האסימון מההפעלה של ASP.NET של הבקשה הנוכחית, ומבטל את האסימון. אופציונלי — תפוגה מתגלגלת מבצעת את אותה ניקוי — אך מומלץ למסמכים גדולים.
שאילתות סשן
| חבר | מחזיר |
|---|---|
int GetPageCount(string token) | סך כל העמודים של המסמך הפתוח |
(int Width, int Height) GetPageDimensions(string token, int page = 1) | גודל עמוד ברירת המחדל המוצג ב‑100 % זום — מרחב הקואורדינטות להערות שנבנות בקוד |
IReadOnlyList<string> GetWorksheetNames(string token) | גיליונות העבודה המוצגים של גיליון אלקטרוני, לפי סדר חוברת העבודה; ריק עבור מסמכים אחרים |
כל אחד זורק InvalidOperationException (Document session not found. Please re-open document.) אם האסימון אינו ידוע או פג, ו‑ArgumentException עבור אסימון ריק.
אפשרויות מסמך
אפשרויות בלתי תלויות בפורמט לכל פתיחה (מרחב שמות Doconut):
| סוג | מאפיין | ברירת מחדל | תיאור |
|---|---|---|---|
string | Password | "" | סיסמה למסמכים מוגנים (מועתקת לתצורת הפורמט אוטומטית). |
string | Watermark | "" | טקסט סימן מים מותאם אישית המצויר על דפים מוצגים — ראה למטה. |
int | TimeOut | 60 | תפוגה מתגלגלת של ההפעלה, בדקות. |
string | BrowserId | "" | חוות רשת: הדפדפן שהכרטיס החתום קשור אליו. הגדר זאת עם DoconutFarmBinding.EnsureBrowserId (ראה הפעלות ואבטחה). |
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~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| שדה | דוגמה | משמעות |
|---|---|---|
קידומת ^ | ^ | פריסת כל הפינות אופציונלית. ללא זה, נעשה השימוש במיקום הרגיל. |
| טקסט | Confidential | טקסט המצוין על כל דף. אסור להיות ריק. |
| צבע | Red | צבע בעל שם. |
| גודלגופן | 24 | גודל גופן; קלט מספרי לא תקין חוזר לברירת המחדל. |
| שםגופן | Verdana | משפחת גופנים. חייב להיות מותקן על השרת — ל‑Windows Server יש פחות גופנים מאשר למחשב שולחני. |
| שקיפות | 80 | 0 עד 255. חייב להיות ניתן לפירוש. |
| זווית | -45 | סיבוב במעלות; קלט מספרי לא תקין חוזר לברירת המחדל. |
ה‑parser מצפה בדיוק לשישה שדות לאחר ^ האופציונלי. הגדרה לא תקינה מוחלפת בטקסט Invalid Watermark גלוי במקום להיעלם בשקט.
החלטת רישיון
| מצב רישיון | ערך מותאם שסופק | תוצאה מוצגת |
|---|---|---|
| רישיון צופה בתשלום תקף | לא | דף נקי |
| רישיון צופה בתשלום תקף | כן | סימן מים מותאם אישית |
| רישיון זמני/הדגמה פעיל | לא | דף נקי |
| רישיון זמני/הדגמה פעיל | כן | סימן מים מותאם אישית |
| רישיון חסר, נדחה, פג, גרסה שגויה, או תחום לא תקין | כל אחד | סימן מים להערכה; הערך המותאם אינו מחליף אותו |
ההחלטה זהה חלה על דפים שניתנו ועל ייצוא הערות. סימן מים מותאם אישית הוא תכונה של יישום מורשה, ולא דרך להחליף את סימן המים להערכה.
API של הערות
טעינת והוצאת הערות בצד השרת. המדריך נמצא ב-הערות.
| Member | Purpose |
|---|---|
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(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | PNG אחד לכל עמוד, ההערות משולבות, נכתב ל‑directoryPath (נוצר אם חסר); מחזיר את מספר התמונות שנכתבו |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP של PNGs לכל עמוד עם ההערות משולבות |
מטא‑נתוני DICOM
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) מופצים רק כאשר הרישיון מעניק אותם.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; } // מצב רישיון, למניעת קוד init ribbon
bool IsAnnotationEnabled { get; }דגלי CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (מוגבל חיפוש), IncludeAnnotationCss (מוגבל הערה).
דגלי ScriptConfig: IncludeJQuery (נדרש על‑ידי כולם), IncludeBootstrap, IncludeViewerScripts (סקריפטים ליבת הצופה), IncludeSearchScripts ו‑IncludeSearchBar (מוגבל חיפוש), IncludeAnnotationScripts ו‑IncludeAnnotationBar (מוגבל הערה), EmitFeatureFlags (ברירת מחדל true: גם כותב סקריפט inline window.Doconut.features = { search, annotation, editor }; הגדר אותו ל‑false תחת Content‑Security‑Policy שחוסמת סקריפטים inline).
שניהם מחזירים HTML: כתבו אותם עם @Html.Raw(...) ב‑MVC 5 (הפקו אותם בבקר — לתצוגות אין @inject) או עם <%= %> ב‑Web Forms. התחלה מהירה מציגה את שניהם.
RenderViewer
string RenderViewer(string elementId, string token, ViewerConfig? config = null)מחזיר בלוק <script> שמאתחל את הווידג'ט על האלמנט עם id elementId ומציג את המסמך: docViewer({...}) נבנה מה‑ViewerConfig (ברירת מחדל: BasePath: '/', ResPath: 'doconut-res/images'), ואז .View(token). כתבו זאת אחרי סקריפטי הצופה. הסקריפט שנוצר אינו שומר הפנייה לאובייקט הצופה, ולכן דף עם סרגל כלים משלו צריך לאתחל את הווידג'ט ידנית במקום זאת. ראה תצורת הצופה.
חוות אינטרנט
string? AccessToken מחזיק את הכרטיס החתום שהונפק על‑ידי הפתיחה האחרונה כאשר מצב מבוזר פעיל ו‑UnsafeMode הוא false; הוא null בשרת יחיד. שלחו אותו לווידג'ט עם הטוקן: objViewer.View(token, accessToken).
האם דף זה היה מועיל?