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

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

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

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. Відмова — це зображення, подане зі статусом 200, тому монітор, який перевіряє лише коди статусу, рахує його як сторінку.

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

text
Document session not found. Please re-open document.

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

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

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

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

javascript
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():

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

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

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

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

LicenseException:

text
This document type requires the 'Dicom' plugin license.

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

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

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

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

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

text
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:

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

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

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

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