Performance Tuning

Doconut's resource profile is dominated by three things: render DPI, what stays cached, and how long sessions live. This guide walks the levers in order of impact.

Resolution — the biggest lever

ImageResolution (25–300 DPI) drives both render time and image size. Most formats default to 200 DPI; images and PSD default to 100.

// A document list preview doesn't need print quality
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { ImageResolution = 100 });

Halving DPI roughly quarters the pixel count per page — faster renders, smaller transfers, less cache memory. Reserve 250–300 DPI for zoom-heavy use cases (CAD, engineering drawings).

For PDFs with heavy embedded imagery, PdfConfig adds finer dials: CompressImages + CompressQuality, ResizeImages + ResizeResolution, and CompressFast. For plain images, ImageConfig.MaxImagePixelSize (default 3000 px) caps output size.

Page caching — memory vs. re-render

BaseConfig.CachePages (default true) keeps every rendered page in memory for the session's lifetime. That's the right default for interactive viewing — users scroll back and forth. Turn it off when:

• documents are huge and viewed once, front to back,
• many concurrent sessions would multiply the cached pages,
• you'd rather pay CPU per view than hold RAM.

var token = await viewer.OpenDocumentAsync(path, new PdfConfig { CachePages = false });

On the client, ViewerConfig.CacheEnabled = true preloads a small moving window of upcoming page images in browser memory. It is a per-view prefetch cache, not persistent localStorage.

Sessions — the memory you don't see

Every open session holds the parsed document model plus (with CachePages) its rendered pages, until the sliding TimeOut (default 60 minutes) elapses since the last request. Two habits keep this under control:

• Close what you're done with. viewer.CloseDocument(token) frees the engine immediately instead of waiting out the idle window.
• Right-size the timeout. A preview that users glance at for two minutes doesn't need a one-hour session:

var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

Remember the trade-off: after expiry the widget shows Document session not found. Please re-open document. — pick a timeout that matches real reading sessions.

Format-specific switches

• Excel: MemoryOptimizationPreference is on by default and reduces the memory footprint when rendering very large workbooks — leave it on, or set it to false if you'd trade memory for a small speed gain; SheetNames / PrintArea restrict rendering to what matters.
• Redirect mode has an upfront cost: DefaultRender = false converts the entire document to PDF at open time. It buys native text-based search, but on a 500-page document the open call carries that conversion — don't enable it reflexively.
• Word/PowerPoint on a server without the documents' fonts: a Windows Server without Office has far fewer fonts than a development machine. Missing fonts cause slow fallback probing and wrong metrics; install the fonts, or point FontFolders at a folder that holds them.

Client-side strategies

• LargeDoc = true — lazy-load strategy for very large documents; pages load as the user approaches them.
• AutoLoad = false (default) — don't render until you actually call View(token).
• ShowThumbs = false — skip thumbnail generation/requests for single-page or embedded previews.
• Enabling FixedZoom avoids free-form zoom changes; when you map a C# ViewerConfig, tune FixedZoomPercentMobile (C# default 75) for small screens.

Startup once, not per request

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance) belongs in Application_Start, next to DoconutHost.Initialize — registering encodings per request is wasted work; forgetting it entirely breaks legacy code-page documents.

The first document after a start

Doconut loads its document engines the first time a document is opened in an application — after the pool starts, after every recycle, and in every new application domain. That first open is slower than the ones after it, and real-time antivirus can make it much slower: the engines are loaded from memory, and Microsoft Defender scans that code as it loads. A folder exclusion does not help, because no file is involved.

Measured on a 4-core Windows Server 2022 machine, opening a two-page Word document:

Pay it once, before your users do:

• Keep the worker process alive: set the application pool's Start Mode to AlwaysRunning, and raise or disable its idle time-out, so a quiet night does not unload the engines.
• Warm it up on start: enable IIS Application Initialization (preloadEnabled="true" on the site) and point its initializationPage at a page of yours that opens a small document. The first real user then finds the engines already loaded.
• Give the first request time: a load balancer health check or an upstream proxy with a short timeout can give up on a cold start that would have succeeded.

Whether to change antivirus settings on a server is your security team's decision; the warm-up above works without it.

The application pool

On a single server, document sessions and cached pages live in the worker process. Every application pool recycle — the scheduled one, an edit to Web.config, or the pool's idle time-out (20 minutes by default in IIS) — drops them all, and open viewers then show Document session not found. Please re-open document.

• Align the pool's idle time-out and recycling schedule with how long your users actually read, or be ready to re-open documents after a recycle.
• Run the pool as a 64-bit process (leave Enable 32-Bit Applications off). Large documents need the address space a 32-bit worker process does not have.
• A web farm keeps sessions in a shared store, so a recycle on one node does not lose them — see Sessions & Security.

A tuning checklist

1. Set the lowest ImageResolution your UX accepts.
2. Keep CachePages on for interactive viewing; off for one-pass or high-concurrency scenarios.
3. Close sessions explicitly; shorten TimeOut where usage is bursty.
4. Use LargeDoc + default AutoLoad = false on the client for big documents.
5. Use DefaultRender = false only when you need a text-bearing PDF projection.