התקנה

Doconut.NETFramework מארח את מציג Doconut ביישום ASP.NET קלאסי על .NET Framework 4.7.2 — IIS או IIS Express, MVC 5 או Web Forms. ההגדרה מורכבת משלושה חלקים: חבילת ה‑NuGet, שני רישומים ב‑Web.config, וקורא אחד ב‑Global.asax. דף זה מכסה את שלושת החלקים; התחלה מהירה לאחר מכן מציב מסמך בעמוד.

דרישות

• הפרויקט ממקד ב‑.NET Framework 4.7.2 או גרסה מאוחרת יותר. פרויקט 4.7 אינו יכול לצרוך חבילה זו; יש לשנות את המטרה תחילה.
• האתר פועל ב‑pipeline משולב (ברירת המחדל עבור מאגרי יישומים של IIS ו‑IIS Express).

דף זה מכסה את Doconut.NETFramework 26.9.0 ומעלה. גרסאות 26.8.0 וקודמות ממקדות .NET Framework 4.7 עם API שונה; קו זה הופסק. עדכון יישום קיים מעבר לגבול זה מכוסה ב‑הגירה.

התקנת החבילה

מהקונסול של מנהל החבילות:

Install-Package Doconut.NETFramework

או, בפרויקט בסגנון SDK:

dotnet add package Doconut.NETFramework

מנוע הרינדור משובץ בחבילה: אין אסמבליית מנוע נפרדת להפניה, העתקה או פריסה. יכולות אופציונליות נשלחות כחבילות נפרדות — לדוגמה Doconut.NETFramework.Converter ו‑Doconut.NETFramework.Dicom — ולכל אחת נדרש רישיון שמאפשר זאת (ראו מערכת תוספים).

הגדרת Web.config

Doconut משרת שני סוגי בקשות, ו‑IIS מעביר את שניהם דרך Web.config:

• DocImage.axd — דף המציג, תמונה ממוזערת, חיפוש ונקודת קצה של הערות, משרת על‑ידי Doconut.DocImageHandler.
• /doconut-res/* — הסקריפטים, קבצי ה‑CSS והאיקונים של המציג, משובצים באסמבליה ומשרתים על‑ידי Doconut.DoconutResourceModule.

הוסיפו את שניהם, יחד עם ההגדרות שעליהם הם תלויים:

<configuration>
  <system.web>
    <!-- רק MVC 5: Razor מקמפל תצוגות בזמן ריצה וצריך את המעטפת netstandard. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength נמדד בקילובייטים: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- קרא קבצי .cshtml ו‑.aspx כ‑UTF‑8, ולא כקוד העמודה ANSI של השרת. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength נמדד בבייטים: אותו 200 MB. -->
        <requestLimits maxAllowedContentLength="209715200" />
      </requestFiltering>
    </security>
    <modules runAllManagedModulesForAllRequests="true">
      <add name="DoconutResourceModule" type="Doconut.DoconutResourceModule, Doconut" />
    </modules>
    <handlers>
      <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd"
           type="Doconut.DocImageHandler, Doconut" />
    </handlers>
  </system.webServer>
</configuration>

כל שורה מונעת כשל שלא זורק חריגה:

• verb="GET,HEAD,POST" — שמרו על HEAD. המציג שולח בקשת HEAD לדף 1 כדי לזהות תמונות מונפשות. ללא הפועל, IIS מחזיר 404 לפני שהמטפל פועל: המסמכים עדיין מוצגים, אך זיהוי האנימציה לעולם לא פועל וקונסול הדפדפן מתמלא ב‑404.
• runAllManagedModulesForAllRequests="true" — קבצים כמו /doconut-res/*.js, .css ו‑.png נראים כקבצים סטטיים, ו‑IIS היה מעביר אותם למטפל הקבצים הסטטי לפני שמודול המשאבים רואה אותם. התוצאה היא מציג ללא סקריפטים או איקונים.
• <globalization fileEncoding="utf-8"> — קבצי דף שנשמרים כ‑UTF‑8 ללא סימן סדרת בתים נקראים אחרת עם קוד העמודה ANSI של השרת, ולכן כל תו שאינו ASCII מגיע לדפדפן מקודד פעמיים (מקף ארוך מופיע כ‑—). הקובץ נכון על הדיסק, והדף עדיין מצהיר <meta charset="utf-8">.
• האסמבליה netstandard (MVC 5) — Razor מקמפל תצוגות בפעם הראשונה שהן נדרשות, עם רשימת רפרנסים משלו שאינה כוללת את המעטפת הזו. תצוגה שמבצעת כל פעולה דינמית מעבר לגישה לחבר רגיל תיכשל עם CS0012 ותשיב 500 ריק, ורק הדפים שמפעילים אותה יכשלו. שגיאת המהדר מופיעה רק ביומן אירועי Windows (מקור ASP.NET). יישומי Web Forms אינם זקוקים לשורה זו.
• מגבלות העלאה — ASP.NET קורא את כל גוף הבקשה לפני שמטפל כלשהו פועל, ולכן העלאה שמעבר למגבלות אלו נדחית על‑ידי IIS עם דף שגיאה משלו. שמרו על maxRequestLength (קילובייט) ו‑maxAllowedContentLength (בייט) בתיאום, וגבוהות מהקובץ הגדול ביותר שהמשתמשים שלכם פותחים או מעלים.

שתי הגדרות נוספות חשובות, ובדרך כלל כבר נכונות:

• מצב סשן נשאר פעיל. כברירת מחדל דף משרת רק לסשן ASP.NET שפתח את המסמך, ולכן האתר לא צריך להגדיר <sessionState mode="Off" />. ראו הפעלות ואבטחה.
• הפניות מחדש (Binding redirects). שמרו על הפניות <runtime> שה‑NuGet כותב ל‑Web.config. בפרויקט בסגנון SDK, העתיקו אותן מה‑bin\<YourApp>.dll.config שנוצר, מכיוון ש‑ASP.NET קלאסי קורא הפניות רק מ‑Web.config. הפנייה שמציינת גרסה חסרה בתיקיית bin\ תעצור את כל היישום עם 500 ריק בזמן ההפעלה.

רישום Doconut ב‑Global.asax

אין בונה ואין צינור Middleware ב‑System.Web. Doconut מורכב פעם אחת לכל תהליך עובד על‑ידי DoconutHost.Initialize ב‑Application_Start, ומשוחרר על‑ידי DoconutHost.Shutdown ב‑Application_End:

// Global.asax.cs
protected void Application_Start()
{
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    });
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}

DoconutHost.Initialize בונה את השירותים שהמתאם, מודול המשאבים והקוד שלך משתמשים בו. הקוד שלך מגיע אליהם דרך DoconutHost.Services (ראו DoconutHost). רק הקריאה הראשונה מגדירה משהו; קריאה שנייה מתעלמת. ביישום MVC, יש גם לשמור את שני הנתיבים של Doconut מחוץ ל‑routing — התחלה מהירה מציגה את Application_Start המלא.

כל האפשרויות

DoconutOptions מקבלת את המאפיינים הניתנים להגדרה הבאים. כל אחד הוא אופציונלי.

כאשר מוגדר יותר ממקור רישיון אחד, LicenseStream גובר על LicenseContent, שמגבר על LicensePath, שמגבר על גילוי אוטומטי — ראו הגדרת רישיון.

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // היכן שהצופה מגיש את קבצי ה‑JS/CSS/תמונות
    options.UnsafeMode      = false;          // שמור על אבטחת המפגש
    options.ShowDoconutInfo = false;
});
// נקודת הקצה של העמוד איננה אפשרות כאן: היא המתאם DocImage.axd המוצהר ב‑Web.config.

הצעדים הבאים

• התחלה מהירה — פתח מסמך והצג אותו בדפדפן, ב‑MVC 5 או Web Forms.
• הגדרת רישיון — המקום שבו Doconut מחפש את קובץ הרישיון שלך.