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

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

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

Viewer ничего не показывает

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

HTTP 500 с сообщением:

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

Безопасность токенов Doconut (включена по умолчанию) требует состояния сессии ASP.NET. Добавьте builder.Services.AddSession() и app.UseSession() до ветки middleware Doconut.

На странице появляется изображение с надписью:

text
You Are Not Authorized To View This Page.

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

Изображение с ошибкой:

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

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

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

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

LicenseException:

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

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

Проверка параметров в режиме fail‑fast — исправьте некорректный путь.

Ошибки сборки / зависимости

Ошибка компилятора CS1705 или во время выполнения при открытии документа:

text
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'

В вашем проекте зафиксирована версия System.Text.Json или System.Text.Encodings.Web ниже 8.0.x, чем требуют зависимости Doconut.NET6. Уберите понижение версии и позвольте NuGet восстановить граф пакетов (System.Text.Json 8.0.6 и System.Text.Encodings.Web 8.0.0 в пакете 26.7.0).

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

text
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 уже содержит готовый эндпоинт.

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

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

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