Cài đặt
Thêm Doconut vào dự án .NET 8 của bạn
Trình xem Doconut cơ bản cho .NET 8 đượ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 | Hỗ trợ |
|---|---|
| Windows x64 / x86 | Có |
Linux x64, glibc-based (Debian, Ubuntu, the official mcr.microsoft.com/dotnet/aspnet:8.0 image) | Có |
| Alpine and other musl-based distributions | Không |
| macOS | Khô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ở:
apt-get update && apt-get install -y libfontconfig1Trê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 đóng gói trong gói NuGet, và libgdiplus không bắt buộc. Các trang được vẽ bằng các phông chữ đã được cài đặt 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
dotnet add package Doconut.NET8Lệ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:
dotnet add package Doconut.NET8 --version 26.10.0Doconut.NET8 là ID của gói. Hậu tố phiên bản thuộc về tên tệp Doconut.NET8.<version>.nupkg đã tải xuống và không phải là một phần của ID.
Đă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ờ đến 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.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state cần một 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 ASP.NET session state
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ính | Mặc định | Mô tả |
|---|---|---|
ShowDoconutInfo | false | Khi 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. |
UnsafeMode | false | Khi 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à 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. |
LicenseStream | null | Giấy phép dưới dạng stream, đọc một lần khi khởi động. |
ResetLicense | false | Cờ tương thích dự phòng. Các dịch vụ .NET 8 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. |
MaxConcurrentEditorSessions | 200 | Số lượng tối đa các phiên biên tập viên trực tiếp (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 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ữ biên tập viên (AddDoconutEditorPersistence), chụp nhanh 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 nhanh 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 thắng LicenseContent, thắng LicensePath, thắng tự động tìm kiếm — xem Cài đặt giấy phép.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.MiddlewarePath = "/doconut"; // phối hợp với app mapping và client BasePath
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
- 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 tệp giấy phép của bạn.
Trang này có hữu ích không?