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

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

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

Перевірка параметрів у режимі fail‑fast — виправте неправильний шлях.

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

Помилка компілятора CS1705 або під час виконання при відкритті документа:

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 при першому файлі презентації:

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, електронна пошта, EPUB та MHT шукаються за їхніми типовими налаштуваннями каталогу.
  • objViewer.CanSearch() повертає false після ініціалізації — визначений формат не має стандартного шляху пошуку. Це рішення окреме від ліцензії Search; перевірте обидва.

Все ще застрягли?

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

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