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, 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 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:

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 của Doconut. Trạng thái phiên 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).

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 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ư dự định — 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ị:

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 thành watermark; đọc License.RejectionMessage để biết lý do.

LicenseException:

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

Phần 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à 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 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:

text
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 riêng 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:

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 mentioning a plugin registered via 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 cho phép nó. Một giấy phép thiếu và một tệp legacy TRIAL không cấp bất kỳ quyền plugin nào.

ArgumentException from 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 khi chạy thời gian 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 ở dưới phiên bản 8.0.x mà Doconut.NET8 khai báo. Hãy loại bỏ việc hạ cấp và để NuGet khôi phục đồ thị gói (System.Text.Json 8.0.5 và System.Text.Encodings.Web 8.0.0).

Đầu ra trông 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ệ. Khi có giấy phép Temporary đang hoạt động, chỉ đầu ra của plugin mới được gắn watermark. Một bản dựng được phát hành sau ngày đăng ký giấy phép trả phí sẽ không có watermark: việc mở sẽ ném LicenseException. 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 mã trang không được tải mặc định trên .NET 8. Thêm một lần khi khởi động:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Phông chữ sai hoặc bị thay thế — máy chủ không có 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. Trên Linux, xem bên dưới.

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ủ lưu trữ hình ảnh có địa chỉ riêng hoặc loopback, máy chủ từ chối lấy. Xem Annotations.

Linux

Mở bất kỳ tài liệu nào thất bại với:

text
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Cài đặt thư viện cấu hình phông chữ: apt-get install -y libfontconfig1 (fontconfig trên RHEL/Fedora). Xem Installation.

Mở bất kỳ tài liệu nào thất bại với:

text
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.

Ứng dụng tham chiếu một SkiaSharp mới hơn, trực tiếp hoặc qua thư viện khác. Thêm SkiaSharp.NativeAssets.Linux ở cùng phiên bản với SkiaSharp đó.

Mở bất kỳ tài liệu nào thất bại với:

text
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.

Máy chủ không phải là nền tảng được hỗ trợ. Alpine và các bản phân phối dựa trên musl khác không được hỗ trợ: hãy sử dụng một hình ảnh dựa trên Debian hoặc Ubuntu.

Văn bản rộng hơn hoặc hẹp hơn so với Windows, hoặc các dòng ngắt khác nhau — phông chữ của tài liệu không được cài đặt, vì vậy Doconut sử dụng phông chữ đã cài đặt gần nhất. Cài đặt các phông chữ tương thích metric (fonts-liberation cho Arial, Times New Roman và Courier New; fonts-crosextra-carlito và fonts-crosextra-caladea cho Calibri và Cambria), hoặc sao chép các phông chữ có giấy phép của bạn vào /usr/share/fonts/ và chạy fc-cache -f. Văn bản châu Á hiển thị dưới dạng các hộp trống cần fonts-noto-cjk.

Tính năng hoạt động trong giai đoạn đá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 Search và annotation có thể biến mất khi các khả năng của chúng không có. Các plugin Registered Converter hoặc 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 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 một công tắc thông qua PdfConfig lồng nhau của chúng.
  • 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. Hãy 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 — hãy đặt DefaultRender = false để chúng hiển thị qua một 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 của danh mục.
  • 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.
  • Trang đọc giá trị trả về của objViewer.Search(...) — số lượng được truyền trong đối số thứ ba, một callback.

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 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à kết quả chẩn đoán giấy phép.

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