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

Между OpenDocumentAsync и PNG, который попадает в браузер, есть два отдельных этапа: определение просмотрщика (какой движок загружает документ, решается один раз при открытии) и обработка страниц (что происходит с каждым изображением страницы при каждом запросе). Понимание обоих объясняет, почему формат рендерится определённым образом — и что на самом деле переключает 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 — каждый со своим адаптером движка. Если лицензированный плагин предоставляет просмотрщик для того же расширения, просмотрщик плагина заменяет встроенный. AddDoconut() проверяет права зарегистрированных плагинов при запуске; резервный переход фабрики к встроенному просмотрщику является защитным правилом выполнения.
3. Форматы только через плагины. Некоторые расширения не имеют встроенного просмотрщика вовсе — DICOM (.dcm) существует только через плагин DICOM. Открытие такого без необходимой возможности вызывает:

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

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

FormatNotSupportedException: Document format '<extension>' is not supported.

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

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

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

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

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

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

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

Отрисованные страницы обрабатываются при каждом запросе по фиксированной последовательности:

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

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

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

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

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

Где настраивать что