Cài đặt

Trình xem Doconut cơ bản cho .NET Standard được cung cấp dưới dạng một gói NuGet 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 lần render đầu tiên.

Kiểm tra khung nền tảng 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 build netstandard2.0 trước đó, và đây là điều đầu tiên cần xác minh:

Nếu ứng dụng chạy trên .NET Framework, đây không phải là gói đúng. Hãy sử dụng Doconut.NETFramework thay thế; từ 26.9.0 nó yêu cầu .NET Framework 4.7.2. Các ứng dụng tham chiếu được phát hành cùng bản này nhắm mục tiêu net8.0.

Cài đặt gói

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. Để tái tạo chính xác bản phát hành 26.8.0 hiện tại, hãy truyền phiên bản như một tùy chọn:

dotnet add package Doconut.NETStandard --version 26.8.0

Doconut.NETStandard là ID gói. Hậu tố .26.8.0 thuộc về tên tệp Doconut.NETStandard.26.8.0.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 phát hành dưới cùng một ID gói, và chỉ có phiên bản phân biệt chúng:

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 ngay sự 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, synchronous 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 đây;
• AddDoconut(), UseDoconutResources(), một Viewer được tiêm, và OpenDocumentAsync(...) xác định tích hợp hiện tại được tài liệu ở đây.

Bản dịch của hướng dẫn cài đặt trước đây vẫn khả dụ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, vòng đời 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 nếu gọi nó trước sẽ khiến mọi yêu cầu tới tài nguyên /doconut-res không tới trình xử lý tài nguyên và trả về 404. 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.

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

app.UseSession();          // gọi UseSession() trước UseDoconut()
app.UseDoconutResources(); // phải đăng ký trước UseDoconut()
app.UseDoconut();

Không gian tên

Các kiểu cấu hình không còn phân tán qua bốn không gian tên. 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:

using Doconut;                       // Viewer, DoconutOptions, DocOptions, tất cả cấu hình định dạng
using Doconut.Middleware;            // AddDoconut, UseDoconut, UseDoconutResources
using Doconut.Clouds;                // cấu hình đám mây 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 tồn tại. 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 sẽ áp dụng khi một thuộc tính không được đặ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 License Setup.

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

Các bước tiếp theo

• Bắt đầu nhanh — mở tài liệu đầu tiên của bạn và render nó trong trình duyệt.
• Cài đặt giấy phép — nơi Doconut tìm kiếm tệp giấy phép của bạn.