Усунення проблем – Doconut Документація

Багато помилок System.Web не піднімають жодного виключення, яке ви можете бачити: сторінка відповідає порожнім 500, іконка повертає 404, або запит ніколи не повертається. Ця сторінка організована за тим, що ви спостерігаєте. Цитовані повідомлення — це буквальний текст, який генерує Doconut.

Симптоми з першого погляду

Що ви бачите	Найймовірніша причина	Виправлення
Кожен запит відповідає порожнім `500`	Виключення у `Application_Start`: плагін без ліцензії, недійсний параметр, неповна конфігурація ферми — або перенаправлення прив’язки, що вказує на версію, якої немає у `bin\`	Журнал подій Windows, Application, джерело ASP.NET. Див. Проблеми запуску
Деякі MVC-сторінки відповідають порожнім `500`	Razor компілює представлення під час виконання: фасад `netstandard` відсутній у `<compilation>`, або представлення використовує C# новіший за 5 (`?.`, `$"..."`, `nameof`)	Додайте фасад (Встановлення); перемістіть логіку з представлення до контролера
Сторінки показують `â€”`, `â€¦` або подібне замість тире та акцентів	Файли сторінок без мітки порядку байтів читаються за ANSI-кодовою сторінкою сервера	`<globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />`
Консоль браузера показує `404` для `HEAD /DocImage.axd?...&page=1`	Обробник зареєстровано без дієслова `HEAD`	`verb="GET,HEAD,POST"` на обробнику
Документ відображається, але іконки панелі інструментів та індикатор завантаження відсутні	`ResPath` вказує на корінь ресурсів, або починається з `/`	`ResPath: 'doconut-res/images'`
`/doconut-res/...` запити відповідають `404`	Модуль ресурсів не зареєстровано, `runAllManagedModulesForAllRequests` вимкнено, або маршрутизація MVC перехоплює шлях	Запис `<modules>`, і `routes.IgnoreRoute("doconut-res/{*pathInfo}")`
Переглядач повідомляє `The viewer handler could not be reached (no response).`	`BasePath` починається з `/` (`'/myapp'` стає `//myapp/…`, інший хост)	`BasePath: '/'` у корені сайту; `'myapp'` у віртуальному каталозі
Переглядач повідомляє `Please make sure your middleware is configured.`	`DocImage.axd` відповів `404`: обробник не у `Web.config`, маршрутизація MVC перехопила його, або `BasePath` вказує в інше місце	Запис `<handlers>`, `routes.IgnoreRoute("{resource}.axd/{*pathInfo}")` та `BasePath`
Кожна сторінка показує `You Are Not Authorized To View This Page.`	Документ відкрито у запиті без стану сесії, стан сесії вимкнено, або cookie сесії не досягає `DocImage.axd`	Див. Не авторизовано
Конверсія Web Forms ніколи не повертає результат	Сторінка блокується на `ConvertAsync` — дедлок	`Async="true"` + `RegisterAsyncTask` (Плагін конвертера)
Кожна сторінка містить водяний знак оцінки	Ліцензію не знайдено — її немає у `<site root>\wwwroot`	Налаштування ліцензії
Віджет завантажується, але його перша дія відповідає `404`	Віджет не ввімкнено, або його `basePath` не є `'/DocImage.axd'`	`options.Add…Widget()`, і `basePath: '/DocImage.axd'`
Перший документ після запуску або перезапуску сайту займає хвилину чи більше; наступні швидкі	Двигуни документів завантажуються при першому відкритті, а антивірус у реальному часі сканує їх під час завантаження	Підготовте сайт і тримайте пул запущеним — див. Перший документ після запуску
Велике завантаження показує сторінку помилки IIS	Завантаження перевищує `maxRequestLength` (KB) або `maxAllowedContentLength` (байт)	Підвищте обидва ліміти вище вашого найбільшого файлу або ліміту віджету

Помилки запуску

Виключення, що викидається у Application_Start, не досягає браузера: кожен запит відповідає порожнім 500, а журнал IIS не містить корисної інформації. Виключення записано у журнал подій Windows (Переглядач подій → Windows Logs → Application, джерело ASP.NET). Типові:

Плагін без ліцензії:

text

The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

Doconut.Viewer.<Capability>.lic плагіна має бути у wwwroot, поруч із Doconut.Viewer.lic. Відсутня ліцензія та застарілий файл TRIAL не надають можливостей плагіну.

Недійсні параметри:

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.

Збірка, яку не вдається завантажити. ASP.NET завантажує кожну збірку у bin\ під час запуску застосунку, тому перенаправлення прив’язки у Web.config, яке вказує на версію, відсутню у bin\, зупиняє весь сайт. Скопіюйте перенаправлення, згенеровані NuGet (для проекту у стилі SDK, з bin\<YourApp>.dll.config) замість ручного редагування, і скопіюйте їх знову після оновлення пакетів.

Ви не маєте дозволу переглядати цю сторінку.

Сторінка відхилена, оскільки запитана сесія ASP.NET ніколи не отримала документ. Перевірте у такому порядку:

Відкриття виконувалося з станом сесії. MVC‑контролери та сторінки Web Forms мають його. Користувацький IHttpHandler, який відкриває документи, повинен реалізовувати System.Web.SessionState.IRequiresSessionState, інакше у нього немає сесії для надання.
Стан сесії увімкнено. <sessionState mode="Off" /> відхиляє кожну сторінку.
Кукі досягає обробника. Запити того ж походження від віджету несуть ASP.NET_SessionId; скрипт, виклик сервер‑до‑сервера або крос‑оригінальна сторінка без кукі цього не робить.
Веб‑ферма: відкриття прив'язує браузер (DocOptions.BrowserId) і сторінка передає квиток (objViewer.View(token, access)); кожен вузол використовує той самий ключ підпису.

Відмова — це зображення, подане зі статусом 200, приблизно 2 KB. Монітор, який перевіряє лише коди статусу, рахує його як сторінку.

Сесію документа не знайдено. Будь ласка, відкрийте документ знову.

Токен прострочив (ковзне вікно, DocOptions.TimeOut, за замовчуванням 60 хвилин), документ був закритий, або — на одному сервері — пул застосунків був перезапущений. Перезапуск відбувається за розкладом, при кожному редагуванні Web.config і після бездіяльності пула (за замовчуванням 20 хвилин в IIS). Відкрийте документ знову, щоб отримати новий токен.

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

LicenseException з причиною відхилення — файл ліцензії знайдено, але відхилено (недійсний підпис, підробка, чорний список або збірка поза вікном версії ліцензії). Відкриття блокується, а не позначається водяним знаком.

LicenseException:

text

This document type requires the 'Dicom' plugin license.

Розширення обробляється лише плагіном (тут DICOM), можливість якого не надано.

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

InvalidDataException — вміст пошкоджений або не відповідає розширенню (перейменований файл). Перевіряйте завантаження перед відкриттям.

InvalidOperationException:

text

No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

DocumentConverter було вирішено без реєстрації плагіна Converter.

Вивід виглядає неправильно

Сторінки містять водяний знак — ліцензію не знайдено, або вона прострочена, або не охоплює цю версію. В IIS ліцензія має бути у wwwroot під коренем сайту (AppContext.BaseDirectory\wwwroot), а не у bin\. Перевірте IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, License.RejectionMessage).

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

csharp

// Global.asax.cs, Application_Start - перед DoconutHost.Initialize.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Неправильні або замінені шрифти — на сервері відсутні шрифти документа. Windows Server без Office має значно менше шрифтів, ніж робоча машина. Встановіть шрифти або вкажіть FontFolders (на WordConfig та PptConfig) на папку, що їх містить.

Анотація зображення відображається у переглядачі, але експорт має вікно «Image blocked» — хост зображення має приватну або локальну адресу, яку сервер відмовляється отримувати. Дивіться Анотації.

Функція працювала в оцінці, беззвучно в продакшені

Активна тимчасова ліцензія надає всі можливості; ваша придбана ліцензія надає лише те, що ви купили. Без можливості її файли пошуку або анотації не генеруються, і зареєстрований плагін зупиняє сайт під час запуску. Порівняйте IsCapabilityGranted(...) з усіма функціями, які ви використовуєте, перед розгортанням.

Пошук нічого не знаходить (або занадто мало)

Для PDF, AllowSearch не був увімкнений під час відкриття документа — за замовчуванням використовується false. Word, Excel і PowerPoint мають той самий перемикач.
Вміст скановано або лише зображення, тому немає текстового шару для пошуку.
HTML та Microsoft Project (MPP) не підлягають пошуку за замовчуванням: встановіть DefaultRender = false, щоб вони рендерилися через PDF‑проекцію з текстом.
objViewer.CanSearch() є false після ініціалізації: визначений формат не має шляху пошуку. Це окремо від ліцензії Search; перевірте обидва.
Сторінка читає повернене значення objViewer.Search(...) — кількість надходить у третій аргумент, колбек.

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

Відтворіть проблему з мінімальним налаштуванням з Швидкий старт. Якщо вона відтворюється там, зверніться до підтримки з документом, вашим Global.asax.cs, частинами Doconut з Web.config та записом журналу подій Windows, якщо такий є.