Усунення проблем

Діагностика поширених помилок

Усі повідомлення нижче — це буквальний текст, який генерує Doconut, упорядкований за симптомами. Знайдіть свою помилку, застосуйте виправлення.

Переглядач нічого не показує

Порожня область переглядача, консоль браузера заповнена 404‑ками для /doconut-res/...
UseDoconutResources() відсутній, або розташований після UseDoconut(). Він має бути першим у конвеєрі.

Переглядач повідомляє The viewer handler could not be reached (no response).
Запит ніколи не отримав відповіді. Поширеною причиною є BasePath, який починається з /: '/doconut' стає //doconut/DocImage.axd, запитом до іншого хоста. Запишіть його без початкового слешу (BasePath: 'doconut').

Переглядач повідомляє Please make sure your middleware is configured.
Кінцева точка сторінки відповіла 404: UseDoconut() не змонтовано там, куди вказує BasePath клієнта. За допомогою app.Map("/doconut", branch => branch.UseDoconut()), клієнт використовує BasePath: 'doconut'.

HTTP 500 з:

text
Session middleware not configured. Call UseSession() before UseDoconut().

Токенова безпека Doconut (увімкнена за замовчуванням) потребує стану сесії ASP.NET. Додайте builder.Services.AddSession() і app.UseSession() перед гілкою проміжного програмного забезпечення Doconut. Стан сесії також потребує кешу: у мінімальному API‑додатку додайте builder.Services.AddDistributedMemoryCache(), або застосунок зупиниться під час запуску через Unable to resolve service for type 'IDistributedCache' (додатки MVC і Razor Pages вже реєструють його).

Зображення помилки в області сторінки з текстом:

text
You Are Not Authorized To View This Page.

Токен був відкритий іншим сеансом браузера. Типові причини: cookie сесії не доходить до запитів сторінки (налаштування крос‑доменної роботи, політика SameSite, API‑клієнт без сховища cookie), або застосунок перезапустився (нові ключі сесії). Це робота шару безпеки згідно з задумом — див. Core Concepts → Sessions & Security. Відмова — це зображення, подане зі статусом 200, тому монітор, який перевіряє лише коди статусу, рахує його як сторінку.

Зображення помилки з текстом:

text
Document session not found. Please re-open document.

Токен прострочився (ковзне вікно, за замовчуванням 60 хвилин — DocOptions.TimeOut) або сесія була закрита. Відкрийте документ знову, щоб отримати новий токен.

Не вдається відкрити документ

LicenseException з повідомленням про відхилення — файл ліцензії знайдено, але він відхилений (недійсний підпис, підробка, у чорному списку або збірка поза діапазоном версії/оновлення ліцензії). Такий стан блокує відкриття (fail‑fast) замість переходу до водяного знака; читайте License.RejectionMessage для отримання причини.

LicenseException:

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

Розширення обробляється лише плагіном (тут: DICOM). Плагін зареєстровано, але жодна ліцензія більше не надає йому можливість — зазвичай це тимчасова ліцензія, яка прострочилася після запуску застосунку. Встановіть ліцензію, що надає цю можливість, і перевірте IsCapabilityGranted(LicenseCapability.Dicom) на IDoconutLicenseService. Відсутність або недостатність постійного права зазвичай призводить до помилки раніше, під час AddDoconut().

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

Жоден переглядач — вбудований, плагін або користувацький — не підтримує це розширення. Перевірте список підтримуваних форматів; для власних форматів DoconutOptions.RegisterViewer може додати його.

InvalidDataException — вміст файлу пошкоджений або не відповідає його розширенню (наприклад, файл перейменовано). Перевіряйте завантаження перед відкриттям.

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Ви вирішили DocumentConverter без реєстрації плагіна Converter.

Помилки запуску

InvalidOperationException згадує плагін, зареєстрований через AddPlugin — поточна непостійна ліцензія не надає цю можливість плагіна. Видаліть реєстрацію або встановіть ліцензію, яка її надає. Відсутня ліцензія та застарілий файл TRIAL не надають можливостей плагіна.

ArgumentException від 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.

Перевірка параметрів швидкого завершення — виправте проблемний шлях.

Помилки збірки / залежностей

Помилка компілятора CS1705, або під час виконання під час відкриття документа:

text
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'

Ваш проєкт закріпив System.Text.Json або System.Text.Encodings.Web нижче 8.0.x залежностей, оголошених Doconut.NET6. Видаліть пониження версії та дозвольте NuGet відновити граф пакетів (System.Text.Json 8.0.6 та System.Text.Encodings.Web 8.0.0, як оголошено у пакеті).

Вивід виглядає неправильно

Сторінки містять водяний знак — додаток перебуває у стані оцінки: не знайдено файл ліцензії, закінчилася Тимчасова ліцензія або недійсний домен. При активній Тимчасовій ліцензії лише вивід плагіна має водяний знак. Збірка, випущена після дати підписки платної ліцензії, не має водяного знаку: при відкритті виникає LicenseException. Перевірте IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — посилання IDoconutLicenseService на сторінці Ліцензування показує готовий кінцевий пункт.

Застарілі документи відображають спотворений текст — кодування кодових сторінок не завантажуються за замовчуванням у .NET 6. Додайте один раз під час запуску:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Неправильні або замінені шрифти — на сервері відсутні шрифти документа. Встановіть їх або вкажіть FontFolders (на WordConfig/PptConfig) на папку, що їх містить. На Linux дивіться нижче.

Анотація зображення відображається у переглядачі, але експорт має коробку "Image blocked" — хост зображення має приватну або loopback-адресу, яку сервер відмовляється отримувати. Дивіться Анотації.

Linux

Відкриття будь-якого документа завершується помилкою:

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.

Встановіть бібліотеку налаштування шрифтів: apt-get install -y libfontconfig1 (fontconfig на RHEL/Fedora). Дивіться Встановлення.

Відкриття будь-якого документа завершується помилкою:

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.

Додаток посилається на новішу версію SkiaSharp, безпосередньо або через іншу бібліотеку. Додайте SkiaSharp.NativeAssets.Linux тієї ж версії, що й SkiaSharp.

Відкриття будь-якого документа завершується помилкою:

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.

Хост не підтримується платформою. Alpine та інші дистрибутиви на базі musl не підтримуються: використовуйте образ на базі Debian або Ubuntu.

Текст ширший або вужчий, ніж у Windows, або рядки розбиваються інакше — шрифти документа не встановлені, тому Doconut використовує найближчий встановлений шрифт. Встановіть метрично сумісні шрифти (fonts-liberation для Arial, Times New Roman та Courier New; fonts-crosextra-carlito і fonts-crosextra-caladea для Calibri та Cambria), або скопіюйте власні ліцензовані шрифти до /usr/share/fonts/ і запустіть fc-cache -f. Для азійського тексту, що відображається порожніми коробками, потрібен fonts-noto-cjk.

Функція працювала в оцінювальному режимі, мовчить у продакшені

Класичний сюрприз під час запуску: активна тимчасова ліцензія надає всі можливості; ваша придбана ліцензія надає лише те, за що ви заплатили. Пакети пошуку та анотацій можуть зникнути, коли їх можливості відсутні. Зареєстрований конвертер або DICOM‑плагіни з недостатньою нетимчасовою ліцензією зазнають невдачі під час AddDoconut(). Порівняйте IsCapabilityGranted(...) з кожною функцією, яку ви вмикаєте перед розгортанням.

Пошук нічого не знаходить (або занадто мало)

  • Для прямого PDF, AllowSearch не був увімкнений під час відкриття. Word, Excel та PowerPoint надають той самий перемикач через їхні вкладені PdfConfig.
  • Вміст скановано/лише зображення, тому звичайний Пошук не має текстового шару для збігу. Використовуйте джерело з текстом або проекцію PDF, що зберігає текст.
  • HTML та MS Project (MPP) не підлягають пошуку у їхніх типових налаштуваннях — встановіть DefaultRender = false, щоб вони рендерилися через проекцію PDF з вбудованим текстовим шаром. Word, Excel, PowerPoint, TXT, Visio, електронна пошта, EPUB та MHT шукаються у їхніх типових налаштуваннях каталогу.
  • objViewer.CanSearch() є false після ініціалізації — визначений формат не має стандартного шляху пошуку. Це рішення окреме від ліцензії на Пошук; перевірте обидва.
  • Сторінка читає повернене значення objViewer.Search(...) — кількість надходить у його третій аргумент, зворотний виклик.

Все ще застрягли?

Ізолюйте проблему за допомогою мінімального додатку Quick Start; якщо вона відтворюється там, зверніться до підтримки з документом, вашим Program.cs та виводом діагностики ліцензії.

Чи була ця сторінка корисною?