Table of Contents

Introduction

CobaltPdf is a .NET library (8.0+) for generating PDF documents from HTML. It drives a real Chromium browser under the hood — the same engine used by Google Chrome — so every page you render produces an exact, pixel-perfect replica of what a user would see in their browser, including CSS, web fonts, JavaScript-rendered content, and complex layouts.

How It Works

Your code                  CobaltPdf                       Chromium
─────────────────────────────────────────────────────────────────────
renderer.Landscape()   ─►  Store option
.AddCookie(…)          ─►  Store option
.RenderUrlAsPdfAsync() ─►  Acquire browser from pool ─►  Navigate to URL
                           Inject cookies                  Apply cookies
                           Wait for ready signal           Execute JS
                                                           Capture PDF
                       ◄─  Return PdfDocument     ◄─  Return bytes
                           Return browser to pool

Browser Pool

CobaltPdf maintains a pool of Chromium processes that are launched once at startup and kept alive between requests. When a render is requested, a browser instance is leased from the pool, used in its own isolated browser context (so cookies and storage from one render never bleed into another), and then returned. This eliminates the multi-second Chromium startup cost that plagues naive implementations.

Pool behaviour is controlled by PoolOptions:

Option Default Description
MinSize 1 Browsers kept warm at all times
MaxSize 5 Maximum concurrent renders
MaxUsesPerBrowser 100 Recycle a browser after N renders
BrowserLeaseTimeout 30 s How long a request waits for a free browser before throwing

Isolated Contexts

Every render runs in a fresh IBrowserContext. This means:

  • Cookies set for render A are invisible to render B running in parallel.
  • localStorage and sessionStorage are empty at the start of every render.
  • Custom JavaScript cannot accidentally leak state between requests.

Key Design Principles

Fluent and minimal. The API is intentionally concise. Options are set by chaining methods on CobaltEngine and the chain is consumed by the terminal call (RenderUrlAsPdfAsync / RenderHtmlAsPdfAsync). After the terminal call the engine resets — so the same CobaltEngine instance can be injected as a singleton and called from multiple threads safely.

Fail loudly. Where an option cannot be honoured (e.g. the signal timeout fires before window.cobaltNotifyRender() is called, or a CSS selector never appears) a descriptive TimeoutException is thrown rather than silently rendering a partial or empty page.

No magic files. No temp files are written unless you explicitly call pdf.SaveAs(path). pdf.BinaryData gives you the raw bytes to attach to an email, stream to a client, upload to blob storage, etc.

Requirements

  • .NET 8 or later — Windows x64 or Linux x64
  • No separate Chromium installation required — the browser ships as a NuGet dependency. See Chromium Setup.

Licensing

A free trial (output is watermarked) is available with no time limit. A licence key removes the watermark and is required for production use. See Pricing and Licensing for details.