התקנה

הוספת Doconut ליישום האינטרנט שלך ב-.NET Framework 4.7.2

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 אינו יכול לצרוך חבילה זו; יש לשנות את היעד תחילה.
  • האתר פועל ב‑צינור משולב (הברירת מחדל עבור מאגרי יישומי IIS ו‑IIS Express).
  • השרת פועל על Windows. החבילה זמינה רק ל‑Windows.

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

התקנת החבילה

מתקון מנהל החבילות (Package Manager Console):

powershell
Install-Package Doconut.NETFramework

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

bash
dotnet add package Doconut.NETFramework

הפקודות ללא גרסה מתקינות את הגרסה היציבה האחרונה. כדי לנעול את הגרסה המתוארת בתיעוד זה, העבירו את הגרסה:

powershell
Install-Package Doconut.NETFramework -Version 26.10.0
bash
dotnet add package Doconut.NETFramework --version 26.10.0

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

הגדרת Web.config

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

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

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

xml
<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 הוא ב KILOBYTES: 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 הוא ב BYTES: אותו 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" />. ראו סשנים ואבטחה.
  • הפניות קשירה. שמרו את הפניות הקשירה של <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:

csharp
// 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 — Quick Start מציג את ה‑Application_Start המלא.

כל האפשרויות

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

מאפייןברירת מחדלתיאור
UnsafeModefalseכאשר false, DocImage.axd מגישה דף רק למפגש ASP.NET שפתח את המסמך. כאשר true, כל בקשה שנושאת את הטוקן מוגשת. השאר אותו false.
ShowDoconutInfofalseכאשר true, בקשת DocImage.axd ללא token משיבה באנר גרסה במקום 404. שימושי כבדיקת עישון; השאר כבוי בייצור.
ResourcesPath"/doconut-res"היכן מודול המשאבים מגיש את הסקריפטים, הסגנונות והאייקונים המוטמעים. שנה זאת רק יחד עם ResPath של הצופה וכל IgnoreRoute של MVC.
LicensePath""נתיב מלא לקובץ הרישיון. ריק משמעותו לעבור למקור הבא, ואז לגילוי אוטומטי.
LicenseContent""תוכן רישיון גולמי — ממשתנה סביבתי, מחסן סודות, או מסד נתונים.
LicenseStreamnullרישיון כזרם, נקרא פעם אחת בהפעלה.
MiddlewarePath"/doconut"לא בשימוש בחבילה זו. נקודת הקצה של העמוד היא המטפל DocImage.axd המוצהר ב‑Web.config, לא משנה למה זה מוגדר. עדיין מתבצע אימות: הוא חייב להתחיל ב‑/ ולהיות שונה מ‑ResourcesPath.
ResetLicensefalseלא בשימוש בחבילה זו. הרישיון נקרא פעם אחת, ב‑DoconutHost.Initialize; יש למחזר את מאגר היישום לאחר החלפת קובץ רישיון.
MaxConcurrentEditorSessions200מספר מקסימלי של סשני עורך פעילים (מסמכים שנפתחים עם DocOptions.EditMode). מעל לכך, סשן העורך הלא פעיל שהשתמשו בו בפעם האחרונה נסגר. סשני צופה רגילים אינם נספרים. 0 או ערך שלילי משמעותו שאין הגבלה.
EditorSnapshotEveryOps50כאשר שמירת העורך מופעלת (AddDoconutEditorPersistence), מצולמים (snapshot) המסמך הפעיל כל N שינויים מוקלטים. 0 או ערך שלילי אף פעם לא מצולמים באמצע סשן. אין השפעה כאשר השמירה מושבתת.

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

csharp
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.

הצעדים הבאים

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

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