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

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

Кожне повідомлення нижче — це буквальний текст, який генерує 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 сесії не доходить до запитів сторінки (налаштування крос‑origin, політика SameSite, клієнт API без cookie‑банки) або застосунок перезапущено (нові ключі сесії). Це робота шару безпеки згідно з задумом — дивіться Core Concepts → Sessions & Security.

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

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 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.

Валідація параметрів у режимі fail-fast — виправте неправильний шлях.

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

Compiler error CS1705, or at runtime when opening a document:

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 у перевіреному пакеті 26.7.0).

TypeInitializationException on the first presentation file:

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 6. Додайте один раз під час запуску:

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 та виводом діагностики ліцензії.

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