Khắc phục sự cố

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:

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. Trạng thái session cũng cần một bộ nhớ 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 lỗi trong khu vực trang hiển thị:

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 đến được 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ư dự kiến — xem Core Concepts → Sessions & Security.

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

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áy chủ hoạt động bình thường nhưng trang hiển thị lỗi — mà không có lỗi nào

Đây là các chế độ lỗi cần nghi ngờ đầu tiên sau khi triển khai một ứng dụng. Cả ba đều để máy chủ hoạt động hoàn hảo, hiển thị tài liệu đúng, và không báo cáo gì trong console trình duyệt.

Một vòng quay đang hoạt động không bao giờ dừng. Các callback của trình xem của bạn được khai báo như các hàm toàn cục có tên trùng với id của container — ctlDoc_OnViewerReady() và các hàm liên quan. Trình xem trước đã tra cứu các tên này; trình xem hiện tại không. Trình xử lý mà sẽ ẩn vòng quay đơn giản không bao giờ chạy. Hãy truyền các hàm này như các tùy chọn thay vì:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

Tài liệu phía sau vòng quay vẫn bình thường. Danh sách đầy đủ các tùy chọn có trong Cấu hình Trình xem.

Thiếu biểu tượng hoặc chrome của trình xem, các trang khác vẫn đúng. ResPath trống hoặc trỏ tới gốc ứng dụng — đúng trong thư viện trước, sai ở đây. Nó phải chỉ định tiền tố mà UseDoconutResources() gắn:

ResPath: 'doconut-res/images'   // or '<your ResourcesPath>/images'

Các ô bị hỏng cho các trang sau khi phục vụ từ lưu trữ chung. Các trang vẫn đang được ghi trả lời 202 Accepted. Một client không có retryOn409: true sẽ xem đó như một hình ảnh thất bại. Xem Triển khai Phân tán.

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ị liệt kê đen, hoặc một 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ì chuyển sang watermark; đọc License.RejectionMessage để biết lý do.

LicenseException:

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 nữa. Đăng ký plugin và xác minh lic.IsCapabilityGranted(LicenseCapability.Dicom). Một quyền không đủ hoặc không tồn tại thường sẽ thất bại sớm hơn trong AddDoconut().

FormatNotSupportedException:

Document format '<extension>' is not supported.

Không có trình xem — tích hợp, plugin, hoặc tùy chỉnh — nào 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.

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:

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 tới một plugin được đăng ký qua AddPlugin — giấy phép hiện tại không phải tạm thời không cấp quyền cho plugin đó. Hãy xóa đăng ký hoặc cài đặt một giấy phép có quyền đó. Một giấy phép thiếu và một tệp TRIAL cũ không cấp bất kỳ quyền plugin nào.

ArgumentException từ AddDoconut():

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 nhanh chóng — sửa đường dẫn gây lỗi.

Lỗi biên dịch / phụ thuộc

Gói sẽ không được cài đặt — Doconut.NETStandard 26.8.0 nhắm tới netstandard2.1, vì vậy NuGet từ chối một dự án .NET Framework. Đây không phải là lỗi khôi phục có thể giải quyết: .NET Framework không thể tiêu thụ netstandard2.1. Hãy dùng gói Doconut.NETFramework thay thế.

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

Could not load file or assembly 'System.Text.Json, Version=9.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 9.0.x được khai báo bởi Doconut.NETStandard. Hãy bỏ hạ cấp và để NuGet khôi phục đồ thị gói (System.Text.Json 9.0.0 và System.Text.Encodings.Web 9.0.0 trong gói 26.8.0 đã được kiểm toán).

Một loạt lỗi biên dịch xuất hiện ngay sau khi nâng cấp gói — điều này là dự kiến. 26.8.0 có bề mặt API khác so với 26.7.0, không phải một bản cập nhật tương thích. Hầu hết các lỗi là các dòng using đã chuyển sang không gian tên gốc Doconut; hãy thực hiện Di chuyển sang .NET Standard 2.1 thay vì vá từng cái một.

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

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 thiếu nó.

Kết quả hiển thị sai

Các trang có dấu watermark — ứng dụng đang ở trạng thái đánh giá: không tìm thấy tệp giấy phép, một 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 đã cung cấp một endpoint sẵn có.

Tài liệu cũ hiển thị văn bản rối — các mã trang ký tự không được tải mặc định. Thêm một lần khi khởi động:

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) trỏ tới thư mục phông chữ đã gắn.

Trình chiếu mở được nhưng không hiển thị trên Linux/macOS — bộ render 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á, im lặng trong sản xuất

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 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 tương ứ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 khi gọi 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 trả về 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 một công tắc thông qua PdfConfig lồng nhau.
• Nội dung chỉ được quét/ảnh, vì vậy Search thông thường không có lớp văn bản để khớp. Hãy 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 của danh mục chúng.
• objViewer.CanSearch() trả về 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. Kết luận này riêng biệt với giấy phép Search; hãy xác minh cả hai.

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

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