Устранение неполадок
Диагностика распространённых ошибок
Ниже приведены буквальные сообщения 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 с:
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 сеанса не достигает запросов страницы (настройка кросс‑origin, политика SameSite, API‑клиент без cookie‑хранилища) или приложение перезапущено (новые ключи сеанса). Это работа слоя безопасности согласно проекту — см. Core Concepts → Sessions & Security. Отказ представляет собой изображение, отданное со статусом 200, поэтому монитор, проверяющий только коды статусов, считает его страницей.
Изображение ошибки с надписью:
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). Плагин зарегистрирован, но лицензия больше не предоставляет ему возможности — обычно это временная лицензия, истёкшая после запуска приложения. Установите лицензию, предоставляющую эту возможность, и проверьте IsCapabilityGranted(LicenseCapability.Dicom) на IDoconutLicenseService. Отсутствующее или недостаточное постоянное право обычно приводит к ошибке раньше, во время 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.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. Добавьте один раз при запуске:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Неправильные или заменённые шрифты — серверу не хватает шрифтов документа. Установите их или укажите FontFolders (на WordConfig/PptConfig) на папку, содержащую их. На Linux смотрите ниже.
Аннотация изображения отображается в просмотрщике, но экспорт содержит окно «Изображение заблокировано» — хост изображения имеет частный или адрес обратной связи, который сервер отказывается получать. Смотрите Аннотации.
Linux
Открытие любого документа завершается ошибкой:
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). Смотрите Установка.
Открытие любого документа завершается ошибкой:
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.
Открытие любого документа завершается ошибкой:
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 и выводом диагностики лицензии.
Была ли эта страница полезной?