Rendering Pipeline

Between OpenDocumentAsync and the PNG that reaches the browser there are two distinct stages: viewer resolution (which engine loads the document, decided once per open) and page processing (what happens to each page image on every request to DocImage.axd). Knowing both explains why a format renders the way it does — and what DefaultRender really switches.

Stage 1 — Resolving the format viewer

The factory maps the file extension to a viewer through the format catalog, with three levels of precedence:

1. Custom viewers first. Anything you registered with DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) wins over every built-in.
2. Built-in family viewers. The catalog maps each viewable extension to a viewer family — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — each with its own engine adapter. If a licensed plugin contributes a viewer for the same extension, the plugin's viewer replaces the built-in one.
3. Plugin-only formats. Some extensions have no built-in viewer at all — DICOM (.dcm, .ima) exists only through the DICOM plugin. Opening one without the required capability throws:

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

An extension that no viewer claims raises FormatNotSupportedException.

After resolution, the config is settled: your explicit config object if you passed one, otherwise the format's default config from the catalog. DocOptions.Password is copied into the config for protected documents.

Stage 1b — Redirect mode (DefaultRender = false)

Most per-format configs expose a DefaultRender flag. It selects between two fundamentally different paths:

• DefaultRender = true — the document renders natively, straight to page images.
• DefaultRender = false — the document is first converted to a PDF in memory, the source engine is released, and a PDF viewer takes over. The generated PDF carries real text, so full-text search gets exact native highlights; the pipeline turns AllowSearch and AllowCopy on for the redirected PDF, since the conversion is invisible to the user.

XPS, and MHT by default, use the redirect path. A PDF projection gives native search to formats such as HTML and Microsoft Project. If the resulting PDF contains images without a text layer, those pixels cannot be searched.

Use redirect mode when you need a searchable, text-bearing projection — at the cost of an upfront conversion when the document opens.

Stage 2 — The page-image pipeline

Each page request to DocImage.axd runs a fixed sequence:

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

• Watermark — applied from the license state (no license, an expired temporary or subscription license, an invalid domain, a build outside the license's versions) and from DocOptions.Watermark for your own text. A licensed site with no custom watermark skips this step.
• Rotate/flip — per-page state the user sets in the widget (90°/180°/270°, horizontal and vertical flips) is stored in the session and applied to every later render of that page.
• Scale — thumbnails and zoom levels are produced by scaling the rendered page to the requested size.
• Annotation burn — saved annotations are drawn onto the bitmap, so exports and page images show them.
• Encoding — the result is encoded as PNG and written directly to the response.

Errors inside the handler are returned as PNG error images (red text on white) with status 200, rather than as HTTP error pages, so the widget can display them in the page area.

Page caching

BaseConfig.CachePages (default true) keeps rendered page images in memory for the lifetime of the document session, so revisiting a page does not render it again. BaseConfig.ImageResolution (25–300 DPI, 0 = the format's default) is the main quality and memory dial; each format's default is listed in Format Configs.

On a single node, sessions and cached pages live in the worker process's memory. An application pool recycle — scheduled, or triggered by a Web.config edit or an idle timeout — drops every open document session, and the widget then shows Document session not found. Please re-open document. In distributed mode (see Sessions & Security), a session is rebuilt from the shared store instead.

Where to tune what