CobaltPDF 1.2.2

CobaltPDF

CobaltPDF is a high-performance .NET library that converts HTML pages and strings into pixel-perfect PDFs using a managed Chromium browser pool.

Features

• 🚀 Browser pooling — Chromium instances kept warm between requests; no per-request startup cost (<75 ms warm renders)
• ✍️ Fluent API — chain options naturally: renderer.WithLandscape().AddCookie(…).RenderUrlAsPdfAsync(…)
• ⏳ Wait strategies — network idle, CSS selector, JavaScript expression, fixed delay, or manual cobaltNotifyRender() signal
• 🍪 Cookie & storage injection — set cookies, localStorage, and sessionStorage before navigation
• 🖋️ Custom JavaScript — execute arbitrary JS before capture to manipulate the DOM or set application state
• 🔤 Fonts — load .ttf, .otf, .woff, .woff2 files from a local directory automatically
• 📄 Headers, footers & watermarks — full HTML templates with pageNumber/totalPages tokens and pre-styled watermark presets
• 🔒 Encryption — AES 128-bit with user + owner passwords and print/copy/modify permissions
• 📋 Metadata — title, author, subject, keywords, creator embedded in the PDF
• 🔄 Lazy loading — scroll N viewport-heights before capture to trigger IntersectionObserver-based content
• 💉 DI support — services.AddCobaltPdf(…) for ASP.NET Core / generic host with singleton lifecycle
• ☁️ Cloud-ready — built-in presets for Docker, Azure App Service, Azure Functions, AWS ECS/Fargate, and Lambda
• 📡 Microservice mode — companion CobaltPDF.Requests package lets any client (C#, TypeScript, Python) send JSON payloads without installing Chromium

Quick start

dotnet add package CobaltPDF

using CobaltPdf;

// Activate your licence (once at startup)
CobaltEngine.SetLicense("COBALTPDF-AcmeCorp-XXXXX-Annual-2026-06-15");

// Render a URL to PDF
var renderer = new CobaltEngine();
var pdf = await renderer.RenderUrlAsPdfAsync("https://example.com");
pdf.SaveAs("output.pdf");

// Render an HTML string
var pdf2 = await renderer.RenderHtmlAsPdfAsync("<h1>Hello, World!</h1>");
Console.WriteLine($"{pdf2.Length} bytes");

Tip: Store your licence key in appsettings.json, environment variables, or user secrets — never hard-code it in source control.

Fluent API

Every option chains. Every method has a sensible default.

var pdf = await new CobaltEngine()
    .WithLandscape()
    .WithPaperFormat("A3")
    .WithMargins(top: "20mm", right: "15mm", bottom: "20mm", left: "15mm")
    .WithPrintBackground()
    .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>")
    .AddCookie("session", "abc123")
    .WithHttpHeader("Authorization", $"Bearer {accessToken}")
    .WithWaitStrategy(WaitOptions.DefaultNetworkIdle)
    .RenderUrlAsPdfAsync("https://example.com/report");

pdf.SaveAs("report.pdf");

Highlights

// Wait for a CSS selector to appear
.WithWaitStrategy(WaitOptions.ForSelector("#chart-container svg"))

// Wait for a JS expression to become truthy
.WithWaitStrategy(WaitOptions.ForJavaScript("window.dataLoaded === true"))

// Wait for the page to call cobaltNotifyRender()
.WithWaitStrategy(WaitOptions.ForSignal())

// Scroll to trigger lazy-loaded images
.WithLazyLoadPages(10)

// Execute JS before capture
.WithCustomJS("document.querySelector('nav').style.display = 'none';")

// Pre-styled watermarks
.WithWatermark(WatermarkOptions.WithText("DRAFT", WatermarkStyle.RedDraft))

// Password protection
.WithEncryption(new PdfEncryptionOptions
{
    UserPassword = "viewer-pass",
    OwnerPassword = "admin-secret",
    AllowPrinting = true,
    AllowCopying = false
})

// PDF metadata
.WithMetadata(m => {
    m.Title  = "Q4 Financial Report";
    m.Author = "Finance Team";
})

ASP.NET Core integration

// Program.cs
CobaltEngine.SetLicense(builder.Configuration["CobaltPdf:LicenseKey"]!);

builder.Services.AddCobaltPdf(options =>
{
    options.MaxSize = Environment.ProcessorCount;
    CloudEnvironment.ConfigureForDocker(options);
});

var app = builder.Build();

// Pre-warm the browser pool at startup (eliminates first-request latency)
await app.Services.GetRequiredService<CobaltEngine>().PreWarmAsync();

// Controller or service — inject CobaltEngine as a singleton
public class ReportController(CobaltEngine renderer) : ControllerBase
{
    [HttpGet("export")]
    public async Task<IActionResult> Export(CancellationToken ct)
    {
        var pdf = await renderer
            .WithPaperFormat("A4")
            .WithPrintBackground()
            .RenderUrlAsPdfAsync("https://app.example.com/report", ct);

        return File(pdf.BinaryData, "application/pdf", "report.pdf");
    }
}

Cloud deployments

Use the built-in CloudEnvironment presets instead of configuring Chromium flags manually:

// Docker / Azure Container Apps
builder.Services.AddCobaltPdf(CloudEnvironment.ConfigureForDocker);

// Azure App Service / Azure Functions (Premium Plan)
builder.Services.AddCobaltPdf(CloudEnvironment.ConfigureForAzure);

// AWS ECS / Fargate
builder.Services.AddCobaltPdf(CloudEnvironment.ConfigureForAwsEcs);

// Memory-constrained (AWS Lambda, small containers)
builder.Services.AddCobaltPdf(CloudEnvironment.ConfigureForLowMemory);

See the Deployment guide for full platform walkthroughs.

Microservice mode

Deploy CobaltPDF as a standalone PDF rendering service and call it from any application. Install the lightweight CobaltPDF.Requests package (~50 KB) on the client — no Chromium required.

[Client Application]                        [PDF Rendering Service]
CobaltPDF.Requests (~50 KB)  ── HTTP POST ──▶  CobaltPDF (full library)
  PdfRequest  → JSON                            CobaltEngine + Chromium
  PdfResponse ← JSON                            request.ExecuteAsync(engine)

Client:

var request = new PdfRequest
{
    Url         = "https://myapp.com/invoice/42",
    PaperFormat = "A4",
    Metadata    = new() { Title = "Invoice #42", Author = "Billing System" },
    Encryption  = new() { UserPassword = "open123" }
};

var response = await httpClient.PostAsJsonAsync("https://pdf-service/api/pdf", request);
byte[] pdfBytes = await response.Content.ReadAsByteArrayAsync();

Server (Minimal API):

app.MapPost("/api/pdf", async (PdfRequest request, CobaltEngine renderer, CancellationToken ct) =>
{
    var pdf = await request.ExecuteAsync(renderer, ct);
    return Results.File(pdf.BinaryData, "application/pdf", "output.pdf");
});

See the full CobaltPDF.Requests guide for Azure Functions, AWS Lambda, ECS/Fargate examples, the complete JSON schema, and security considerations.

Requirements

Chromium is bundled as a NuGet dependency — no separate installation required.

Documentation

Full documentation, API reference, and deployment guides are available at cobaltpdf.com/docs.

Quick start snippets for every feature: cobaltpdf.com/quickstart.

License

CobaltPDF is a commercial product. A licence key is required for production use. Without a valid licence, a trial watermark is applied to all generated PDFs.

CobaltEngine.SetLicense("YOUR-LICENSE-KEY");

View pricing & licensing →

© 2026 Modus Squared Ltd. All rights reserved.