Khắc phục sự cố

Chẩn đoán các lỗi thường gặp

Mỗi thông báo dưới đây là văn bản nguyên gốc mà Doconut tạo ra, được sắp xếp theo triệu chứng. Tìm lỗi của bạn, áp dụng cách khắc phục.

Trình xem không hiển thị gì

Khu vực trình xem trống, console trình duyệt đầy các lỗi 404 cho /doconut-res/...
UseDoconutResources() bị thiếu, hoặc được đặt sau UseDoconut(). Nó phải được đặt đầu tiên trong pipeline.

HTTP 500 với:

text
Session middleware not configured. Call UseSession() before UseDoconut().

Bảo mật token của Doconut (được bật mặc định) cần trạng thái phiên ASP.NET. Thêm builder.Services.AddSession() và app.UseSession() trước nhánh middleware Doconut.

Một hình ảnh lỗi trong khu vực trang hiển thị:

text
You Are Not Authorized To View This Page.

Token đã được mở bởi một phiên trình duyệt khác. Các nguyên nhân thường gặp: cookie phiên không tới các yêu cầu trang (cấu hình cross-origin, chính sách SameSite, một client API không có cookie jar), hoặc ứng dụng đã khởi động lại (các khóa phiên mới). Đây là lớp bảo mật hoạt động như thiết kế — xem Core Concepts → Sessions & Security.

Một hình ảnh lỗi hiển thị:

text
Document session not found. Please re-open document.

Token đã hết hạn (cửa sổ trượt, mặc định 60 phút — DocOptions.TimeOut) hoặc phiên đã bị đóng. Mở lại tài liệu để nhận token mới.

Mở tài liệu thất bại

LicenseException với thông báo từ chối — tệp giấy phép đã được tìm thấy nhưng bị từ chối (chữ ký không hợp lệ, bị giả mạo, nằm trong danh sách đen, hoặc bản dựng ngoài cửa sổ phiên bản/cập nhật của giấy phép). Trạng thái này ngăn việc mở (fail-fast) thay vì giảm xuống watermark; đọc License.RejectionMessage để biết lý do.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

Tiện ích mở rộng này chỉ được xử lý bởi một plugin (ở đây: DICOM) và khả năng này không còn được cấp. Đăng ký plugin và xác minh lic.IsCapabilityGranted(LicenseCapability.Dicom). Một quyền không tạm thời thiếu hoặc không đủ thường gây lỗi sớm hơn trong AddDoconut().

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

Không có trình xem nào — tích hợp, plugin, hoặc tùy chỉnh — hỗ trợ phần mở rộng đó. Kiểm tra danh sách các định dạng được hỗ trợ; đối với các định dạng của bạn, DoconutOptions.RegisterViewer có thể thêm một trình xem.

InvalidDataException — nội dung tệp bị hỏng hoặc không khớp với phần mở rộng của nó (ví dụ: tệp đã được đổi tên). Xác thực các tệp tải lên trước khi mở.

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Bạn đã giải quyết DocumentConverter mà không đăng ký plugin Converter.

Khởi động thất bại

InvalidOperationException đề cập đến một plugin được đăng ký qua AddPlugin — giấy phép không tạm thời hiện tại không cấp quyền cho plugin đó. Gỡ bỏ đăng ký hoặc cài đặt giấy phép có cấp quyền. Một giấy phép thiếu và tệp TRIAL legacy không cấp bất kỳ quyền plugin nào.

ArgumentException từ AddDoconut():

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

Xác thực tùy chọn fail-fast — sửa đường dẫn gây lỗi.

Lỗi xây dựng / phụ thuộc

Lỗi biên dịch CS1705, hoặc tại thời gian chạy khi mở tài liệu:

text
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'

Dự án của bạn đã cố định System.Text.Json hoặc System.Text.Encodings.Web ở phiên bản dưới 8.0.x mà Doconut.NET6 yêu cầu. Loại bỏ việc hạ cấp và để NuGet khôi phục đồ thị gói (System.Text.Json 8.0.6 và System.Text.Encodings.Web 8.0.0 trong gói 26.7.0 đã được kiểm tra).

TypeInitializationException trên tệp trình chiếu đầu tiên:

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

Engine trình chiếu yêu cầu bắt buộc System.Drawing.Common 6.0.0 (được khai báo bởi gói). Đừng xóa hoặc ghi đè phụ thuộc này — mọi việc mở PPT/PPTX/PPS/POT/ODP sẽ thất bại nếu không có nó.

Kết quả đầu ra sai

Các trang có watermark — ứng dụng đang ở trạng thái đánh giá: không tìm thấy tệp giấy phép, cửa sổ tạm thời hoặc đăng ký đã hết hạn, hoặc miền không hợp lệ. Kiểm tra IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — tham chiếu IDoconutLicenseService trên trang Licensing hiển thị một endpoint đã sẵn sàng.

Tài liệu legacy hiển thị văn bản rối — các bảng mã code-page không được tải mặc định trên .NET 6. Thêm một lần ở lúc khởi động:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Phông chữ sai hoặc thay thế trên Linux/Docker — container thiếu các phông chữ của tài liệu. Đặt FontFolders (trên WordConfig/PptConfig) tới thư mục phông chữ đã gắn.

Các bản trình chiếu mở nhưng không hiển thị trên Linux/macOS — renderer PPT/PPTX/PPS/POT/ODP hiện tại yêu cầu libgdiplus native cộng với System.Drawing.EnableUnixSupport=true. Gói cung cấp System.Drawing.Common 6.0.0 vì đó là phiên bản cuối cùng hỗ trợ tùy chọn này.

Tính năng hoạt động trong đánh giá, im lặng trong sản xuất

Bất ngờ khi đưa vào hoạt động: một giấy phép Temporary đang hoạt động cấp mọi khả năng; giấy phép bạn mua chỉ cấp những gì bạn đã mua. Các gói tìm kiếm và chú thích có thể biến mất khi khả năng của chúng không có. Các plugin Converter hoặc DICOM đã đăng ký với giấy phép không tạm thời không đủ sẽ thất bại trong AddDoconut(). So sánh IsCapabilityGranted(...) với mọi tính năng bạn bật trước khi triển khai.

Tìm kiếm không tìm thấy gì (hoặc quá ít)

  • Đối với PDF trực tiếp, AllowSearch không được bật khi mở. Word, Excel và PowerPoint cung cấp cùng công tắc thông qua PdfConfig lồng nhau.
  • Nội dung được quét/chỉ là hình ảnh, vì vậy Search bình thường không có lớp văn bản để khớp. Sử dụng nguồn có văn bản hoặc một PDF projection giữ lại văn bản.
  • HTML và MS Project (MPP) không thể tìm kiếm theo mặc định — đặt DefaultRender = false để chúng được render qua một PDF projection có lớp văn bản gốc. Word, Excel, PowerPoint, TXT, Visio, email, EPUB và MHT tìm kiếm theo mặc định danh mục của chúng.
  • objViewer.CanSearch() là false sau khi khởi tạo — định dạng đã giải quyết không có đường tìm kiếm tiêu chuẩn. Phán quyết này tách biệt với giấy phép Search; hãy xác minh cả hai.

Vẫn gặp khó khăn?

Cô lập vấn đề bằng ứng dụng Quick Start tối thiểu; nếu lỗi tái hiện ở đó, liên hệ hỗ trợ kèm theo tài liệu, Program.cs của bạn và kết quả chẩn đoán giấy phép.

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