Усунення проблем
Діагностика поширених помилок
Усі повідомлення нижче — це буквальний текст, який генерує 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.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. Додайте один раз під час запуску:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Неправильні або замінені шрифти — на сервері відсутні шрифти документа. Встановіть їх або вкажіть FontFolders (на WordConfig/PptConfig) на папку, що їх містить. На Linux дивіться нижче.
Анотація зображення відображається у переглядачі, але експорт має коробку "Image blocked" — хост зображення має приватну або loopback-адресу, яку сервер відмовляється отримувати. Дивіться Анотації.
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 та виводом діагностики ліцензії.
Чи була ця сторінка корисною?