Устранение неполадок
Диагностика распространённых ошибок
Ниже приведены точные сообщения 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. Состоянию сессии также нужен кэш: в приложении minimal‑API добавьте builder.Services.AddDistributedMemoryCache(), иначе приложение останавливается при запуске с ошибкой Unable to resolve service for type 'IDistributedCache' (приложения MVC и Razor Pages уже регистрируют его).
Изображение ошибки в области страницы с надписью:
You Are Not Authorized To View This Page.Токен был открыт в другой сессии браузера. Типичные причины: cookie сессии не попадает в запросы страницы (настройка кросс‑origin, политика SameSite, API‑клиент без cookie‑хранилища) или приложение перезапущено (новые ключи сессии). Это работа слоя безопасности согласно задумке — см. Основные концепции → Сессии и безопасность. Отказ представляет собой изображение, отданное со статусом 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 из 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; разберите их,
используя Перейти к .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 без неё завершится ошибкой.
Вывод выглядит некорректно
Страницы содержат водяной знак — приложение находится в режиме оценки: не найден файл лицензии, истекла временная лицензия или неверный домен. При активной временной лицензии только вывод плагинов помечается водяным знаком. Сборка, выпущенная после даты подписки платной лицензии, не имеет водяного знака: при открытии возникает LicenseException. Проверьте IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — ссылка IDoconutLicenseService на странице лицензирования показывает готовый конец‑точки.
Устаревшие документы отображают искажённый текст — кодовые страницы не загружаются по умолчанию. Добавьте один раз при запуске:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Неправильные или заменённые шрифты — на сервере отсутствуют шрифты документа. Установите их или укажите FontFolders (на WordConfig/PptConfig) на папку, где они находятся.
Аннотация изображения отображается в просмотрщике, но при экспорте появляется окно «Image blocked» — хост изображения имеет частный или обратный адрес, который сервер отказывается получать. См. Аннотации.
Функция работала в оценке, молчала в продакшене
Классический сюрприз при вводе в эксплуатацию: активная временная лицензия предоставляет все возможности; ваша приобретённая лицензия предоставляет только то, что вы купили. Пакеты поиска и аннотаций могут исчезнуть, когда их возможности отсутствуют. Зарегистрированный 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(...)— счёт приходит в его третий аргумент, обратный вызов.
Всё ещё застряли?
Изолируйте проблему, используя минимальное приложение Quick Start; если она воспроизводится там, обратитесь в поддержку с документом, вашим Program.cs и выводом диагностики лицензии.
Была ли эта страница полезной?