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

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

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

Просмотрщик ничего не показывает

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

HTTP 500 с:

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

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

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

text
You Are Not Authorized To View This Page.

Токен был открыт в другой сессии браузера. Типичные причины: cookie‑сессии не достигает запросов страницы (настройка кросс‑домена, политика 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.

Валидация параметров с быстрым падением — исправьте проблемный путь.

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

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

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

Ваш проект зафиксировал System.Text.Json / System.Text.Encodings.Web ниже версии 10.0.x. Удалите откат и позвольте NuGet восстановить версии, объявленные в Doconut.NET8.

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 8. Добавьте один раз при запуске:

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

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