Cài đặt

Thêm Doconut vào dự án .NET Standard 2.1 của bạn

Bộ trình xem Doconut cơ bản cho .NET Standard được cung cấp dưới dạng một gói NuGet duy nhất có thể tích hợp vào bất kỳ ứng dụng ASP.NET Core nào. Các plugin tùy chọn sử dụng các gói riêng biệt. Trang này cài đặt gói cơ bản, xác nhận máy chủ của bạn có thể sử dụng nó, và đăng ký middleware — mức tối thiểu cần thiết trước khi bạn thực hiện lần render đầu tiên.

Kiểm tra khung nền máy chủ trước tiên

Thư viện nhắm mục tiêu netstandard2.1. Đây là một hợp đồng hẹp hơn so với bản dựng netstandard2.0 trước đó, và đây là điều đầu tiên cần xác minh:

Máy chủĐược hỗ trợ
.NET Core 3.0 hoặc sau, bao gồm .NET 5/6/7/8Có
.NET Framework (bất kỳ phiên bản nào)Không — netstandard2.1 không thể được sử dụng bởi .NET Framework

Gói này chỉ chạy trên chỉ Windows. Đối với máy chủ Linux, sử dụng Doconut.NET8 hoặc Doconut.NET6.

Nếu ứng dụng chạy trên .NET Framework, đây không phải là gói phù hợp. Sử dụng Doconut.NETFramework thay thế; kể từ phiên bản 26.9.0 nó yêu cầu .NET Framework 4.7.2.

Cài đặt gói

bash
dotnet add package Doconut.NETStandard

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 như một tùy chọn riêng:

bash
dotnet add package Doconut.NETStandard --version 26.10.0

Doconut.NETStandard là ID của gói. Hậu tố phiên bản thuộc về tên tệp Doconut.NETStandard.<version>.nupkg đã tải xuống và không phải là một phần của ID.

Số phiên bản là thế hệ

Điều này quan trọng hơn ở đây so với tên gói. Cả hai thế hệ của thư viện .NET Standard đều được phát hành dưới cùng một ID gói, và chỉ phiên bản mới phân biệt chúng:

Phiên bảnMục tiêuAPI
26.7.0 và dướinetstandard2.0tích hợp trước đó
26.8.0 và trênnetstandard2.1tích hợp được mô tả ở đây

Không có shim tương thích và không có gói song song. Nâng cấp phiên bản là việc nâng cấp, và trình biên dịch sẽ báo cáo ngay lập tức các khác biệt API.

Đừng chọn tài liệu chỉ dựa trên tên gói:

  • new Viewer(_cache, _accessor, …), UnSafeMode, đồng bộ OpenDocument(...), viewer.InitCache(), UseDoconutWebFarm, và các script trình xem được sao chép thủ công xác định tích hợp trước đó;
  • AddDoconut(), UseDoconutResources(), một Viewer được tiêm vào, và OpenDocumentAsync(...) xác định tích hợp hiện tại được mô tả ở đây.

Tài liệu hướng dẫn cài đặt trước vẫn còn sẵn sàng. Sử dụng hướng dẫn di chuyển để thay đổi thế hệ; việc cập nhật gói không tự động chuyển đổi khởi động, thời gian sống của trình xem, hoặc tài nguyên trình duyệt.

Đăng ký Doconut

AddDoconut() là điểm vào duy nhất để đăng ký — có một overload duy nhất, và nó kết nối dịch vụ Viewer, dịch vụ giấy phép, và cơ sở hạ tầng render vào container DI.

Hai lời gọi middleware hoàn thiện việc thiết lập, và thứ tự của chúng quan trọng: UseDoconutResources() phải chạy trước UseDoconut(). UseDoconut() là middleware cuối cùng, vì vậy gọi nó trước sẽ khiến mọi yêu cầu tới tài nguyên /doconut-res không bao giờ tới trình xử lý tài nguyên và trả về 404. UseDoconut() trả lời mọi yêu cầu đến nó, vì vậy hãy gắn nó vào một nhánh riêng với app.Map. Việc kết nối session cũng cần thiết — bảo mật tài liệu mặc định của Doconut xác thực mọi yêu cầu trang dựa trên trạng thái session của ASP.NET.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state cần một bộ nhớ đệm (MVC/Razor Pages đã thêm sẵn một)
builder.Services.AddSession(); // Bảo mật tài liệu Doconut dựa trên session state của ASP.NET

app.UseSession();          // gọi UseSession() trước UseDoconut()
app.UseDoconutResources(); // phải được đăng ký trước UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

Không gian tên

Các kiểu cấu hình không còn được phân tán qua bốn không gian tên nữa. Trong bản phát hành này, hầu hết mọi thứ đều nằm trong không gian tên gốc Doconut:

csharp
using Doconut;                       // Viewer, DoconutOptions, DocOptions, tất cả các cấu hình định dạng
using Doconut.Middleware;            // AddDoconut, UseDoconut, UseDoconutResources
using Doconut.Clouds;                // cấu hình cloud và chia sẻ tệp
using Doconut.Configs.Conversion;    // ConversionTarget

Tên các kiểu không thay đổi — PdfConfig, WordConfig, ExcelConfig, CssConfig, ScriptConfig và các phần còn lại vẫn còn. Nếu bạn đang di chuyển một ứng dụng hiện có, hầu hết các tệp chỉ cần xóa hai dòng using; xem hướng dẫn di chuyển.

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 — các giá trị mặc định dưới đây áp dụng khi một thuộc tính không được đặt.

Thuộc tínhMặc địnhMô tả
ShowDoconutInfofalseKhi true, một yêu cầu 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.
UnsafeModefalseKhi true, bỏ qua kiểm tra bảo mật ASP.NET-session trên các yêu cầu trang. Tắt trong môi trường sản xuất. Lưu ý cách viết — thư viện trước gọi nó là UnSafeMode.
MiddlewarePath"/doconut"Giá trị phối hợp cho endpoint page-image. Nó được xác thực, nhưng không tự tạo nhánh; giữ nó đồng nhất với ánh xạ UseDoconut() thực tế và client BasePath.
ResourcesPath"/doconut-res"Nơi các tài nguyên JS/CSS/hình ảnh nhúng được phục vụ từ.
LicensePath"" (empty string)Đường dẫn tới tệp giấy phép. Trống có nghĩa là chuyển sang nguồn tiếp theo, sau đó tự động tìm kiếm.
LicenseContent"" (empty string)Nội dung giấy phép thô — từ biến môi trường, trình quản lý 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.
ResetLicensefalseCờ tương thích dự trữ. Giấy phép được đọc trong quá trình AddDoconut(); khởi động lại ứng dụng sau khi thay thế giấy phép.
MaxConcurrentEditorSessions200Số tối đa các phiên editor trực tiếp (tài liệu mở bằng DocOptions.EditMode). Nếu vượt quá, phiên editor không hoạt động lâu nhất sẽ bị đóng. Các phiên trình xem 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.
EditorSnapshotEveryOps50Khi bật tính năng lưu trữ editor (AddDoconutEditorPersistence), chụp ảnh tài liệu trực tiếp mỗi N thay đổi đã ghi. 0 hoặc giá trị âm sẽ không chụp ảnh trong phiên. Không có ảnh hưởng khi tính năng lưu trữ bị tắt.

Thứ tự ưu tiên giấy phép khi có hơn một nguồn được đặt: LicenseStream thắng LicenseContent thắng LicensePath thắng tự động tìm kiếm — xem Cài đặt Giấy phép.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath     = "Doconut.Viewer.lic";
    options.MiddlewarePath  = "/doconut";     // phối hợp với ánh xạ app và BasePath của client
    options.ResourcesPath   = "/doconut-res"; // nơi mà JS/CSS/hình ảnh của viewer được phục vụ
    options.UnsafeMode      = false;          // giữ bảo mật session luôn bật
    options.ShowDoconutInfo = false;
});

Các bước tiếp theo

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