Performance Tuning

Optimize rendering and memory

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.

csharp
// 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.
csharp
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:
csharp
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/PPT on Linux/Docker: missing fonts cause slow fallback probing and wrong metrics; point FontFolders at a directory with your fonts.
  • Presentations on Linux/macOS: PPT/PPTX/PPS/POT/ODP files can open, but rendering with the current presentation engine requires native libgdiplus and the runtime switch System.Drawing.EnableUnixSupport=true. Other format families use the normal cross-platform rendering path.

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 Program.cs — registering encodings per request is wasted work; forgetting it entirely breaks legacy code-page documents.

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.

Was this page helpful?