Усунення проблем
Діагностика поширених помилок
Кожне повідомлення нижче — це буквальний текст, який генерує Doconut, організований за симптомами. Знайдіть свою помилку, застосуйте виправлення.
Переглядач нічого не показує
Порожня область переглядача, консоль браузера заповнена 404‑ми для /doconut-res/...
UseDoconutResources() відсутній, або розташований після UseDoconut(). Він повинен бути першим у конвеєрі.
Переглядач повідомляє The viewer handler could not be reached (no response).
Запит ніколи не отримав відповіді. Поширеною причиною є BasePath, який починається з /: '/doconut' стає //doconut/DocImage.axd, запитом до іншого хоста. Запишіть його без початкового слешу (BasePath: 'doconut').
Переглядач повідомляє Please make sure your middleware is configured.
Кінцева точка сторінки відповіла 404: UseDoconut() не змонтовано там, куди вказує BasePath клієнта. З app.Map("/doconut", branch => branch.UseDoconut()) клієнт використовує BasePath: 'doconut'.
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. Відмова — це зображення, подане зі статусом 200, тому монітор, який перевіряє лише коди статусу, рахує його як сторінку.
Зображення помилки з текстом:
Document session not found. Please re-open document.Токен прострочив (ковзне вікно, за замовчуванням 60 хвилин — DocOptions.TimeOut) або сесія була закрита. Відкрийте документ знову, щоб отримати новий токен.
Сервер у порядку, але сторінка поводиться неправильно — без жодних помилок
Ось режими відмов, які слід підозрювати першими після перенесення застосунку. Усі три залишають сервер у справному стані, коректно рендерять документ і не повідомляють нічого в консолі браузера.
Зайнятий індикатор, який ніколи не зупиняється. Ваші зворотні виклики переглядача оголошені як глобальні функції, названі за ідентифікатором контейнера — ctlDoc_OnViewerReady() та подібні. Попередній переглядач шукав ці імена; цей — ні. Обробник, який мав би приховати індикатор, просто ніколи не виконується. Передайте функції як параметри замість цього:
function ctlDoc_OnViewerBusy() { /* показати ваш індикатор зайнятості */ }
function ctlDoc_OnViewerReady() { /* приховати його */ }
function ctlDoc_Copy(text) { /* використати скопійований текст */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* повідомляти про прогрес */ }
const objViewer = $('#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 з повідомленням про відхилення — файл ліцензії знайдено, але він відхилений (недійсний підпис, підробка, у чорному списку або збірка поза вікном версії/оновлення ліцензії). Такий стан блокує відкриття (швидке відмовлення) замість переходу до водяного знака; читайте License.RejectionMessage для отримання причини.
LicenseException:
This document type requires the 'Dicom' plugin license.Розширення обробляється лише плагіном (тут: DICOM). Плагін зареєстровано, але жодна ліцензія більше не надає йому можливість — зазвичай це тимчасова ліцензія, яка закінчилася після запуску програми. Встановіть ліцензію, що її надає, і перевірте IsCapabilityGranted(LicenseCapability.Dicom) на IDoconutLicenseService. Відсутність або недостатність нетимчасового права зазвичай призводить до помилки раніше, під час 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 from 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 орієнтується на 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 має інший набір API, ніж 26.7.0, і не є сумісним оновленням. Більшість помилок — це рядки using, які перемістилися у кореневий простір імен Doconut; працюйте за рекомендацією Migrate to .NET Standard 2.1 замість виправлення їх поодинці.
TypeInitializationException on the first presentation file:
Could not load ... System.Drawing.Common, Version=6.0.0.0Двигун презентацій жорстко вимагає System.Drawing.Common 6.0.0 (оголошено у пакеті). Не видаляйте і не перевизначайте цю залежність — відкриття будь-якого PPT/PPTX/PPS/POT/ODP без неї завершується помилкою.
Вихід виглядає неправильно
Сторінки містять водяний знак — додаток знаходиться у стані оцінки: не знайдено файл ліцензії, закінчилася Тимчасова ліцензія або недійсний домен. При активній Тимчасовій ліцензії лише вихід плагінів має водяний знак. Збірка, випущена після дати підписки платної ліцензії, не має водяного знака: відкриття генерує LicenseException. Перевірте IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — посилання IDoconutLicenseService на сторінці ліцензування показує готову кінцеву точку.
Старі документи відображають спотворений текст — кодування сторінок за замовчуванням не завантажуються. Додайте один раз під час запуску:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Неправильні або замінені шрифти — на сервері відсутні шрифти документа. Встановіть їх або вкажіть FontFolders (на WordConfig/PptConfig) на папку, що їх містить.
Анотація зображення відображається у переглядачі, але експорт має коробку "Image blocked" — хост зображення має приватну або локальну адресу, яку сервер відмовляється отримувати. Дивіться Annotations.
Функція працювала в оцінці, беззвучна у виробництві
Класичний сюрприз під час запуску: активна тимчасова ліцензія надає всі можливості; ваша придбана ліцензія надає лише те, що ви купили. Пакети пошуку та анотацій можуть зникнути, коли їх можливості відсутні. Зареєстрований 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після ініціалізації — визначений формат не має стандартного шляху пошуку. Це рішення окреме від ліцензії Пошуку; перевірте обидва.- Сторінка читає повернене значення
objViewer.Search(...)— кількість передається у його третьому аргументі, колбеку.
Все ще застрягли?
Ізолюйте проблему у мінімальному додатку Швидкий старт; якщо вона відтворюється там, зверніться до підтримки з документом, вашим Program.cs та виводом діагностики ліцензії.
Чи була ця сторінка корисною?