Cài đặt

Thêm Doconut vào ứng dụng web .NET Framework 4.7.2 của bạn

Doconut.NETFramework lưu trữ Doconut viewer trong một ứng dụng ASP.NET cổ điển trên .NET Framework 4.7.2 — IIS hoặc IIS Express, MVC 5 hoặc Web Forms. Cài đặt gồm ba phần: gói NuGet, hai đăng ký trong Web.config, và một lời gọi trong Global.asax. Trang này bao gồm cả ba phần; Bắt đầu nhanh sau đó đặt một tài liệu lên trang.

Yêu cầu

  • Dự án web nhắm mục tiêu .NET Framework 4.7.2 hoặc mới hơn. Dự án 4.7 không thể sử dụng gói này; hãy chuyển mục tiêu lại trước.
  • Trang web chạy trong integrated pipeline (mặc định cho các pool ứng dụng IIS và IIS Express).

Trang này bao gồm Doconut.NETFramework 26.9.0 và các phiên bản sau. Các phiên bản 26.8.0 và trước đó nhắm mục tiêu .NET Framework 4.7 với API khác; dòng đó đã ngừng hỗ trợ. Việc cập nhật một ứng dụng hiện có qua ranh giới này được mô tả trong Di chuyển.

Cài đặt gói

Từ Package Manager Console:

powershell
Install-Package Doconut.NETFramework

Hoặc, trong một dự án kiểu SDK:

bash
dotnet add package Doconut.NETFramework

Engine render được nhúng trong gói: không có assembly engine riêng để tham chiếu, sao chép hoặc triển khai. Các khả năng tùy chọn được cung cấp dưới dạng các gói riêng — ví dụ Doconut.NETFramework.Converter và Doconut.NETFramework.Dicom — và mỗi gói cần một giấy phép cho phép (xem Hệ thống Plugin).

Cấu hình Web.config

Doconut phục vụ hai loại yêu cầu, và IIS định tuyến cả hai qua Web.config:

  • DocImage.axd — trang của viewer, hình thu nhỏ, tìm kiếm và điểm cuối chú thích, được phục vụ bởi Doconut.DocImageHandler.
  • /doconut-res/* — các script, stylesheet và biểu tượng của viewer, được nhúng trong assembly và phục vụ bởi Doconut.DoconutResourceModule.

Thêm cả hai, cùng với các cài đặt mà chúng phụ thuộc vào:

xml
<configuration>
  <system.web>
    <!-- Chỉ MVC 5: Razor biên dịch các view tại thời gian chạy và cần facade netstandard. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength tính bằng KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Đọc các tệp .cshtml và .aspx dưới dạng UTF-8, không phải dưới dạng trang mã ANSI của máy chủ. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength tính bằng BYTES: cùng 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>

Mỗi dòng ngăn ngừa một lỗi không ném ra ngoại lệ:

  • verb="GET,HEAD,POST" — giữ HEAD. Viewer gửi yêu cầu HEAD cho trang 1 để phát hiện hình ảnh động. Nếu không có verb này, IIS trả về 404 trước khi trình xử lý chạy: tài liệu vẫn hiển thị, nhưng việc phát hiện hoạt ảnh không bao giờ hoạt động và console trình duyệt đầy 404.
  • runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css, và .png trông giống như các tệp tĩnh, và IIS sẽ chuyển chúng cho trình xử lý tệp tĩnh trước khi mô-đun tài nguyên nhìn thấy chúng. Kết quả là một viewer không có script hoặc biểu tượng.
  • <globalization fileEncoding="utf-8"> — các tệp trang được lưu dưới dạng UTF-8 mà không có byte-order mark sẽ bị đọc bằng trang mã ANSI của máy chủ, vì vậy mọi ký tự không phải ASCII tới trình duyệt sẽ bị mã hoá đôi (dấu gạch ngang dài hiển thị là —). Tệp trên đĩa là đúng, và trang vẫn khai báo <meta charset="utf-8">.
  • Assembly netstandard (MVC 5) — Razor biên dịch các view khi chúng được yêu cầu lần đầu, với danh sách tham chiếu riêng không bao gồm façade này. Một view thực hiện bất kỳ thao tác động nào ngoài truy cập thành viên đơn giản sẽ thất bại với CS0012 và trả về lỗi 500 rỗng, và chỉ các trang gây ra lỗi này mới thất bại. Lỗi biên dịch chỉ xuất hiện trong nhật ký sự kiện Windows (nguồn ASP.NET). Các ứng dụng Web Forms không cần dòng này.
  • Giới hạn tải lên — ASP.NET đọc toàn bộ thân yêu cầu trước khi bất kỳ trình xử lý nào chạy, vì vậy một tải lên vượt quá các giới hạn này sẽ bị IIS từ chối với trang lỗi riêng. Giữ maxRequestLength (kilobyte) và maxAllowedContentLength (byte) đồng bộ, và lớn hơn tệp lớn nhất người dùng của bạn mở hoặc tải lên.

Hai cài đặt nữa cũng quan trọng, và thường đã đúng sẵn:

  • Trạng thái phiên (Session) vẫn bật. Mặc định một trang chỉ được phục vụ cho phiên ASP.NET đã mở tài liệu, vì vậy trang web không được đặt <sessionState mode="Off" />. Xem Phiên & Bảo mật.
  • Chuyển hướng ràng buộc (Binding redirects). Giữ các chuyển hướng ràng buộc <runtime> mà NuGet ghi vào Web.config. Trong một dự án kiểu SDK, sao chép chúng từ bin\<YourApp>.dll.config được tạo, vì ASP.NET cổ điển chỉ đọc chuyển hướng từ Web.config. Một chuyển hướng chỉ định phiên bản không tồn tại trong bin\ sẽ dừng toàn bộ ứng dụng với lỗi 500 rỗng khi khởi động.

Đăng ký Doconut trong Global.asax

Không có builder và không có pipeline middleware trong System.Web. Doconut được tạo một lần cho mỗi tiến trình worker bằng DoconutHost.Initialize trong Application_Start, và được giải phóng bởi DoconutHost.Shutdown trong 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 xây dựng các dịch vụ cho handler, mô-đun tài nguyên và mã của bạn sử dụng. Mã của bạn truy cập chúng qua DoconutHost.Services (xem DoconutHost). Chỉ lần gọi đầu tiên mới cấu hình; lần gọi thứ hai sẽ bị bỏ qua. Trong một ứng dụng MVC, cũng hãy giữ hai đường dẫn Doconut ra khỏi routing — Bắt đầu nhanh hiển thị Application_Start đầy đủ.

Tất cả các tùy chọn

DoconutOptions chấp nhận các thuộc tính có thể thiết lập sau. Mỗi thuộc tính đều là tùy chọn.

Thuộc tínhMặc địnhMô tả
UnsafeModefalseKhi false, DocImage.axd chỉ phục vụ một trang cho phiên ASP.NET đã mở tài liệu. Khi true, bất kỳ yêu cầu nào mang token đều được phục vụ. Để nó là false.
ShowDoconutInfofalseKhi true, một yêu cầu DocImage.axd không có token sẽ trả về một biểu ngữ phiên bản thay vì 404. Hữu ích như một kiểm tra nhanh; để tắt trong môi trường sản xuất.
ResourcesPath"/doconut-res"Nơi mô-đun tài nguyên phục vụ các script, style và biểu tượng được nhúng. Chỉ thay đổi nó cùng với ResPath của viewer và bất kỳ IgnoreRoute nào trong MVC.
LicensePath""Đường dẫn đầy đủ tới tệp giấy phép. Trống có nghĩa là sẽ chuyển sang nguồn tiếp theo, sau đó đến việc tự động phát hiện.
LicenseContent""Nội dung giấy phép thô — từ biến môi trường, kho bí mật, hoặc cơ sở dữ liệu.
LicenseStreamnullGiấy phép dưới dạng stream, đọc một lần khi khởi động.
MiddlewarePath"/doconut"Không được sử dụng trong gói này. Điểm cuối trang là handler DocImage.axd được khai báo trong Web.config, bất kể giá trị này được đặt là gì. Nó vẫn được xác thực: phải bắt đầu bằng / và khác với ResourcesPath.
ResetLicensefalseKhông được sử dụng trong gói này. Giấy phép được đọc một lần, trong DoconutHost.Initialize; hãy tái khởi động pool ứng dụng sau khi thay thế tệp giấy phép.

Khi có hơn một nguồn giấy phép được thiết lập, LicenseStream sẽ ưu tiên hơn LicenseContent, LicenseContent ưu tiên hơn LicensePath, và LicensePath ưu tiên hơn việc tự động phát hiện — xem Cài đặt Giấy phép.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // nơi các JS/CSS/hình ảnh của viewer được cung cấp
    options.UnsafeMode      = false;          // giữ bảo mật phiên hoạt động
    options.ShowDoconutInfo = false;
});
// Điểm cuối trang không phải là một lựa chọn ở đây: nó là trình xử lý DocImage.axd được khai báo trong Web.config.

Các bước tiếp theo

Trang này có hữu ích không?