Конвейер рендеринга

Между OpenDocumentAsync и PNG, который попадает в браузер, существуют два отдельных этапа: определение просмотрщика (какой движок загружает документ, решается один раз при открытии) и обработка страниц (что происходит с каждым изображением страницы при каждом запросе к DocImage.axd). Понимание обоих объясняет, почему формат рендерится определённым образом — и что действительно переключает DefaultRender.

Этап 1 — Определение просмотрщика формата

Фабрика сопоставляет расширение файла просмотрщику через каталог форматов, используя три уровня приоритета:

1. Сначала пользовательские просмотрщики. Всё, что вы зарегистрировали с помощью DoconutOptions.RegisterViewer(extension, factory, defaultConfig?), имеет приоритет над всеми встроенными.
2. Встроенные семейные просмотрщики. Каталог сопоставляет каждое расширение, которое можно просматривать, семейству просмотрщиков — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — каждый со своим адаптером движка. Если лицензированный плагин предоставляет просмотрщик для того же расширения, просмотрщик плагина заменяет встроенный.
3. Форматы только через плагины. Некоторые расширения не имеют встроенного просмотрщика — DICOM (.dcm, .ima) существует только через плагин DICOM. Открытие такого файла без необходимой возможности приводит к ошибке:

LicenseException: This document type requires the 'Dicom' plugin license.

Если ни один просмотрщик не поддерживает расширение, возникает FormatNotSupportedException.

После определения конфигурация фиксируется: ваш явный объект конфигурации, если вы его передали, иначе конфигурация по умолчанию для формата из каталога. DocOptions.Password копируется в конфигурацию для защищённых документов.

Этап 1b — Режим перенаправления (DefaultRender = false)

Большинство конфигураций для форматов раскрывают флаг DefaultRender. Он выбирает один из двух принципиально разных путей:

• DefaultRender = true — документ рендерится нативно, напрямую в изображения страниц.
• DefaultRender = false — документ сначала конвертируется в PDF в памяти, исходный движок освобождается, и управление переходит к PDF‑просмотрщику. Сгенерированный PDF содержит реальный текст, поэтому полнотекстовый поиск получает точные нативные подсветки; конвейер включает AllowSearch и AllowCopy для перенаправленного PDF, поскольку конверсия невидима для пользователя.

По умолчанию XPS и MHT используют путь перенаправления. Проекция в PDF обеспечивает нативный поиск для форматов, таких как HTML и Microsoft Project. Если полученный PDF содержит изображения без текстового слоя, эти пиксели нельзя искать.

Используйте режим перенаправления, когда вам нужна проекция с возможностью поиска текста — ценой предварительной конвертации при открытии документа.

Этап 2 — Конвейер изображений страниц

Каждый запрос страницы к DocImage.axd выполняет фиксированную последовательность:

raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response

• Водяной знак — применяется в зависимости от состояния лицензии (отсутствие лицензии, истёкшая временная или подписочная лицензия, недействительный домен, сборка вне версий лицензии) и из DocOptions.Watermark для вашего собственного текста. Лицензированный сайт без пользовательского водяного знака пропускает этот шаг.
• Поворот/отражение — состояние каждой страницы, которое пользователь задаёт в виджете (90°/180°/270°, горизонтальное и вертикальное отражения), сохраняется в сессии и применяется к каждому последующему рендеру этой страницы.
• Масштабирование — миниатюры и уровни зума создаются путём масштабирования отрендеренной страницы до запрошенного размера.
• Наложение аннотаций — сохранённые аннотации рисуются на битмапе, поэтому экспорты и изображения страниц отображают их.
• Кодирование — результат кодируется как PNG и записывается непосредственно в ответ.

Ошибки внутри обработчика возвращаются как PNG‑изображения ошибок (красный текст на белом фоне) со статусом 200, а не как HTTP‑страницы ошибок, чтобы виджет мог отобразить их в области страницы.

Кеширование страниц

BaseConfig.CachePages (по умолчанию true) хранит отрендеренные изображения страниц в памяти на протяжении всей сессии документа, поэтому повторный переход к странице не приводит к её повторному рендерингу. BaseConfig.ImageResolution (25–300 DPI, 0 = значение по умолчанию для формата) является основным параметром качества и памяти; значение по умолчанию для каждого формата указано в Конфиги форматов.

На отдельном узле сессии и кешированные страницы находятся в памяти рабочего процесса. Перезапуск пула приложений — запланированный или вызванный изменением Web.config или тайм‑аутом простоя — удаляет все открытые сессии документов, и виджет затем показывает Document session not found. Please re-open document. В распределённом режиме (см. Сессии и безопасность) сессия восстанавливается из общего хранилища.

Где и как настраивать