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

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

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

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

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

HTTP 500 з:

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

Безпека токенів Doconut (увімкнена за замовчуванням) потребує стану сесії ASP.NET. Додайте builder.Services.AddSession() та app.UseSession() перед гілкою проміжного програмного забезпечення Doconut.

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

text
You Are Not Authorized To View This Page.

Токен був відкритий в іншій сесії браузера. Типові причини: cookie сесії не доходить до запитів сторінки (крос‑оригінальна конфігурація, політика SameSite, API‑клієнт без cookie‑скриньки) або застосунок перезапущений (нові ключі сесії). Це рівень безпеки працює згідно задуму — дивіться Основні концепції → Сесії та безпека.

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

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), і можливість більше не надана. Зареєструйте плагін і перевірте lic.IsCapabilityGranted(LicenseCapability.Dicom). Відсутність або недостатність непостійного права зазвичай викликає помилку раніше під час 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=10.0.0.0'

У вашому проєкті зафіксовано System.Text.Json / System.Text.Encodings.Web нижче 10.0.x. Видаліть пониження та дозвольте NuGet відновити версії, які оголошує Doconut.NET8.

TypeInitializationException у першому файлі презентації:

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

Двигун презентацій жорстко вимагає System.Drawing.Common 6.0.0 (оголошено в пакеті). Не видаляйте і не перевизначайте цю залежність — без неї відкриття будь‑якого PPT/PPTX/PPS/POT/ODP не вдається.

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

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

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Неправильні або замінені шрифти у Linux/Docker — у контейнері відсутні шрифти документа. Вкажіть FontFolders (у WordConfig/PptConfig) на змонтований каталог шрифтів.

Презентації відкриваються, але не відображаються у Linux/macOS — поточний рендерер PPT/PPTX/PPS/POT/ODP вимагає нативний libgdiplus плюс System.Drawing.EnableUnixSupport=true. Пакет постачає System.Drawing.Common 6.0.0, оскільки це остання версія, що підтримує цей параметр.

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

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

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

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

Все ще не вдається?

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

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