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

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

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

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

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.

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

Document session not found. Please re-open document.

Токен прострочився (ковзне вікно, за замовчуванням 60 хвилин — DocOptions.TimeOut) або сесія була закрита. Відкрийте документ знову, щоб отримати новий токен.

Сервер у порядку, але сторінка поводиться неправильно — без жодних помилок

Це типи збоїв, які слід підозрювати першими після перенесення застосунку. Усі три залишають сервер працюючим бездоганно, правильно рендерять документ і не виводять нічого в консоль браузера.

Індикатор завантаження, який ніколи не зупиняється. Ваші зворотні виклики переглядача оголошені як глобальні функції, названі за ідентифікатором контейнера — ctlDoc_OnViewerReady() та інші. Попередній переглядач шукав ці імена; цей їх не знаходить. Обробник, який мав би сховати індикатор, просто не виконується. Передайте функції як параметри замість цього:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

Документ за індикатором у порядку. Повний список параметрів знаходиться в КонфігураціяПереглядача.

Відсутні іконки переглядача або хром, інші сторінки правильні. ResPath порожній або вказує на корінь застосунку — у попередній бібліотеці це було правильно, тут — ні. Потрібно вказати префікс, який монтує UseDoconutResources():

ResPath: 'doconut-res/images'   // або '<your ResourcesPath>/images'

Зламані плитки на пізніших сторінках при обслуговуванні з спільного сховища. Сторінки, які ще записуються, відповідають 202 Accepted. Клієнт без retryOn409: true сприймає це як невдале зображення. Див. Розподілені розгортання.

Не вдається відкрити документ

LicenseException з повідомленням про відхилення — файл ліцензії знайдено, але він відхилений (недійсний підпис, пошкоджений, у чорному списку або збірка поза діапазоном версії/оновлення ліцензії). Такий стан блокує відкриття (fail‑fast) замість переходу до водяного знака; читайте License.RejectionMessage для отримання причини.

LicenseException:

This document type requires the 'Dicom' plugin license.

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

Швидка валідація параметрів — виправте неправильний шлях.

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

Пакет взагалі не встановлюється — Doconut.NETStandard 26.8.0 орієнтується на netstandard2.1, тому NuGet відхиляє проєкт .NET Framework. Це не виправна помилка відновлення: .NET Framework не може споживати netstandard2.1. Використайте пакет Doconut.NETFramework замість нього.

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

Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

Ваш проєкт зафіксував System.Text.Json або System.Text.Encodings.Web нижче версії 9.0.x, яка оголошена в Doconut.NETStandard. Приберіть зниження версії та дозвольте NuGet відновити граф залежностей (System.Text.Json 9.0.0 і System.Text.Encodings.Web 9.0.0 у перевіреному пакеті 26.8.0).

Стіна помилок компіляції одразу після оновлення пакету — це очікувано. 26.8.0 має інший API‑поверх, ніж 26.7.0, і не є сумісним оновленням. Більшість помилок – це рядки using, які перемістилися до кореневого простору імен Doconut; пройдіть Migrate to .NET Standard 2.1 замість того, щоб виправляти їх поодинці.

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

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 на сторінці ліцензування показує готовий кінцевий пункт.

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

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, оскільки це остання версія, яка підтримує цей перемикач.

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

Класичний сюрприз після запуску: активна тимчасова ліцензія надає всі можливості; ваша придбана ліцензія надає лише те, за що ви заплатили. Пакети пошуку та анотацій можуть зникнути, якщо їх можливості відсутні. Зареєстровані конвертери або 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; перевірте обидва.

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

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