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

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

Ниже перечислены буквальные сообщения 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.

Startup fails

InvalidOperationException упоминает плагин, зарегистрированный через AddPlugin — текущая не‑временная лицензия не предоставляет эту возможность плагина. Удалите регистрацию или установите лицензию, предоставляющую её. Отсутствующая лицензия и устаревший файл TRIAL не предоставляют возможностей плагина.

ArgumentException from 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 как указано в пакете).

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

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

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

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

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

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.

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

Классический сюрприз при запуске: активная временная лицензия предоставляет все возможности; ваша приобретённая лицензия предоставляет только то, что вы купили. Пакеты поиска и аннотаций могут исчезать, когда их возможности отсутствуют. Зарегистрированный 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; проверьте оба.
  • Страница считывает возвращаемое значение objViewer.Search(...) — количество приходит в третьем аргументе, в виде обратного вызова.

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

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

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