Усунення проблем
Діагностика поширених помилок
Кожне повідомлення нижче — це буквальний текст, який генерує 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 з:
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 вже реєструють його).
Зображення помилки в області сторінки з текстом:
You Are Not Authorized To View This Page.Токен був відкритий іншим сеансом браузера. Типові причини: cookie сесії не доходить до запитів сторінки (настройка крос‑доменної роботи, політика SameSite, API‑клієнт без cookie‑банки), або додаток перезапустився (нові ключі сесії). Це рівень безпеки працює згідно задуму — див. Core Concepts → Sessions & Security. Відмова — це зображення, подане зі статусом 200, тому монітор, який перевіряє лише коди статусу, рахує його як сторінку.
Зображення помилки з текстом:
Document session not found. Please re-open document.Токен прострочився (ковзне вікно, за замовчуванням 60 хвилин — DocOptions.TimeOut) або сесія була закрита. Відкрийте документ знову, щоб отримати новий токен.
Не вдається відкрити документ
LicenseException з повідомленням про відхилення — файл ліцензії був знайдений, але відхилений (недійсний підпис, підробка, у чорному списку, або збірка поза вікном версії/оновлення ліцензії). Такий стан блокує відкриття (fail-fast) замість переходу до водяного знака; прочитайте License.RejectionMessage для отримання причини.
LicenseException:
This document type requires the 'Dicom' plugin license.Розширення обробляється лише плагіном (тут: DICOM). Плагін зареєстровано, але жодна ліцензія більше не надає йому можливості — зазвичай це тимчасова ліцензія, яка прострочилася після запуску додатку. Встановіть ліцензію, яка це дозволяє, і перевірте IsCapabilityGranted(LicenseCapability.Dicom) на IDoconutLicenseService. Відсутність або недостатність нетимчасової ліцензії зазвичай призводить до помилки під час AddDoconut().
FormatNotSupportedException:
Document format '<extension>' is not supported.Жоден переглядач — вбудований, плагін чи кастомний — не підтримує це розширення. Перевірте список підтримуваних форматів; для власних форматів DoconutOptions.RegisterViewer може додати його.
InvalidDataException — вміст файлу пошкоджений або не відповідає його розширенню (наприклад, файл перейменовано). Перевіряйте завантаження перед відкриттям.
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().Ви вирішили DocumentConverter без реєстрації плагіна Converter.
Помилки запуску
InvalidOperationException згадка про плагін, зареєстрований через AddPlugin — поточна не‑тимчасова ліцензія не надає цю можливість плагіна. Видаліть реєстрацію або встановіть ліцензію, яка це дозволяє. Відсутня ліцензія та застарілий файл TRIAL не надають можливостей плагіна.
ArgumentException з 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.Валідація параметрів швидкого завершення — виправте неправильний шлях.
Помилки збірки / залежностей
Помилка компілятора CS1705, або під час виконання при відкритті документа:
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.NET8. Видаліть зниження версії та дозвольте NuGet відновити граф пакетів (System.Text.Json 8.0.5 і System.Text.Encodings.Web 8.0.0).
Вивід виглядає неправильно
Сторінки містять водяний знак — застосунок знаходиться у стані оцінки: не знайдено файл ліцензії, закінчилася Тімчасова ліцензія або недійсний домен. При активній Тімчасовій ліцензії водяний знак додається лише до виводу плагіна. Збірка, випущена після дати підписки платної ліцензії, не має водяного знака: при відкритті виникає LicenseException. Перевірте IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — посилання IDoconutLicenseService на сторінці ліцензування показує готовий кінцевий пункт.
Застарілі документи відображають спотворений текст — кодування сторінок за замовчуванням не завантажуються в .NET 8. Додайте один раз під час запуску:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Неправильні або замінені шрифти — сервер не має шрифтів документа. Встановіть їх або вкажіть FontFolders (на WordConfig/PptConfig) на папку, що містить їх. На Linux дивіться нижче.
Анотація зображення відображається у переглядачі, але експорт має коробку «Image blocked» — хост зображення має приватну або локальну адресу, яку сервер відмовляється отримувати. Дивіться Анотації.
Linux
Відкриття будь-якого документа завершується помилкою:
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). Дивіться Встановлення.
Відкриття будь-якого документа завершується помилкою:
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.
Відкриття будь-якого документа завершується помилкою:
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 та виводом діагностики ліцензії.
Чи була ця сторінка корисною?