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

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

Кожне повідомлення нижче — це точний текст, який генерує 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. Стан сесії також потребує кешу: у мінімальному 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.

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

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

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