Cài đặt

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

Trình xem Doconut cơ bản cho .NET 6 đượ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 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.

Yêu cầu

Gói chạy trên các nền tảng sau:

Nền tảngĐược hỗ trợ
Windows x64 / x86Có
Linux x64, glibc-based (Debian, Ubuntu, the official mcr.microsoft.com/dotnet/aspnet:6.0-bookworm-slim image)Có
Alpine và các bản phân phối dựa trên musl khácKhông
macOSKhông

Trên Linux, cài đặt thư viện cấu hình phông chữ trước khi tài liệu đầu tiên được mở:

bash
apt-get update && apt-get install -y libfontconfig1

Trên RHEL, Fedora và các bản phân phối tương tự, gói là fontconfig (dnf install -y fontconfig). Đó là gói hệ thống duy nhất mà Doconut cần: các thư viện gốc mà nó sử dụng được bao gồm trong gói NuGet, và libgdiplus không bắt buộc.
Trong Docker, nên dùng aspnet:6.0-bookworm-slim (Debian 12): thẻ aspnet:6.0 mặc định là Debian 11, mà các gương gói của nó có thể thất bại khi cài đặt libfontconfig1. Các trang được vẽ bằng phông chữ đã cài trên máy chủ, vì vậy hãy xem Khắc phục sự cố để biết về phông chữ và các thông báo lỗi trên Linux.

Cài đặt gói

bash
dotnet add package Doconut.NET6

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ả, hãy truyền phiên bản như một tùy chọn riêng:

bash
dotnet add package Doconut.NET6 --version 26.10.0

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

Xác định tích hợp trước khi nâng cấp

ID gói Doconut.NET6 đã được sử dụng bởi cả tích hợp cổ điển và hiện tại của .NET 6. Đừng chọn tài liệu chỉ dựa trên tên gói:

  • DocImage.axd, new Viewer(_cache, _accessor, ...), đồng bộ
    OpenDocument(...), và các script trình xem được sao chép thủ công xác định
    tích hợp cổ điển;
  • AddDoconut(), UseDoconutResources(), một Viewer được tiêm vào, và
    OpenDocumentAsync(...) xác định tích hợp hiện tại được tài liệu này mô tả.

Bản hướng dẫn cài đặt cổ điển đã được dịch tại đây vẫn còn sẵn sàng. Sử dụng hướng dẫn di chuyển để thay đổi các thế hệ; một bản cập nhật gói thông thường sẽ 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ý — chỉ có một overload, 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 tới 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(); // trạng thái phiên cần một bộ nhớ cache (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 trạng thái phiên 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());

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 đây. 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.

Thuộc tínhMặc địnhMô tả
ShowDoconutInfofalseKhi true, một yêu cầu không có token sẽ trả về một banner phiên bản thay vì 404. Hữu ích như một kiểm tra nhanh; nên tắt trong môi trường sản xuất.
UnsafeModefalseKhi true, bỏ qua kiểm tra bảo mật session ASP.NET trên các yêu cầu trang. Nên tắt trong môi trường sản xuất.
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; hãy giữ nó đồng bộ với ánh xạ UseDoconut() thực tế và BasePath của client.
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à sẽ 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ữ. Các dịch vụ .NET 6 hiện tại đọc giấy phép 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 biên tập viên trực tiếp (các tài liệu mở bằng DocOptions.EditMode). Khi vượt quá, phiên biên tập viên không hoạt động ít nhất sẽ bị đóng. Các phiên trình xem bình thường không đượ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ữ biên tập viên (AddDoconutEditorPersistence), chụp ảnh tài liệu trực tiếp mỗi N thay đổi đã ghi lại. 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 thiết lập: LicenseStream ưu tiên hơn LicenseContent, ưu tiên hơn LicensePath, ưu tiên hơn 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ạ ứng dụng và BasePath của client
    options.ResourcesPath   = "/doconut-res"; // nơi các tệp JS/CSS/hình ảnh của viewer được phục vụ từ
    options.UnsafeMode      = false;          // giữ bảo mật phiên được bật
    options.ShowDoconutInfo = false;
});

Các bước tiếp theo

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