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

Каждое сообщение ниже — буквальный текст, который выдаёт Doconut, сгруппированный по симптомам. Найдите свою ошибку и примените исправление.

Просмотрщик ничего не отображает

Пустая область просмотрщика, консоль браузера заполнена 404‑ми для /doconut-res/...
UseDoconutResources() отсутствует или размещён после UseDoconut(). Он должен быть первым в конвейере.

HTTP 500 с:

Session middleware not configured. Call UseSession() before UseDoconut().

Текст ошибки в области страницы:

You Are Not Authorized To View This Page.

Токен был открыт в другой сессии браузера. Типичные причины: cookie‑сессия не попадает в запросы страницы (настройка кросс‑домена, политика SameSite, клиент API без cookie‑хранилища) или приложение перезапущено (новые ключи сессии). Это работа слоя безопасности — см. Core Concepts → Sessions & Security.

Текст ошибки:

Document session not found. Please re-open document.

Токен истёк (скользящее окно, по умолчанию 60 минут — DocOptions.TimeOut) или сессия была закрыта. Откройте документ заново, чтобы получить новый токен.

Токен безопасности Doconut (включён по умолчанию) требует состояния сессии ASP.NET. Добавьте builder.Services.AddSession() и app.UseSession() до ветки middleware Doconut. Состоянию сессии также нужен кэш: в минимальном API‑приложении добавьте builder.Services.AddDistributedMemoryCache(), иначе приложение завершится с ошибкой Unable to resolve service for type 'IDistributedCache' (в MVC и Razor Pages кэш уже зарегистрирован).

Сервер работает, но страница ведёт себя неправильно — без ошибок где‑либо

Это типичные режимы отказа, которые следует проверять в первую очередь после переноса приложения. Все три оставляют сервер полностью рабочим, документ корректно рендерится и в консоли браузера ничего не выводится.

Индикатор загрузки, который никогда не останавливается. Ваши обратные вызовы просмотрщика объявлены как глобальные функции, названные по идентификатору контейнера — ctlDoc_OnViewerReady() и др. Предыдущий просмотрщик искал эти имена; текущий — нет. Обработчик, который должен был скрыть индикатор, просто не вызывается. Передайте функции через параметры:

objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

Документ за индикатором в порядке. Полный список параметров находится в ViewerConfig.

Отсутствуют иконки или «хром» просмотрщика, остальные части страницы корректны. ResPath пустой или указывает на корень приложения — правильно в предыдущей библиотеке, ошибочно здесь. Нужно указать префикс, который монтирует UseDoconutResources():

ResPath: 'doconut-res/images'   // or '<your ResourcesPath>/images'

Повреждённые плитки для последующих страниц при обслуживании из общего хранилища. Страницы, которые ещё записываются, отвечают 202 Accepted. Клиент без retryOn409: true воспринимает это как неудачную загрузку изображения. См. Distributed Deployments.

Ошибка при открытии документа

LicenseException с сообщением об отклонении — файл лицензии найден, но отклонён (недействительная подпись, повреждён, в чёрном списке или сборка вне окна версии/обновления лицензии). Такое состояние блокирует открытие (fail‑fast) вместо наложения водяного знака; читайте License.RejectionMessage для получения причины.

LicenseException:

This document type requires the 'Dicom' plugin license.

Это расширение поддерживается только плагином (здесь — DICOM), и возможность больше не предоставлена. Зарегистрируйте плагин и проверьте lic.IsCapabilityGranted(LicenseCapability.Dicom). Отсутствие или недостаточность постоянного права обычно приводит к ошибке ещё на этапе 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, но не зарегистрировали плагин конвертера.

Ошибки запуска

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 26.8.0 нацелен на 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).

Стена ошибок компиляции сразу после обновления пакета — это ожидаемо. 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 завершится ошибкой.

Вывод выглядит некорректно

Страницы содержат водяной знак — приложение находится в режиме оценки: файл лицензии не найден, истёк временный или подписочный период, либо неверный домен. Проверьте IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — ссылка на IDoconutLicenseService на странице лицензирования показывает готовый эндпоинт.

Устаревшие документы отображают искажённый текст — кодовые страницы не загружаются по умолчанию. Добавьте один раз при запуске:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Неправильные или заменённые шрифты в Linux/Docker — в контейнере отсутствуют шрифты документа. Укажите FontFolders (в WordConfig/PptConfig) на смонтированный каталог шрифтов.

Презентации открываются, но не рендерятся в Linux/macOS — текущий рендерер PPT/PPTX/PPS/POT/ODP требует нативный libgdiplus плюс System.Drawing.EnableUnixSupport=true. Пакет поставляет System.Drawing.Common 6.0.0, поскольку это последняя версия, поддерживающая этот переключатель.

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

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

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

Изолируйте проблему, используя минимальное приложение Quick Start; если она воспроизводится там, обратитесь в поддержку с документом, вашим Program.cs и выводом диагностики лицензии.