Getting Started

1. Install

dotnet add package CobaltPdf

Tip

A free trial licence is included automatically — output will carry a small watermark until you activate a paid licence key. See Licensing.

2. Configure the Pool (once at startup)

Call CobaltEngine.Configure once before any renders. This must be called before the first render; it cannot be called after the pool has started.

Windows (local development)

using CobaltPdf;

CobaltEngine.Configure(options =>
{
    options.MinSize = 2;
    options.MaxSize = Math.Max(2, Environment.ProcessorCount);
});

Linux / Docker / Cloud

Use a CloudEnvironment preset — it applies the correct Chromium flags and pool sizing for your environment:

using CobaltPdf;
using CobaltPdf.Configuration;

// Docker
CobaltEngine.Configure(CloudEnvironment.ConfigureForDocker);

// Azure App Service or Functions Premium Plan
CobaltEngine.Configure(CloudEnvironment.ConfigureForAzure);

// AWS ECS / Fargate
CobaltEngine.Configure(CloudEnvironment.ConfigureForAwsEcs);

// Memory-constrained (single browser, --single-process)
CobaltEngine.Configure(CloudEnvironment.ConfigureForLowMemory);

You can also override specific settings after applying a preset:

CobaltEngine.Configure(o =>
{
    CloudEnvironment.ConfigureForDocker(o);
    o.MaxSize = 4; // more concurrent renders if your container has the RAM
});

See Configuration for the full PoolOptions reference and preset summary.

Tip

Call await CobaltEngine.PreWarmAsync() immediately after Configure to launch the minimum browsers at startup rather than on the first request.

3. Render Your First PDF

var renderer = new CobaltEngine();

// From a URL
var pdf = await renderer.RenderUrlAsPdfAsync("https://example.com");
pdf.SaveAs("example.pdf");
Console.WriteLine($"Saved {pdf.Length} bytes");

// From an HTML string (returned in memory — no file written)
var pdf2 = await renderer.RenderHtmlAsPdfAsync("""
    <html>
    <body style="font-family: sans-serif; padding: 40px;">
        <h1>Invoice #1042</h1>
        <p>Total due: <strong>£149.99</strong></p>
    </body>
    </html>
    """);
Console.WriteLine($"{pdf2.Length} bytes in memory");

// From an HTML file on disk
var pdf3 = await renderer.RenderHtmlFileAsPdfAsync("report.html");
pdf3.SaveAs("report.pdf");

4. Shutdown Gracefully

When your application exits, release Chromium processes:

await CobaltEngine.ShutdownAsync();

In an ASP.NET Core app use the application lifetime hook — see Dependency Injection.

Complete Console Example

using CobaltPdf;
using CobaltPdf.Configuration;

// ── Startup ──────────────────────────────────────────────────────────────
CobaltEngine.LoggingMode = BrowserLoggingMode.Console;

// Use the Docker preset (or ConfigureForLinux / ConfigureForAzure / etc.)
CobaltEngine.Configure(o =>
{
    CloudEnvironment.ConfigureForDocker(o);
    o.MinSize = 2;
});

await CobaltEngine.PreWarmAsync();

// ── Render ───────────────────────────────────────────────────────────────
var renderer = new CobaltEngine();

var pdf = await renderer
    .Landscape()
    .WithHeader("<div style='font-size:10px;text-align:center;width:100%'>My Report</div>")
    .WithFooter("<div style='font-size:10px;text-align:center;width:100%'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>")
    .RenderUrlAsPdfAsync("https://example.com");

pdf.SaveAs("report.pdf");
Console.WriteLine($"Done — {pdf.Length} bytes");

// ── Shutdown ─────────────────────────────────────────────────────────────
await CobaltEngine.ShutdownAsync();

Table of Contents