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

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

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

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

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

Изображение ошибки с надписью:

Document session not found. Please re-open document.

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

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

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, не зарегистрировав плагин 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.

Быстрая проверка параметров — исправьте некорректный путь.

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

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

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 при первом файле презентации:

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

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