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

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

Ниже приведены буквальные сообщения 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‑хранилища) или приложение перезапущено (новые ключи сеанса). Это работа слоя безопасности согласно проекту — см. Core Concepts → Sessions & Security. Отказ представляет собой изображение, отданное со статусом 200, поэтому монитор, проверяющий только коды статусов, считает его страницей.

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

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). Плагин зарегистрирован, но лицензия больше не предоставляет ему возможности — обычно это временная лицензия, истёкшая после запуска приложения. Установите лицензию, предоставляющую эту возможность, и проверьте 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.

Проверка параметров быстрого завершения — исправьте проблемный путь.

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

Ошибка компиляции 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.NET8. Удалите понижение версии и позвольте NuGet восстановить граф пакетов (System.Text.Json 8.0.5 и System.Text.Encodings.Web 8.0.0).

Вывод выглядит неправильно

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

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

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

Аннотация изображения отображается в просмотрщике, но экспорт содержит окно «Изображение заблокировано» — хост изображения имеет частный или адрес обратной связи, который сервер отказывается получать. Смотрите Аннотации.

Linux

Открытие любого документа завершается ошибкой:

text
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Установите библиотеку конфигурации шрифтов: apt-get install -y libfontconfig1 (fontconfig на RHEL/Fedora). Смотрите Установка.

Открытие любого документа завершается ошибкой:

text
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.

Приложение ссылается на более новую версию SkiaSharp, напрямую или через другую библиотеку. Добавьте SkiaSharp.NativeAssets.Linux той же версии, что и SkiaSharp.

Открытие любого документа завершается ошибкой:

text
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.

Хост не является поддерживаемой платформой. Дистрибутивы Alpine и другие основанные на musl не поддерживаются: используйте образ на основе Debian или Ubuntu.

Текст шире или уже, чем в Windows, или переносы строк отличаются — шрифты документа не установлены, поэтому Doconut использует ближайший установленный шрифт. Установите совместимые по метрике шрифты (fonts-liberation для Arial, Times New Roman и Courier New; fonts-crosextra-carlito и fonts-crosextra-caladea для Calibri и Cambria), либо скопируйте свои лицензированные шрифты в /usr/share/fonts/ и запустите fc-cache -f. Для азиатского текста, отображаемого пустыми квадратами, требуется fonts-noto-cjk.

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

Классический сюрприз при запуске: активная Temporary лицензия предоставляет все возможности; ваша приобретённая лицензия предоставляет только то, что вы купили. Пакеты поиска и аннотаций могут исчезнуть, когда их возможности отсутствуют. Зарегистрированный Converter или DICOM плагины с недостаточной non‑temporary лицензией терпят неудачу во время AddDoconut(). Сравните IsCapabilityGranted(...) со всеми функциями, которые вы включаете перед развертыванием.

Поиск ничего не находит (или слишком мало)

  • Для прямого PDF, AllowSearch не был включён во время открытия. Word, Excel и PowerPoint предоставляют тот же переключатель через их вложенный PdfConfig.
  • Содержимое отсканировано/только изображение, поэтому обычный Search не имеет текстового слоя для сопоставления. Используйте источник с текстом или проекцию PDF, сохраняющую текст.
  • HTML и MS Project (MPP) по умолчанию не поддаются поиску — установите DefaultRender = false, чтобы они рендерились через проекцию PDF с нативным текстовым слоем. Поиск в Word, Excel, PowerPoint, TXT, Visio, email, EPUB и MHT работает по их каталоговым настройкам по умолчанию.
  • objViewer.CanSearch() является false после инициализации — разрешённый формат не имеет стандартного пути поиска. Это заключение отдельно от лицензии Search; проверьте оба.
  • Страница считывает возвращаемое значение objViewer.Search(...) — счёт приходит в его третий аргумент, обратный вызов.

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

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

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