Khắc phục sự cố
Chẩn đoán các lỗi phổ biến
Mỗi thông báo dưới đây là văn bản nguyên bản 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, bảng điều khiển 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 xuất hiện đầu tiên trong pipeline.
Trình xem báo cáo The viewer handler could not be reached (no response).
Yêu cầu không bao giờ nhận được phản hồi. Nguyên nhân phổ biến là một BasePath bắt đầu bằng /: '/doconut' trở thành //doconut/DocImage.axd, một yêu cầu tới máy chủ khác. Viết nó mà không có dấu gạch chéo đầu tiên (BasePath: 'doconut').
Trình xem báo cáo Please make sure your middleware is configured.
Điểm cuối trang trả lời 404: UseDoconut() không được gắn tại nơi mà BasePath của client chỉ tới. Với app.Map("/doconut", branch => branch.UseDoconut()), client sử dụng BasePath: 'doconut'.
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 phiên ASP.NET. Thêm builder.Services.AddSession() và app.UseSession() trước nhánh middleware của Doconut. Trạng thái phiên cũng cần một bộ nhớ đệm: trong ứng dụng minimal-API, thêm builder.Services.AddDistributedMemoryCache(), hoặc ứng dụng sẽ dừng khi 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).
Một hình ả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 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 (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. Sự từ chối là một hình ảnh được phục vụ với trạng thái 200, vì vậy một công cụ giám sát chỉ kiểm tra mã trạng thái sẽ tính nó là một trang.
Một hình ả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 phiên đã 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ị sai — 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 ứng dụng. Ba trường hợp này đề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 bảng điều khiển trình duyệt.
Một vòng quay đang hoạt động liên tục 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 theo id của container — ctlDoc_OnViewerReady() và các hàm liên quan. Trình xem trước đã tra cứu những tên này; trình xem này 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ư tùy chọn thay vì:
function ctlDoc_OnViewerBusy() { /* hiển thị chỉ báo bận của bạn */ }
function ctlDoc_OnViewerReady() { /* ẩn nó */ }
function ctlDoc_Copy(text) { /* sử dụng văn bản đã sao chép */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* báo cáo tiến độ */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... các tùy chọn hiện có của bạn ...
onViewerBusy: ctlDoc_OnViewerBusy,
onViewerReady: ctlDoc_OnViewerReady,
onCopy: ctlDoc_Copy,
onAutoLoadStatus: ctlDoc_AutoLoadStatus
});Tài liệu phía sau vòng quay vẫn ổn. Danh sách tùy chọn đầy đủ có trong ViewerConfig.
Biểu tượng hoặc chrome của trình xem bị thiếu, 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 đặt tên tiền tố mà UseDoconutResources() gắn:
ResPath: 'doconut-res/images' // hoặc '<your ResourcesPath>/images'Các ô bị hỏng cho các trang sau khi phục vụ từ lưu trữ chia sẻ. Các trang vẫn đang được ghi trả lời 202 Accepted. Một client không có retryOn409: true coi đó là một hình ảnh thất bại. Xem Distributed Deployments.
Mở tài liệu thất bại
LicenseException with a rejection message — 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 nằm 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:
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). Plugin đã được đăng ký, nhưng không còn giấy phép nào cấp quyền cho nó — thường là một giấy phép Temporary đã hết hạn sau khi ứng dụng khởi động. Cài đặt một giấy phép cấp quyền cho nó và xác minh IsCapabilityGranted(LicenseCapability.Dicom) trên IDoconutLicenseService. 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 quá trình AddDoconut().
FormatNotSupportedException:
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 — khai báo hỗ trợ tiện ích 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 riêng bạn, DoconutOptions.RegisterViewer có thể thêm một mục.
InvalidDataException — nội dung tệp bị hỏng hoặc không khớp với tiện ích 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 mentioning a plugin registered via 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 một giấy phép cấp quyền cho nó. Một giấy phép thiếu và một tệp legacy TRIAL không cung cấp bất kỳ khả năng plugin nào.
ArgumentException from 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 fail-fast — sửa đường dẫn gây lỗi.
Lỗi xây dựng / phụ thuộc
Gói không thể cài đặt được — Doconut.NETStandard nhắm mục tiêu
netstandard2.1, vì vậy NuGet từ chối dự án .NET Framework. Đây không phải là lỗi khôi phục có thể giải quyết được: .NET Framework không thể tiêu thụ netstandard2.1. Hãy sử dụng gói
Doconut.NETFramework thay thế.
Lỗi biên dịch CS1705, hoặc khi chạy thời gian 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 dưới phiên bản 9.0.x
các phụ thuộc được khai báo bởi Doconut.NETStandard. Loại bỏ việc 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 như đã khai báo
bởi gói).
Một loạt lỗi biên dịch ngay sau khi nâng cấp gói — đây là điều dự kiến.
26.8.0 có giao diện API khác so với 26.7.0, không phải là 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 xử lý
Di chuyển sang .NET Standard 2.1 thay vì vá chúng từng cái một.
TypeInitializationException on the first presentation file:
Could not load ... System.Drawing.Common, Version=6.0.0.0Engine trình chiếu yêu cầu nghiêm ngặt System.Drawing.Common 6.0.0 (được khai báo bởi gói). Đừng gỡ 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, giấy phép Temporary đã hết hạn, hoặc miền không hợp lệ. Dưới giấy phép Temporary đang hoạt động, chỉ đầu ra của plugin mới có watermark. Một bản dựng được phát hành sau ngày đăng ký của giấy phép trả phí sẽ không có watermark: khi mở sẽ ném LicenseException. Kiểm tra IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — tham chiếu IDoconutLicenseService trên trang Licensing cho thấy một endpoint đã sẵn sàng.
Tài liệu legacy hiển thị văn bản rối loạn — các mã trang mã 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 thay thế — máy chủ thiếu phông chữ của tài liệu. Cài đặt chúng, hoặc chỉ định FontFolders (trên WordConfig/PptConfig) tới một thư mục chứa chúng.
Một chú thích hình ảnh hiển thị trong trình xem nhưng khi xuất ra có hộp "Image blocked" — máy chủ chứa hình ảnh có địa chỉ riêng hoặc loopback, máy chủ từ chối tải về. Xem Chú thích.
Tính năng hoạt động trong đánh giá, im lặng trong sản xuất
Sự bất ngờ truyền thố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 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ó. Bộ chuyển đổi đã đăng ký hoặc các plugin DICOM với giấy phép không tạm thời không đủ sẽ thất bại trong quá trình 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,
AllowSearchkhông được bật khi mở. Word, Excel và PowerPoint cung cấp cùng một công tắc thông quaPdfConfiglồng nhau của chúng. - Nội dung chỉ được quét/hình ảnh, vì vậy Tìm kiếm bình thường không có lớp văn bản để khớp. Hãy sử dụng một nguồn có văn bản hoặc một phép chiếu PDF giữ lại văn bản.
- HTML và MS Project (MPP) không thể tìm kiếm ở mặc định — hãy đặt
DefaultRender = falseđể chúng hiển thị qua một phép chiếu PDF 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àfalsesau khi khởi tạo — định dạng đã giải quyết không có đường dẫn tìm kiếm chuẩn. Phán quyết này tách biệt khỏi giấy phép Tìm kiếm; hãy xác minh cả hai.- Trang đọc giá trị trả về của
objViewer.Search(...)— số lượng đến trong đối số thứ ba của nó, một callback.
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 ở đó, hãy liên hệ hỗ trợ cùng 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?