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ữ trình xem Doconut 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 phủ cả ba phần; Bắt đầu nhanh sau đó đặt một tài liệu lên một 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).
- Máy chủ chạy trên Windows. Gói này chỉ hỗ trợ Windows.
Trang này bao phủ Doconut.NETFramework 26.9.0 trở lên. Các phiên bản 26.8.0 và trước đó nhắm mục tiêu .NET Framework 4.7 với một 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 đó được mô tả trong Di chuyển.
Cài đặt gói
Từ Package Manager Console:
Install-Package Doconut.NETFrameworkHoặc, trong một dự án kiểu SDK:
dotnet add package Doconut.NETFrameworkCác lệnh không chỉ định phiên bản sẽ cài đặt bản phát hành ổn định mới nhất. Để cố định bản phát hành mà tài liệu này mô tả, truyền phiên bản:
Install-Package Doconut.NETFramework -Version 26.10.0dotnet add package Doconut.NETFramework --version 26.10.0Engine 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 đều 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 trình xem, ảnh thu nhỏ, tìm kiếm và điểm cuối chú thích, được phục vụ bởiDoconut.DocImageHandler./doconut-res/*— các script, stylesheet và biểu tượng riêng của trình xem, được nhúng trong assembly và phục vụ bởiDoconut.DoconutResourceModule.
Thêm cả hai, cùng với các cài đặt mà chúng phụ thuộc:
<configuration>
<system.web>
<!-- Chỉ dành cho 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 gây ra ngoại lệ:
verb="GET,HEAD,POST"— giữHEAD. Trình xem gửi một yêu cầuHEADcho trang 1 để phát hiện hình ảnh động. Nếu không có động từ này, IIS trả lời404trướ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 hình không bao giờ hoạt động và console trình duyệt đầy các lỗi 404.runAllManagedModulesForAllRequests="true"—/doconut-res/*.js,.cssvà.pngtrô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 trình xem 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ó dấu byte-order 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 đến trình duyệt được mã hoá đôi (một 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 facade 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ớiCS0012và trả về một500rỗng, và chỉ những trang gây ra lỗi 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(kilobytes) vàmaxAllowedContentLength(bytes) đồng bộ, và trên mức 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:
- Trạng thái phiên 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. Giữ các chuyển hướng ràng buộc
<runtime>mà NuGet ghi vàoWeb.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 một phiên bản không có trongbin\sẽ dừng toàn bộ ứng dụng với một500rỗ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ởi DoconutHost.Initialize trong Application_Start, và được giải phóng bởi DoconutHost.Shutdown trong 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 xây dựng các dịch vụ, trình xử lý, 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). Only the first call configures anything; a second call is ignored. In an MVC application, also keep the two Doconut paths out of routing — Bắt đầu nhanh shows the complete Application_Start.
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ính | Mặc định | Mô tả |
|---|---|---|
UnsafeMode | false | Khi 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ó false. |
ShowDoconutInfo | false | Khi true, một yêu cầu DocImage.axd không có token sẽ trả lời 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 MVC nào. |
LicensePath | "" | Đường dẫn đầy đủ tới tệp giấy phép. Trống có nghĩa là chuyển sang nguồn tiếp theo, sau đó là phát hiện tự động. |
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. |
LicenseStream | null | Giấ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à trình xử lý DocImage.axd được khai báo trong Web.config, bất kể giá trị được đặt. Nó vẫn được xác thực: phải bắt đầu bằng / và khác với ResourcesPath. |
ResetLicense | false | Khô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. |
MaxConcurrentEditorSessions | 200 | Số tối đa các phiên editor đang hoạt động (tài liệu mở bằng DocOptions.EditMode). Khi vượt quá, phiên editor không hoạt động lâu nhất sẽ bị đóng. Các phiên viewer bình thường không bao giờ được tính. 0 hoặc giá trị âm có nghĩa là không giới hạn. |
EditorSnapshotEveryOps | 50 | Khi bật tính năng lưu trữ editor (AddDoconutEditorPersistence), chụp nhanh tài liệu đang hoạt động mỗi N thay đổi đã ghi lại. 0 hoặc giá trị âm sẽ không bao giờ chụp nhanh trong phiên. Không có hiệu lực khi tính năng lưu trữ bị tắt. |
Khi có hơn một nguồn giấy phép được thiết lập, LicenseStream ưu tiên hơn LicenseContent, rồi LicensePath, và cuối cùng là phát hiện tự động — xem Cài đặt giấy phép.
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.ResourcesPath = "/doconut-res"; // nơi mà JS/CSS/hình ảnh của viewer được phục vụ từ
options.UnsafeMode = false; // giữ bảo mật session
options.ShowDoconutInfo = false;
});
// Điểm cuối trang không phải là một tùy 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
- Bắt đầu nhanh — mở một tài liệu và hiển thị nó trong trình duyệt, trong MVC 5 hoặc Web Forms.
- Cài đặt giấy phép — nơi Doconut tìm kiếm tệp giấy phép của bạn.
Trang này có hữu ích không?