การติดตั้ง

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 ไม่สามารถใช้แพคเกจนี้ได้; ต้องเปลี่ยนเป้าหมายก่อน.
• เว็บไซต์ต้องทำงานใน integrated pipeline (ค่าเริ่มต้นสำหรับ application pool ของ IIS และ IIS Express).

หน้านี้ครอบคลุม Doconut.NETFramework เวอร์ชัน 26.9.0 ขึ้นไป. เวอร์ชัน 26.8.0 และก่อนหน้านั้นมุ่งเป้าไปที่ .NET Framework 4.7 ด้วย API ที่แตกต่าง; สายการนั้นได้ยกเลิกแล้ว. การอัปเดตแอปพลิเคชันที่มีอยู่ข้ามขอบเขตนั้นอธิบายใน การย้าย.

ติดตั้งแพคเกจ

จาก Package Manager Console:

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/* — สคริปต์, สไตล์ชีต, และไอคอนของตัวดูเอง, ฝังอยู่ในแอสเซมบลีและให้บริการโดย Doconut.DoconutResourceModule.

เพิ่มทั้งสองพร้อมการตั้งค่าที่พึ่งพา:

<configuration>
  <system.web>
    <!-- เฉพาะ MVC 5: Razor คอมไพล์วิวในเวลารันและต้องการ netstandard facade. -->
    <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 เพื่อตรวจจับภาพเคลื่อนไหว. หากไม่มี verb นี้ IIS จะตอบ 404 ก่อนตัวจัดการทำงาน: เอกสารยังแสดง, แต่การตรวจจับการเคลื่อนไหวจะไม่ทำงานและคอนโซลของเบราว์เซอร์จะเต็มด้วย 404s.
• runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css, และ .png ดูเหมือนไฟล์สถิต, และ IIS จะส่งให้ตัวจัดการไฟล์สถิตก่อนที่โมดูลทรัพยากรจะเห็น. ผลลัพธ์คือตัวดูที่ไม่มีสคริปต์หรือไอคอน.
• <globalization fileEncoding="utf-8"> — ไฟล์หน้าเว็บที่บันทึกเป็น UTF-8 โดยไม่มี byte-order mark จะถูกอ่านด้วยหน้าโค้ด ANSI ของเซิร์ฟเวอร์, ทำให้ตัวอักษรที่ไม่ใช่ ASCII ถูกเข้ารหัสซ้ำเมื่อถึงเบราว์เซอร์ (เช่น em dash แสดงเป็น —). ไฟล์บนดิสก์ถูกต้อง, และหน้ายังคงประกาศ <meta charset="utf-8">.
• แอสเซมบลี netstandard (MVC 5) — Razor คอมไพล์วิวเมื่อมีการร้องขอครั้งแรก, ด้วยรายการอ้างอิงของมันที่ไม่ได้รวม facade นี้. วิวที่ทำอะไรแบบไดนามิกเกินการเข้าถึงสมาชิกธรรมดาจะล้มเหลวด้วย CS0012 และตอบเป็น 500 ว่างเปล่า, และเฉพาะหน้าที่ทำให้เกิดข้อผิดพลาดจึงล้มเหลว. ข้อผิดพลาดของคอมไพเลอร์ปรากฏเฉพาะใน Windows event log (source ASP.NET). แอปพลิเคชัน Web Forms ไม่จำเป็นต้องมีบรรทัดนี้.
• ขีดจำกัดการอัปโหลด — ASP.NET อ่านเนื้อหาคำขอทั้งหมดก่อนที่ตัวจัดการใดทำงาน, ดังนั้นการอัปโหลดที่เกินขีดจำกัดนี้จะถูก IIS ปฏิเสธด้วยหน้าแสดงข้อผิดพลาดของมันเอง. ควรรักษา maxRequestLength (kilobytes) และ maxAllowedContentLength (bytes) ให้สอดคล้องกัน, และต้องมากกว่าขนาดไฟล์ที่ใหญ่ที่สุดที่ผู้ใช้ของคุณเปิดหรืออัปโหลด.

มีการตั้งค่าเพิ่มเติมอีกสองอย่างที่สำคัญ, และโดยปกติแล้วทั้งสองถูกตั้งค่าอย่างถูกต้องแล้ว:

• สถานะเซสชันยังเปิดอยู่. โดยค่าเริ่มต้นหน้าจะให้บริการเฉพาะกับเซสชัน ASP.NET ที่เปิดเอกสาร, ดังนั้นไซต์ต้องไม่ตั้งค่า <sessionState mode="Off" />. ดู เซสชันและความปลอดภัย.
• การเปลี่ยนเส้นทางการผูก. คงการเปลี่ยนเส้นทาง <runtime> ที่ NuGet เขียนลงใน Web.config. ในโครงการแบบ SDK, คัดลอกจาก bin\<YourApp>.dll.config ที่สร้างขึ้น, เนื่องจาก ASP.NET แบบคลาสสิกอ่านการเปลี่ยนเส้นทางเฉพาะจาก Web.config. การเปลี่ยนเส้นทางที่ระบุเวอร์ชันที่ไม่มีใน bin\ จะทำให้แอปพลิเคชันทั้งหมดหยุดทำงานด้วย 500 ว่างเปล่าเมื่อเริ่มต้น.

ลงทะเบียน Doconut ใน Global.asax

ไม่มีตัวสร้าง (builder) และไม่มี pipeline ของ middleware ใน System.Web. Doconut จะถูกประกอบขึ้นหนึ่งครั้งต่อกระบวนการ worker โดย 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 จะสร้างบริการให้กับ handler, โมดูลทรัพยากร, และโค้ดของคุณเอง โค้ดของคุณสามารถเข้าถึงบริการเหล่านั้นได้ผ่าน DoconutHost.Services (ดูที่ DoconutHost). การเรียกครั้งแรกเท่านั้นที่ทำการกำหนดค่า; การเรียกครั้งที่สองจะถูกละเลย ในแอปพลิเคชัน MVC ควรทำให้เส้นทาง Doconut ทั้งสองอยู่นอกการ routing — ดูที่ Quick Start เพื่อดู Application_Start อย่างสมบูรณ์

ตัวเลือกทั้งหมด

DoconutOptions รองรับคุณสมบัติเบื้องต้นต่อไปนี้ ทุกคุณสมบัติต่างเป็นตัวเลือก (optional)

เมื่อกำหนดแหล่งใบอนุญาตมากกว่าหนึ่งแหล่ง, LicenseStream จะมีลำดับความสำคัญสูงสุด, ตามด้วย LicenseContent, ตามด้วย LicensePath, แล้วจึงเป็นการค้นหาอัตโนมัติ — ดูที่ License Setup.

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // ที่ viewer ให้บริการไฟล์ JS/CSS/รูปภาพ
    options.UnsafeMode      = false;          // รักษาความปลอดภัยของเซสชันไว้
    options.ShowDoconutInfo = false;
});
// จุดสิ้นสุดของหน้าไม่ได้เป็นตัวเลือกที่นี่: มันคือ handler `DocImage.axd` ที่ประกาศใน Web.config.

ขั้นตอนต่อไป

• เริ่มต้นอย่างเร็ว — เปิดเอกสารและแสดงผลในเบราว์เซอร์, ใน MVC 5 หรือ Web Forms.
• การตั้งค่าใบอนุญาต — ที่ Doconut ค้นหาไฟล์ใบอนุญาตของคุณ.