התחלה מהירה

הצגת המסמך הראשון שלך ב‑MVC 5 או Web Forms

המדריך הזה מעביר יישום ASP.NET על .NET Framework 4.7.2 מחבילה מותקנת למסמך שמוצג בדפדפן: Global.asax, נקודת קצה פתוחה, נכסי הצופה, הווידג'ט, והטוקן שמקשר ביניהם. הוא מניח שהרישומים של Web.config מ‑התקנה במקום — ללא המטפל DocImage.axd ומודול המשאבים, שום דבר למטה לא יוכל להגיע לשרת.

הרכבת Doconut ב‑Global.asax

‏Application_Start מלא עבור יישום MVC 5:

csharp
// Global.asax.cs - הרכבה פעם אחת לכל תהליך עובד, שחרור בעת כיבוי.
protected void Application_Start()
{
    Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.UnsafeMode  = false; // דף נשלח רק למפגש שפתח את המסמך
    });

    // MVC only: שמור את שני קצות Doconut מחוץ ל‑routing.
    RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}
  • Encoding.RegisterProvider עושה את דפי קוד המורשת שבהם משתמשים כמה פורמטים של מסמכים זמינים לתהליך. קרא זאת פעם אחת, לפני שהמסמך הראשון נפתח.
  • UnsafeMode = false הוא ברירת המחדל, כתוב כך שאף אחד לא יחליף אותו בטעות: DocImage.axd מגיש דף רק למפגש ASP.NET שפתח את המסמך.
  • שתי הקריאות של IgnoreRoute שומרות על ניתוב MVC רחוק מ‑DocImage.axd ו‑/doconut-res/*, שהמטפל והממודול משרתים. יישום Web Forms אין לו מסלולי MVC ואינו זקוק לשורה זו.
  • DoconutHost.Shutdown מפסיק את העבודה ברקע של Doconut ומשחרר את השירותים שלו כאשר מאגר האפליקציה מתחדש. זה בטוח לקרוא גם אם Initialize מעולם לא רץ.

פתיחת מסמך

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

ב‑MVC 5, פעולה של בקרת מקבלת את שירות Viewer מ‑DoconutHost.Services — ל‑MVC 5 אין הזרקת קונסטרקטור עבורו:

csharp
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

    // הטוקן אינו שקוף - העבר אותו לצופה, אל תתעד או תשמר אותו.
    string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
    return Json(new { token });
}

המסמך חייב להיפתח בתוך בקשה שיש לה מצב סשן, מכיוון שהפתיחה היא מה שמעניק למפגש ASP.NET הנוכחי גישה לדפים שלו. בקרי MVC ודפי Web Forms כוללים מצב סשן כברירת מחדל. IHttpHandler מותאם אישית אינו עושה זאת, אלא אם הוא מממש System.Web.SessionState.IRequiresSessionState. פתח מסמך ממטפל ללא זה, והצופה יציג "אינך מורשה לצפות בדף זה." בכל דף.

ב‑Web Forms, הדף עצמו יכול לפתוח את המסמך בקוד‑בייק שלו. OpenDocument היא הצורה הסינכרונית של OpenDocumentAsync, מיועדת לקוד‑בייק שאינו משתמש בדפים אסינכרוניים:

csharp
// Default.aspx.cs
protected string Token;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    Token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
}

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

הפנייה לנכסי הצופה

Viewer.ReferenceCss ו-Viewer.ReferenceScripts מפיקים את תגי <link> ו-<script> עבור הנכסים המוטמעים, בסדר תלות, ומצביעים על /doconut-res/. הווידג'ט הוא תוסף jQuery, ולכן jQuery מגיע ראשון.

MVC 5. לתצוגות אין @inject, ולכן יש לייצר את התגים בבקר ולהעביר אותם ב-ViewBag:

csharp
public ActionResult Index()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
    {
        IncludeBootstrapCss = true,
        IncludeViewerCss    = true
    });
    ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
    {
        IncludeJQuery        = true,
        IncludeBootstrap     = true,
        IncludeViewerScripts = true
    });
    return View();
}
html
@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)

השאירו עבודה זו בבקר. MVC 5 מקמפל תצוגות כאשר הן מוגשות לראשונה, וללא חבילת קומפיילר נוספת הקומפיילר הזה מבין רק C# 5 — אין ?., אין $"...", אין nameof. תצוגה שמשתמשת בהם מקמפלת בצורה נקייה ב‑Visual Studio, ואז מחזירה 500 ריק בדפדפן.

Web Forms. חשפו את המחרוזות זהות מה‑code‑behind וכתבו אותן עם <%= %>:

html
<head>
    <%= ViewerCss %>
</head>
<body>
    ...
    <%= ViewerScripts %>
</body>

IncludeViewerCss ו-IncludeViewerScripts הם הליבה המחויבת. כדי להוסיף את רצועות החיפוש וההערות, יש גם להגדיר את IncludeSearchCss, IncludeAnnotationCss, IncludeSearchScripts, IncludeSearchBar, IncludeAnnotationScripts ו-IncludeAnnotationBar. שתי השיטות משאירות קבצי רצועה כאשר הרישיון אינו מעניק את היכולת; הצופה עצמו עדיין מתחיל.

הוספת הצופה לדף

משטח הרינדור הוא שני div מקוננים:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

תנו ל-div החיצוני גובה אמיתי — הצופה ממלא את המכולה שלו ומודד אותה כאשר הוא מתחיל. הצופה אינו מצייר סרגל כלים משלו: GotoPage, Next, Zoom, FitType והיתר הם שיטות שהדף שלכם מחבר לכפתורים שלו, הממוקמים לצד הצופה:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <button type="button" onclick="objViewer.GotoPage(1)">First</button>
    <button type="button" onclick="objViewer.Next(false)">Previous</button>
    <button type="button" onclick="objViewer.Next(true)">Next</button>
    <button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
    <button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
    <button type="button" onclick="objViewer.FitType('width')">Fit width</button>
</nav>

אתחול הצופה והצגת המסמך

אחרי סקריפטי הצופה, צרו את הווידג'ט, ואז העבירו לו את הטוקן:

javascript
var objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // '/' משמעותו DocImage.axd בשורש האתר
    ResPath:    'doconut-res/images',  // אין '/' בתחילת
    onViewerReady: function () {
        // הדפים גלויים; הסתר אינדיקטור טעינה כאן
    },
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

fetch('/Document/Open', { method: 'POST' })
    .then(function (resp) { return resp.json(); })
    .then(function (data) { objViewer.View(data.token); });

ב‑Web Forms, כאשר הדף פותח את המסמך בעצמו, שלוש השורות האחרונות הופכות ל-objViewer.View('<%= Token %>');.

ארבעה פרטים כאן נכשלים ללא הודעת שגיאה:

  • BasePath: '/' מתייחס ל-DocImage.axd בשורש האתר. עבור יישום בתיקייה וירטואלית, השתמשו בשם שלו ללא קווים נטויים ('myapp' מבקש /myapp/DocImage.axd). קו נטוי מוביל ('/myapp') מייצר //myapp/DocImage.axd, שהדפדפן קורא זאת כבקשה למארח אחר.
  • ResPath: 'doconut-res/images' — האייקונים נמצאים בתיקייה אחת מתחת לשורש המשאבים. עם 'doconut-res', כל אייקון מחזיר 404: אין סמלי סרגל כלים ואין סיבוב טעינה, בעוד שהמסמך עצמו עדיין מוצג. קו נטוי מוביל שוב שובר את זה באותו אופן כמו BasePath.
  • Callbacks הן אפשרויות. onViewerReady, onError והיתר נכנסים לאובייקט המועבר ל-docViewer(...). פונקציה גלובלית בשם הצופה, כגון ctlDoc_ViewerReady, לעולם לא נקראת.
  • שמרו על הצופה, ואז קראו ל-View בנפרד. docViewer(...) מחזיר את האובייקט עם Zoom, Next ו-FitType; View(...) מחזיר משהו אחר. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) מציג את המסמך, ואז נכשל עם objViewer.Zoom is not a function בלחיצה הראשונה על סרגל הכלים.

שמות האפשרויות משולבות camelCase (showThumbs, autoLoad, pageZoom) ו‑PascalCase (FitType, BasePath, ResPath). אפשרות עם שגיאת כתיב מתעלמים ממנה, והווידג'ט משתמש בברירת המחדל שלו.

האלטרנטיבה בשורה אחת

לדף שצריך רק להציג מסמך, ללא סרגל כלים משלך, Viewer.RenderViewer כותב את כל סקריפט האתחול — docViewer(...) עם BasePath: '/' ו-ResPath: 'doconut-res/images', ואז .View(token). הוא קיים רק בחבילה זו:

csharp
// Default.aspx.cs
protected string ViewerInit;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    string token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
    ViewerInit = viewer.RenderViewer("div_ctlDoc", token);
}
html
<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>

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

סגור את המסמך

קרא ל-objViewer.Close(true) כאשר המשתמש עוזב את הצופה או פותח חלופה: הוא מנקה את הווידג'ט ושולח בקשת סגירה ל-DocImage.axd. objViewer.Close() ללא ארגומנט מנקה רק את הווידג'ט. בשרת, viewer.CloseDocument(token) מסיר את סשן המסמך מיידית, משחרר את משאבי הרינדור שלו, ומסיר את הגישה של הסשן לדפים שלו. תפוגה מתגלגלת עושה זאת בסופו של דבר, אך סגירת מסמכים גדולים במפורש משחררת זיכרון מהר יותר.

הפעל זאת

הציב קובץ PDF ב-~/files/Sample.pdf, הפעל את האתר ב‑IIS Express (F5 ב‑Visual Studio), ופתח את הדף שמארח את הווידג'ט. העמוד הראשון מוצג, עם תמונות ממוזערות בצד שמאל. אם זה לא קורה, ראה פתרון בעיות.

מה אתה מקבל ללא רישיון

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

האם דף זה היה מועיל?