Khắc phục sự cố

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

Mỗi tin nhắn dưới đây là văn bản nguyên bản do 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 ASP.NET. Thêm builder.Services.AddSession() và app.UseSession() trước nhánh middleware Doconut. Trạng thái session cũng cần một cache: trong ứng dụng minimal-API thêm builder.Services.AddDistributedMemoryCache(), hoặc ứng dụng sẽ dừng khởi động với Unable to resolve service for type 'IDistributedCache' (các ứng dụng MVC và Razor Pages đã đăng ký sẵn).

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ằng 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, một client API không có cookie jar), hoặc ứng dụng đã khởi động lại (các 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, bị đưa vào 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 chặ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 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 bị 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 đó. 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 (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 đó. Xóa đă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=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 đã 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 đó — mọi tệp PPT/PPTX/PPS/POT/ODP sẽ không mở được 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 domain 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 mã trang không được tải mặc định trên .NET 6. Thêm một lần khi khởi động:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Phông chữ sai hoặc thay thế trên Linux/Docker — container thiếu 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 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 gốc cộng với System.Drawing.EnableUnixSupport=true. Gói cung cấp System.Drawing.Common 6.0.0 vì đây 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á, nhưng im lặng trong môi trường production

Bất ngờ khi đưa vào hoạt động: một giấy phép tạm thời hoạt động cấp mọi khả năng; giấy phép mua của bạn 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ó. 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 chỉ được quét/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 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 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 đề với ứng dụng Quick Start tối thiểu; nếu nó tái hiện ở đó, liên hệ hỗ trợ kèm tài liệu, Program.cs của bạn, và đầu ra chẩn đoán giấy phép.

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