การติดตั้ง

เพิ่ม Doconut ไปยังแอปพลิเคชันเว็บ .NET Framework 4.7.2 ของคุณ

Doconut.NETFramework โฮสต์ Doconut viewer ในแอปพลิเคชัน 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 (ค่าเริ่มต้นสำหรับพูลแอปพลิเคชันของ 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 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 ก่อนที่ตัวจัดการจะทำงาน: เอกสารยังแสดง, แต่การตรวจจับแอนิเมชันจะไม่ทำงานและคอนโซลของเบราว์เซอร์จะเต็มไปด้วย 404.
  • 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" />. ดู เซสชันและความปลอดภัย.
  • การเปลี่ยนเส้นทางการผูก — รักษาการเปลี่ยนเส้นทาง binding <runtime> ที่ NuGet เขียนลงใน Web.config. ในโครงการแบบ SDK, คัดลอกจาก bin\<YourApp>.dll.config ที่สร้างขึ้น, เนื่องจาก ASP.NET แบบคลาสสิกอ่านการเปลี่ยนเส้นทางเฉพาะจาก Web.config. การเปลี่ยนเส้นทางที่ระบุเวอร์ชันที่ไม่มีใน bin\ จะทำให้แอปพลิเคชันทั้งหมดหยุดทำงานด้วย 500 ว่างที่การเริ่มต้น.

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

ไม่มีตัวสร้างและไม่มี pipeline ของ middleware ใน System.Web. Doconut ถูกสร้างขึ้นหนึ่งครั้งต่อกระบวนการ worker โดย 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 — เริ่มต้นอย่างรวดเร็ว แสดง Application_Start ที่สมบูรณ์.

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

DoconutOptions ยอมรับคุณสมบัติตั้งค่าต่อไปนี้. ทุกข้อเป็นทางเลือก.

คุณสมบัติค่าเริ่มต้นคำอธิบาย
UnsafeModefalseเมื่อ false, DocImage.axd ให้บริการหน้าเพจเฉพาะกับเซสชัน ASP.NET ที่เปิดเอกสารนั้น. เมื่อ true, คำขอใดๆ ที่มีโทเคนจะได้รับการให้บริการ. ปล่อยไว้เป็น false.
ShowDoconutInfofalseเมื่อ true, คำขอ DocImage.axd ที่ไม่มี token จะตอบด้วยแบนเนอร์เวอร์ชันแทน 404. มีประโยชน์เป็นการตรวจสอบเบื้องต้น; ปิดไว้ในการผลิต.
ResourcesPath"/doconut-res"ตำแหน่งที่โมดูลทรัพยากรให้บริการสคริปต์, สไตล์, และไอคอนที่ฝังอยู่. เปลี่ยนเฉพาะเมื่อเปลี่ยน ResPath ของ viewer และ MVC IgnoreRoute ใดๆ.
LicensePath""เส้นทางเต็มไปยังไฟล์ใบอนุญาต. ค่าว่างหมายถึงให้ผ่านไปยังแหล่งต่อไป, แล้วต่อไปยังการค้นหาอัตโนมัติ.
LicenseContent""เนื้อหาใบอนุญาตดิบ — มาจากตัวแปรสภาพแวดล้อม, ที่เก็บความลับ, หรือฐานข้อมูล.
LicenseStreamnullใบอนุญาตเป็นสตรีม, อ่านครั้งเดียวเมื่อเริ่มต้น.
MiddlewarePath"/doconut"ไม่ใช้ในแพคเกจนี้. จุดสิ้นสุดของหน้าเป็นตัวจัดการ DocImage.axd ที่ประกาศใน Web.config, ไม่ว่าค่าจะเป็นอะไร. ยังต้องตรวจสอบ: ต้องเริ่มด้วย / และต้องแตกต่างจาก ResourcesPath.
ResetLicensefalseไม่ใช้ในแพคเกจนี้. ใบอนุญาตอ่านครั้งเดียว, ใน DoconutHost.Initialize; รีไซเคิล application pool หลังจากเปลี่ยนไฟล์ใบอนุญาต.
MaxConcurrentEditorSessions200จำนวนสูงสุดของเซสชัน editor ที่เปิดอยู่ (เอกสารที่เปิดด้วย DocOptions.EditMode). หากเกิน, เซสชัน editor ที่ไม่ได้ใช้นานที่สุดจะถูกปิด. เซสชัน viewer ปกติจะไม่ถูกนับ. 0 หรือค่าติดลบหมายถึงไม่มีขีดจำกัด.
EditorSnapshotEveryOps50เมื่อเปิดการคงสภาพ editor (AddDoconutEditorPersistence), ทำ snapshot เอกสารที่เปิดอยู่ทุก N การเปลี่ยนแปลงที่บันทึก. 0 หรือค่าติดลบจะไม่ทำ snapshot ระหว่างเซสชัน. ไม่มีผลเมื่อการคงสภาพถูกปิด.

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

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

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

หน้านี้เป็นประโยชน์หรือไม่?