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 session của 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. Nguyên nhân thường gặp: cookie session không tới các yêu cầu trang (cấu hình cross-origin, chính sách SameSite, client API không có cookie), hoặc ứng dụng đã khởi động lại (khóa session 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 session đã 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ì chuyển sang watermark; đọc License.RejectionMessage để biết lý do.

LicenseException:

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

Phần mở rộng này chỉ được xử lý bởi một plugin (ở đây: DICOM) và khả năng đó 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 sẽ thất bạ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 này. 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 cái.

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 biên dịch / 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=10.0.0.0'

Dự án của bạn đã cố định System.Text.Json / System.Text.Encodings.Web dưới 10.0.x. Loại bỏ việc hạ cấp và để NuGet khôi phục các phiên bản mà Doconut.NET8 khai báo.

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 loại bỏ hoặc ghi đè phụ thuộc đó — mọi việc mở PPT/PPTX/PPS/POT/ODP sẽ thất bại nếu không có nó.

Kết quả hiển thị 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.

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Phông chữ sai hoặc bị 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) vào 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 — trình render PPT/PPTX/PPS/POT/ODP hiện tại yêu cầu libgdiplus gốc cùng 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 môi trường sản xuất

Bất ngờ truyền thố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 chưa đượ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 thông 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 ở mặc định — đặt DefaultRender = false để chúng render qua PDF projection với lớp văn bản gốc. Word, Excel, PowerPoint, TXT, Visio, email, EPUB và MHT tìm kiếm ở 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 dẫn tìm kiếm tiêu chuẩn. Phán quyết này tách biệt khỏ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?