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

Между 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 = значение по умолчанию формата) является основным регулятором качества/памяти; значение по умолчанию для каждого формата задокументировано на его странице конфигурации.

DocOptions.ImageResolution устарел и не управляет качеством рендеринга. Если вы переносите приложение с предыдущей библиотеки, перенесите это значение в конфигурацию формата — компилятор укажет на каждое место вызова.

Рендеринг на одном узле vs. многих

Всё выше описывает рендеринг на одном узле по запросу для сессии, которая открыла документ. При развертывании, где один узел рендерит и публикует весь набор артефактов, а другие узлы обслуживают эти страницы из общего хранилища, используется иной путь чтения — см. Распределённые развертывания.

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