Устранение неполадок – Doconut Документация

Многие сбои System.Web не вызывают видимых исключений: страница отвечает пустым 500, иконка возвращает 404, или запрос никогда не завершается. Эта страница организована по тому, что вы наблюдаете. Цитируемые сообщения — это буквальный текст, который генерирует Doconut.

Симптомы в обзоре

Что вы видите	Наиболее вероятная причина	Исправление
Каждый запрос отвечает пустым `500`	Исключение в `Application_Start`: плагин без лицензии, недопустимая опция, неполная конфигурация фермы — или перенаправление привязки, указывающее версию, которой нет в `bin\`	Журнал событий Windows, Приложение, источник ASP.NET. См. Сбои при запуске
Некоторые MVC‑страницы отвечают пустым `500`	Razor компилирует представления во время выполнения: фасад `netstandard` отсутствует в `<compilation>`, или представление использует C# новее 5 (`?.`, `$"..."`, `nameof`)	Добавьте фасад (Установка); перенесите логику из представления в контроллер
Страницы показывают `â€”`, `â€¦` или похожие символы вместо тире и акцентов	Файлы страниц без маркера порядка байтов читаются с ANSI‑кодировкой сервера	`<globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />`
Консоль браузера показывает `404` для `HEAD /DocImage.axd?...&page=1`	Обработчик зарегистрирован без глагола `HEAD`	`verb="GET,HEAD,POST"` в обработчике
Документ отображается, но значки панели инструментов и индикатор загрузки отсутствуют	`ResPath` указывает на корень ресурсов, либо начинается с `/`	`ResPath: 'doconut-res/images'`
Запросы `/doconut-res/...` отвечают `404`	Модуль ресурсов не зарегистрирован, `runAllManagedModulesForAllRequests` выключен, или маршрутизация MVC перехватывает путь	Запись `<modules>` и `routes.IgnoreRoute("doconut-res/{*pathInfo}")`
Просмотрщик сообщает `The viewer handler could not be reached (no response).`	`BasePath` начинается с `/` (`'/myapp'` становится `//myapp/…`, другой хост)	`BasePath: '/'` в корне сайта; `'myapp'` в виртуальном каталоге
Просмотрщик сообщает `Please make sure your middleware is configured.`	`DocImage.axd` ответил `404`: обработчик отсутствует в `Web.config`, маршрутизация MVC перехватила его, или `BasePath` указывает в другое место	Запись `<handlers>`, `routes.IgnoreRoute("{resource}.axd/{*pathInfo}")` и `BasePath`
Каждая страница показывает `You Are Not Authorized To View This Page.`	Документ был открыт в запросе без состояния сессии, состояние сессии отключено, или cookie сессии не достигает `DocImage.axd`	См. Не авторизовано
Конверсия Web Forms никогда не возвращается	Страница блокируется на `ConvertAsync` — взаимная блокировка	`Async="true"` + `RegisterAsyncTask` (Плагин конвертера)
Каждая страница содержит водяной знак оценки	Лицензия не найдена — её нет в `<site root>\wwwroot`	Настройка лицензии
Виджет загружается, но его первое действие отвечает `404`	Виджет не включён, или его `basePath` не является `'/DocImage.axd'`	`options.Add…Widget()`, и `basePath: '/DocImage.axd'`
Первый документ после запуска или рециркуляции сайта открывается минуту и более; последующие открываются быстро	Движки документов загружаются при первом открытии, а антивирус в реальном времени сканирует их при загрузке	Разогрейте сайт и держите пул запущенным — см. Первый документ после запуска
При большой загрузке отображается страница ошибки IIS	Загрузка превышает `maxRequestLength` (KB) или `maxAllowedContentLength` (байт)	Увеличьте оба значения выше вашего максимального файла или лимита виджета

Сбои при запуске

Исключение, выброшенное в Application_Start, не доходит до браузера: каждый запрос отвечает пустым 500, а журнал IIS не содержит полезной информации. Исключение находится в журнале событий Windows (Просмотр событий → Журналы Windows → Приложение, источник ASP.NET). Обычные:

Плагин без лицензии:

text

The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

Doconut.Viewer.<Capability>.lic плагина должен находиться в wwwroot, рядом с Doconut.Viewer.lic. Отсутствующая лицензия и устаревший файл TRIAL не предоставляют возможностей плагина.

Недопустимые опции:

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.

Сборка, которую нельзя загрузить.

ASP.NET загружает каждую сборку в bin\ при запуске приложения, поэтому перенаправление привязки в Web.config, указывающее версию, отсутствующую в bin\, останавливает весь сайт. Скопируйте перенаправления, сгенерированные NuGet (для проекта в стиле SDK, из bin\<YourApp>.dll.config), вместо редактирования их вручную, и скопируйте их снова после обновления пакетов.

Вы не авторизованы для просмотра этой страницы.

Страница отклонена, потому что запрашиваемая ASP.NET‑сессия никогда не получала документ. Проверьте в следующем порядке:

Открытие выполняется с состоянием сессии. MVC‑контроллеры и страницы Web Forms имеют его. Пользовательский IHttpHandler, который открывает документы, должен реализовывать System.Web.SessionState.IRequiresSessionState, иначе у него нет сессии для предоставления.
Состояние сессии включено. <sessionState mode="Off" /> отклоняет каждую страницу.
Кука достигает обработчика. Запросы виджета того же происхождения несут ASP.NET_SessionId; скрипт, вызов сервер‑к‑серверу или кросс‑origin страница без кук этого не делает.
Web‑farm: открытие связывает браузер (DocOptions.BrowserId) и страница передаёт билет (objViewer.View(token, access)); каждый узел использует один и тот же ключ подписи.

Отказ представляет собой изображение, отданное со статусом 200, размером около 2 КБ. Монитор, проверяющий только коды статусов, считает его страницей.

Сессия документа не найдена. Пожалуйста, откройте документ заново.

Токен истёк (скользящее окно, DocOptions.TimeOut, по умолчанию 60 минут), документ был закрыт, либо — на единственном сервере — пул приложений был перезапущен. Перезапуск происходит по расписанию, при каждом редактировании Web.config и после простоя пула (по умолчанию 20 минут в IIS). Откройте документ снова, чтобы получить новый токен.

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

LicenseException с причиной отклонения — файл лицензии найден, но отклонён (недействительная подпись, вмешательство, черный список или сборка вне окна версии лицензии). Открытие блокируется, а не помечается водяным знаком.

LicenseException:

text

This document type requires the 'Dicom' plugin license.

Расширение обрабатывается только плагином (здесь DICOM), чья возможность не предоставлена.

FormatNotSupportedException — ни один просмотрщик (встроенный, плагин или пользовательский) не поддерживает это расширение. DoconutOptions.RegisterViewer может добавить его для ваших собственных форматов.

InvalidDataException — содержимое повреждено или не соответствует расширению (переименованный файл). Проверяйте загружаемые файлы перед открытием.

InvalidOperationException:

text

No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

DocumentConverter был разрешён без регистрации плагина Converter.

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

Страницы содержат водяной знак — лицензия не найдена, либо истекла, либо не покрывает эту версию. В IIS лицензия должна находиться в wwwroot под корнем сайта (AppContext.BaseDirectory\wwwroot), а не в bin\. Проверьте IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, License.RejectionMessage).

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

csharp

// Global.asax.cs, Application_Start - перед DoconutHost.Initialize.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Неправильные или заменённые шрифты — на сервере отсутствуют шрифты документа. Windows Server без Office имеет гораздо меньше шрифтов, чем рабочая машина. Установите шрифты или укажите FontFolders (на WordConfig и PptConfig) на папку, где они находятся.

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

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

Активная временная лицензия предоставляет все возможности; ваша приобретённая лицензия предоставляет только то, что вы купили. Без возможности её файлы поиска или аннотации не генерируются, и зарегистрированный плагин останавливает сайт при запуске. Сравните IsCapabilityGranted(...) со всеми функциями, которые вы используете, перед развертыванием.

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

Для PDF AllowSearch не был включён при открытии документа — по умолчанию используется false. Word, Excel и PowerPoint предоставляют тот же переключатель.
Содержимое отсканировано или только изображение, поэтому нет текстового слоя для сопоставления.
HTML и Microsoft Project (MPP) по умолчанию не поддаются поиску: установите DefaultRender = false, чтобы они рендерились через PDF‑проекцию с текстом.
objViewer.CanSearch() является false после инициализации: разрешённый формат не имеет пути поиска. Это отдельно от лицензии Search; проверьте оба.
Страница читает возвращаемое значение objViewer.Search(...) — количество приходит в третьем аргументе, в колбэке.

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

Воспроизведите проблему с минимальной конфигурацией из Быстрый старт. Если она воспроизводится там, свяжитесь со службой поддержки, предоставив документ, ваш Global.asax.cs, части Doconut из Web.config и запись журнала событий Windows, если она есть.