Устранение неполадок

Диагностика распространённых ошибок

Ниже приведены точные сообщения 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. Состоянию сессии также нужен кэш: в приложении minimal‑API добавьте builder.Services.AddDistributedMemoryCache(), иначе приложение останавливается при запуске с ошибкой Unable to resolve service for type 'IDistributedCache' (приложения MVC и Razor Pages уже регистрируют его).

Изображение ошибки в области страницы с надписью:

text
You Are Not Authorized To View This Page.

Токен был открыт в другой сессии браузера. Типичные причины: cookie сессии не попадает в запросы страницы (настройка кросс‑origin, политика SameSite, API‑клиент без cookie‑хранилища) или приложение перезапущено (новые ключи сессии). Это работа слоя безопасности согласно задумке — см. Основные концепции → Сессии и безопасность. Отказ представляет собой изображение, отданное со статусом 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 из 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; разберите их, используя Перейти к .NET Standard 2.1 вместо поочерёдного исправления.

TypeInitializationException в первом файле презентации:

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» — хост изображения имеет частный или обратный адрес, который сервер отказывается получать. См. Аннотации.

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

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

Была ли эта страница полезной?