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

Между OpenDocumentAsync и PNG, который попадает в браузер, существуют два отдельных этапа: viewer resolution (какой движок загружает документ, определяется один раз при открытии) и page processing (что происходит с каждым изображением страницы при каждом запросе). Понимание обоих объясняет, почему формат отображается так, как он отображается — и что на самом деле переключает 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

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

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

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

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

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