DEV Community: dotnet

Global Exception Handling in ASP.NET Core — The Complete Guide

Libin Tom Baby — Sat, 25 Apr 2026 14:00:00 +0000

UseExceptionHandler, IExceptionHandler (.NET 8), ProblemDetails, middleware vs filters, logging errors

Unhandled exceptions are inevitable.

The question is not whether they will happen — it's whether your API returns a clear, structured error response or exposes a raw stack trace to the client.

Why You Need Global Exception Handling

Without it:

Unhandled exceptions return 500 Internal Server Error with no useful body
Stack traces may be leaked to clients in non-production environments
Logging is inconsistent — some exceptions get logged, others disappear
Every controller has its own try-catch — duplicated and inconsistent

With it:

Every unhandled exception is caught in one place
Errors are logged consistently
Clients receive a structured, predictable error response
Controllers stay clean — no try-catch everywhere

Approach 1: `UseExceptionHandler` Middleware

The simplest and most compatible approach. Works in all ASP.NET Core versions.

app.UseExceptionHandler(errorApp =>
{
    errorApp.Run(async context =>
    {
        var error = context.Features.Get<IExceptionHandlerFeature>();
        var exception = error?.Error;

        context.Response.StatusCode = exception switch
        {
            NotFoundException => StatusCodes.Status404NotFound,
            ValidationException => StatusCodes.Status400BadRequest,
            UnauthorizedException => StatusCodes.Status401Unauthorized,
            _ => StatusCodes.Status500InternalServerError
        };

        context.Response.ContentType = "application/problem+json";

        var problem = new ProblemDetails
        {
            Status = context.Response.StatusCode,
            Title = GetTitle(exception),
            Detail = exception?.Message,
            Instance = context.Request.Path
        };

        await context.Response.WriteAsJsonAsync(problem);
    });
});

Approach 2: `IExceptionHandler` (.NET 8+)

The modern approach — typed handlers that can be chained.

public class ValidationExceptionHandler : IExceptionHandler
{
    private readonly ILogger<ValidationExceptionHandler> _logger;

    public ValidationExceptionHandler(ILogger<ValidationExceptionHandler> logger)
        => _logger = logger;

    public async ValueTask<bool> TryHandleAsync(
        HttpContext context,
        Exception exception,
        CancellationToken ct)
    {
        if (exception is not ValidationException validationEx)
            return false; // Pass to next handler

        _logger.LogWarning("Validation failed: {Errors}", validationEx.Errors);

        context.Response.StatusCode = StatusCodes.Status400BadRequest;

        var problem = new ValidationProblemDetails(validationEx.ToDictionary())
        {
            Status = StatusCodes.Status400BadRequest,
            Title = "Validation failed",
            Instance = context.Request.Path
        };

        await context.Response.WriteAsJsonAsync(problem, ct);

        return true; // Handled — stop processing
    }
}

builder.Services.AddExceptionHandler<ValidationExceptionHandler>();
builder.Services.AddExceptionHandler<NotFoundExceptionHandler>();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>(); // catch-all last

builder.Services.AddProblemDetails();

app.UseExceptionHandler();

Approach 3: Exception Filter (MVC only)

For MVC controllers specifically — not minimal APIs.

public class ApiExceptionFilter : IExceptionFilter
{
    private readonly ILogger<ApiExceptionFilter> _logger;

    public ApiExceptionFilter(ILogger<ApiExceptionFilter> logger)
        => _logger = logger;

    public void OnException(ExceptionContext context)
    {
        _logger.LogError(context.Exception, "Unhandled exception");

        context.Result = context.Exception switch
        {
            NotFoundException ex => new NotFoundObjectResult(ex.Message),
            ValidationException ex => new BadRequestObjectResult(ex.Message),
            _ => new ObjectResult("An error occurred")
                { StatusCode = StatusCodes.Status500InternalServerError }
        };

        context.ExceptionHandled = true;
    }
}

// Register globally
builder.Services.AddControllers(options =>
{
    options.Filters.Add<ApiExceptionFilter>();
});

ProblemDetails — RFC 7807

ProblemDetails is the standard structured error response format.

{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "Validation failed",
  "status": 400,
  "detail": "The 'Name' field is required",
  "instance": "/api/orders",
  "traceId": "00-8a3e12b1c456d789-b23f4a12c3d45e67-00"
}

Enabling globally:

builder.Services.AddProblemDetails();

Custom Domain Exceptions

public abstract class DomainException : Exception
{
    protected DomainException(string message) : base(message) { }
}

public class NotFoundException : DomainException
{
    public NotFoundException(string entity, object key)
        : base($"{entity} with key {key} was not found.") { }
}

public class ValidationException : DomainException
{
    public IReadOnlyList<string> Errors { get; }

    public ValidationException(IEnumerable<string> errors)
        : base("One or more validation failures occurred.")
    {
        Errors = errors.ToList();
    }
}

public class UnauthorizedException : DomainException
{
    public UnauthorizedException() : base("Unauthorised.") { }
}

Throw them anywhere in your application code — the global handler catches and maps them.

Logging Exceptions

_logger.LogError(
    exception,
    "Unhandled exception for {Method} {Path} — TraceId: {TraceId}",
    context.Request.Method,
    context.Request.Path,
    Activity.Current?.Id ?? context.TraceIdentifier);

Interview-Ready Summary

UseExceptionHandler = catch-all middleware, compatible with all ASP.NET Core versions
IExceptionHandler (.NET 8+) = typed, chainable handlers — preferred for new projects
Exception filters = MVC-specific, controller-level
ProblemDetails = RFC 7807 standard for structured error responses
Define a domain exception hierarchy to map business errors to HTTP status codes
Log every exception with request context and a correlation/trace ID
Never expose raw stack traces to clients

A strong interview answer:

"In ASP.NET Core, global exception handling is best done with UseExceptionHandler middleware or the IExceptionHandler interface introduced in .NET 8. Both catch all unhandled exceptions in one place, log them, and return a structured ProblemDetails response. IExceptionHandler allows typed, chainable handlers where each handles a specific exception type. The key is to keep controllers free of try-catch blocks and let the global handler decide the HTTP status code."

How I Built GPU-Accelerated Frosted Glass and Acrylic Blur for .NET MAUI (And Why Every Other Library Gets It Wrong)

Plixroit — Fri, 24 Apr 2026 14:29:53 +0000

Blur on Android in MAUI is kind of a mess. I needed a frosted-glass effect over a scrolling message list and everything I tried either stuttered or just looked bad when the content behind it moved.

So I dug into how all the existing libraries actually work under the hood. Turns out they're all doing the same thing:

Grab a Bitmap of what's behind the view, on the CPU
Run a blur pass in software
Push it back up to the GPU
Do it again next frame

Every. Single. Frame. No wonder it drops frames.

Why not just stay on the GPU the whole time?

Android 12 added RenderEffect and RenderNode. These let you hook into the GPU render pipeline directly and apply blur without ever touching the CPU. No bitmap snapshots, no software blur, no memory uploads between frames. The GPU just handles it natively.

That's the whole idea behind VitrumMAUI. Keep it on the GPU and get out of the way.

On a mid-range device blurring over a fast scroll, the difference is obvious. No jank.

Two views, that's it

BlurHostView wraps whatever content sits in the background. BlurConsumerView goes on top and shows the blurred result with an optional tint.

<vitrum:BlurHostView>
    <CollectionView ... />
</vitrum:BlurHostView>

<vitrum:BlurConsumerView
    BlurRadius="20"
    TintColor="#33FFFFFF" />

No bitmaps to manage. No invalidation loops. No hacks.

Install

dotnet add package VitrumMAUI --version 1.0.8

Or in your csproj:

<PackageReference Include="VitrumMAUI" Version="1.0.8" />

What's supported

Android version	What you get
12+ (API 31+)	Full GPU blur via RenderEffect
9 to 11	Tint-only fallback

iOS and macOS are not included. Apple's own blur APIs are solid and already built into the platform, so there's no point reinventing that.

Why I actually built this

I was working on a chat UI in my own app. The bottom sheet sits over the message list and I wanted it blurred. Everything I tried was either too slow or required me to wire up manual invalidation which felt wrong. I wanted something that just works without me babysitting it.

So I built it. It's one day old, rough around the edges, but the core works well.

GitHub: VitrumMAUI
NuGet: VitrumMAUI 1.0.8

MIT licensed. If you run into issues or have ideas, open an issue.

Why .NET interviews feel harder than they should

Ayman Atif — Fri, 24 Apr 2026 14:19:20 +0000

Most .NET interview prep goes into learning concepts.

But in actual interviews, I’ve noticed something else matters more.

It’s not just what you know, it’s how you explain it.

A lot of people run into the same issues:

They start explaining too much at once, or they lose clarity halfway through their answer.

And even simple questions like “what’s the difference between IEnumerable and IQueryable?” end up sounding more complicated than they are.

I think the better approach is actually pretty simple:

Start with a clear, short answer first. Then add detail only if needed.

Something like:
“IEnumerable works in memory, IQueryable works with the database.”

Then expand from there if the interviewer wants more.

It sounds small, but it changes how your answers come across a lot.

At the end of the day, interviews are less about how much you know, and more about how clearly you can communicate it.

If you're preparing for .NET interviews, this is something worth paying attention to.

Migrating from jsreport to IronPDF: no fuss, no fluff

IronSoftware — Fri, 24 Apr 2026 11:32:00 +0000

The deployment worked fine on-prem. Then the team containerized the application for Kubernetes, and the PDF generation service started failing intermittently. The error logs pointed to jsreport's child process spawning — Node.js inside a Docker container, with the reporting service trying to launch headless Chromium inside that Node.js process. The layered process management, the user permission model in the container, the memory limits — it all compounds. Getting jsreport running reliably in a container environment takes work that has nothing to do with generating PDFs.

That's a common trigger for evaluating alternatives. This article is for .NET teams considering IronPDF as the replacement. If you're not switching, the architecture comparison section still maps out the tradeoffs worth understanding.

Architecture difference — this matters first

jsreport is a reporting server. IronPDF is a .NET library. That difference has practical implications before you write a single line of migration code:

jsreport architecture:

External Node.js process (separate service, or embedded via jsreport.Local)
Templates stored in jsreport's template engine (Handlebars, etc.)
.NET communicates via HTTP API or local IPC
Reports can be managed via a browser-based designer UI
Supports multiple output formats: PDF, Excel, CSV, HTML, etc.

IronPDF architecture:

In-process .NET library
Templates are HTML strings or files (rendered via Chromium)
No external service — runs in your process
PDF output only (plus manipulation of existing PDFs)
No built-in template management UI

The migration decision depends on what you're actually using jsreport for:

jsreport usage	Migration path
PDF generation only, HTML templates	Direct replacement with IronPDF
Multiple output formats (Excel, CSV, etc.)	IronPDF covers PDF; other formats need separate handling
Template management via browser UI	IronPDF has no equivalent — build template management separately
Complex Handlebars/EJS logic	Rewrite templates in HTML/Razor; logic moves to .NET
On-premises, works fine	No migration trigger — document this and move on

Why migrate (without drama)

Eight specific reasons teams trigger this migration:

Container deployment complexity — jsreport's Chromium-in-Node.js-in-Docker requires managing layered process permissions, seccomp profiles, and memory limits that don't apply to an in-process library.
Node.js dependency in a .NET shop — maintaining a Node.js runtime, managing npm packages, and keeping jsreport updated adds operational overhead for teams without Node.js expertise.
Inter-process communication overhead — HTTP or IPC round trips to a reporting server add latency per PDF. In-process rendering eliminates the network hop.
Service orchestration — jsreport as a separate service needs health checks, restart policies, and separate monitoring. An in-process library reduces the service count.
Azure App Service / serverless constraints — some Azure tiers restrict background process spawning. An in-process renderer avoids this constraint. See IronPDF Azure documentation.
Template management coupling — jsreport templates stored in jsreport's data store create a dependency between your template design and the reporting service. Moving to HTML files in your codebase gives you version control integration.
Output format scope — if PDF is the only output you actually use, maintaining a full reporting platform is overhead.
jsreport licensing tiers — if you're hitting limits on the community edition for your use case, evaluating alternatives is reasonable before upgrading tiers.

Comparison table

Aspect	jsreport	IronPDF
Focus	Multi-format reporting platform	PDF generation + manipulation
Pricing	Community (free) + commercial tiers	Commercial — verify at ironsoftware.com
API Style	HTTP REST API + .NET client	In-process .NET library
Learning Curve	Medium (requires understanding reporting concepts)	Medium (.NET API)
HTML Rendering	Chromium via Puppeteer	Chromium-based
Page Indexing	N/A (output only)	0-based
Thread Safety	External service handles isolation	Renderer instance reuse — see async docs
Namespace	`jsreport.Client` (HTTP client)	`IronPdf`

Migration complexity assessment

Effort by feature

Feature	jsreport approach	Effort to migrate
HTML/Handlebars to PDF	API call with template data	Medium — migrate templates to HTML
URL to PDF	jsreport recipe	Low
Headers and footers	Template recipe options	Medium
Watermark	Custom CSS in template / post-processing	Low (native in IronPDF)
Merge PDFs	Not a jsreport core feature	Low (native in IronPDF)
Password protection	Not a jsreport core feature	Low
Excel output	jsreport native feature	N/A — IronPDF doesn't cover this
CSV output	jsreport native feature	N/A
Template management UI	jsreport studio	Not in IronPDF — build separately
Scheduled reports	jsreport scheduling	Not in IronPDF — build separately
Container deployment	Complex (see opening)	Simpler — in-process

Decision matrix

Scenario	Recommendation
PDF only, container deployment issues	IronPDF is a direct fit — evaluates well
Multi-format output (Excel, CSV) needed	IronPDF covers PDF; retain jsreport for other formats, or add libraries
Template management UI is business-critical	jsreport's studio has no equivalent in IronPDF
Node.js runtime is already in your stack	jsreport overhead is lower — migration ROI is smaller

Before you start

Prerequisites

.NET 6+
HTML template inventory from jsreport
Access to jsreport template files for migration
NuGet access

Find jsreport references in your codebase

# Find jsreport client usage
rg -l "jsreport\|JsReport\|IJsReportClient" --type cs -i

# Find HTTP API calls to jsreport
rg "jsreport\|localhost:5488\|api/report" --type cs -n

# Find template rendering calls
rg "ReportingService\|RenderAsync" --type cs -n

# Find NuGet package references
grep -r "jsreport" *.csproj **/*.csproj 2>/dev/null

# Find jsreport config files
find . -name "jsreport.config.json" -o -name "*.jsrep" 2>/dev/null

Remove jsreport client, install IronPDF

# Remove jsreport .NET client packages
dotnet remove package jsreport.Client
dotnet remove package jsreport.Local    # if using embedded mode
dotnet remove package jsreport.AspNetCore  # if using middleware

# Install IronPDF
dotnet add package IronPdf
dotnet restore

Separately: remove jsreport from Docker images, docker-compose files, and service orchestration config.

Quick start migration (3 steps)

Step 1: License configuration

Before (jsreport — no .NET license key; authenticated via jsreport server config):

using jsreport.Client;
using jsreport.Types;
using System;

// jsreport authentication is handled at the HTTP level
var rs = new ReportingService("http://localhost:5488");
// Optional: rs.Username = "admin"; rs.Password = "password";
// No in-process license key

After (IronPDF):

using IronPdf;

// One-time setup at application startup
IronPdf.License.LicenseKey = "YOUR_IRONPDF_LICENSE_KEY";
// Guide: https://ironpdf.com/how-to/license-keys/

Step 2: Namespace imports

Before:

using jsreport.Client;
using jsreport.Types;
using System.Threading.Tasks;

After:

using IronPdf;
using IronPdf.Rendering;

Step 3: Basic PDF generation

Before (jsreport API call):

using jsreport.Client;
using jsreport.Types;
using System.IO;
using System.Threading.Tasks;

class QuickStartExample
{
    static async Task Main()
    {
        var rs = new ReportingService("http://localhost:5488");

        var report = await rs.RenderAsync(new RenderRequest
        {
            Template = new Template
            {
                Content = "<h1>Hello World</h1>",
                Engine = Engine.None,
                Recipe = Recipe.ChromePdf
            }
        });

        using var ms = new MemoryStream();
        await report.Content.CopyToAsync(ms);
        File.WriteAllBytes("output.pdf", ms.ToArray());
    }
}

After (IronPDF):

using IronPdf;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");
pdf.SaveAs("output.pdf");
// Guide: https://ironpdf.com/how-to/html-string-to-pdf/

API mapping tables

Namespace mapping

jsreport	IronPDF	Notes
`jsreport.Client`	`IronPdf`	Core
`jsreport.Types`	`IronPdf.Rendering`	Configuration types
HTTP client pattern	In-process — no HTTP	Architectural change

Core class mapping

jsreport class	IronPDF class	Description
`ReportingService`	`ChromePdfRenderer`	Entry point for PDF generation
`RenderRequest`	`ChromePdfRenderOptions`	Render configuration
`Template`	HTML string or file	Template definition
`Report.Content` (stream)	`PdfDocument`	PDF output

Document loading methods

Operation	jsreport	IronPDF
HTML string	`Template.Content` + `Engine.None`	`renderer.RenderHtmlAsPdf(html)`
URL	jsreport URL recipe	`renderer.RenderUrlAsPdf(url)`
Template file	jsreport template store	`renderer.RenderHtmlFileAsPdf(path)`
Existing PDF	Not jsreport's scope	`PdfDocument.FromFile(path)`

Page operations

Operation	jsreport	IronPDF
Page size	`ChromePdfOptions.PaperSize`	`ChromePdfRenderOptions.PaperSize`
Margins	`ChromePdfOptions` properties	`ChromePdfRenderOptions.Margin*`
Orientation	jsreport Chrome options	`ChromePdfRenderOptions.PaperOrientation`
Headers/footers	`HeaderTemplate` / `FooterTemplate`	`HtmlHeaderFooter` — verify IronPDF API

Merge/split operations

Operation	jsreport	IronPDF
Merge	Not a core jsreport feature	`PdfDocument.Merge(pdf1, pdf2)`
Split	Not a core jsreport feature	`pdf.CopyPages(startIndex, endIndex)`

Four complete before/after migrations

1. HTML to PDF

Before (jsreport RenderAsync with template data):

using jsreport.Client;
using jsreport.Types;
using System;
using System.IO;
using System.Threading.Tasks;

class HtmlToPdfExample
{
    static async Task Main()
    {
        var rs = new ReportingService("http://localhost:5488");

        // Template with Handlebars data binding
        string template = @"
            <html><body>
                <h1>Invoice #{{invoiceNumber}}</h1>
                <p>Customer: {{customerName}}</p>
                <p>Amount: ${{amount}}</p>
            </body></html>";

        var report = await rs.RenderAsync(new RenderRequest
        {
            Template = new Template
            {
                Content = template,
                Engine = Engine.Handlebars,
                Recipe = Recipe.ChromePdf,
                Chrome = new Chrome { MarginTop = "10mm", MarginBottom = "10mm" }
            },
            Data = new
            {
                invoiceNumber = "1234",
                customerName = "ACME Corp",
                amount = "500.00"
            }
        });

        // Stream to bytes
        using var ms = new MemoryStream();
        await report.Content.CopyToAsync(ms);
        File.WriteAllBytes("invoice.pdf", ms.ToArray());
        Console.WriteLine("Saved: invoice.pdf");
    }
}

After (IronPDF — template logic moves to your .NET code):

using IronPdf;
using System;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

// Template data rendering moves to .NET (Razor, string interpolation, etc.)
var invoiceNumber = "1234";
var customerName = "ACME Corp";
var amount = "500.00";

string html = $@"
    <html><body>
        <h1>Invoice #{invoiceNumber}</h1>
        <p>Customer: {customerName}</p>
        <p>Amount: ${amount}</p>
    </body></html>";

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.MarginTop = 10;
renderer.RenderingOptions.MarginBottom = 10;

var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("invoice.pdf");

2. Merge PDFs

Before (jsreport doesn't merge natively — multi-report generation then merge separately):

using jsreport.Client;
using jsreport.Types;
using PdfSharp.Pdf;       // secondary library
using PdfSharp.Pdf.IO;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;

class MergeReportsExample
{
    static async Task Main()
    {
        var rs = new ReportingService("http://localhost:5488");
        var tempPaths = new List<string>();

        // Generate each section as separate PDF
        foreach (var sectionHtml in new[] { "<h1>Section 1</h1>", "<h1>Section 2</h1>" })
        {
            var report = await rs.RenderAsync(new RenderRequest
            {
                Template = new Template
                {
                    Content = sectionHtml,
                    Engine = Engine.None,
                    Recipe = Recipe.ChromePdf
                }
            });
            var tempPath = Path.GetTempFileName() + ".pdf";
            using var fs = new FileStream(tempPath, FileMode.Create);
            await report.Content.CopyToAsync(fs);
            tempPaths.Add(tempPath);
        }

        // Merge with PdfSharp (secondary library)
        using var outputDoc = new PdfDocument();
        foreach (var path in tempPaths)
        {
            using var input = PdfReader.Open(path, PdfDocumentOpenMode.Import);
            foreach (PdfPage page in input.Pages)
                outputDoc.AddPage(page);
        }
        outputDoc.Save("merged.pdf");
        foreach (var path in tempPaths) File.Delete(path); // cleanup
    }
}

After (IronPDF native merge):

using IronPdf;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

var renderer = new ChromePdfRenderer();

var section1 = renderer.RenderHtmlAsPdf("<h1>Section 1</h1>");
var section2 = renderer.RenderHtmlAsPdf("<h1>Section 2</h1>");

var merged = PdfDocument.Merge(section1, section2);
merged.SaveAs("merged.pdf");
// Guide: https://ironpdf.com/how-to/merge-or-split-pdfs/

3. Watermark

Before (jsreport — watermark typically via CSS in template, or post-process with secondary library):

using jsreport.Client;
using jsreport.Types;
using iTextSharp.text;
using iTextSharp.text.pdf;
using System.IO;
using System.Threading.Tasks;

class WatermarkExample
{
    static async Task Main()
    {
        var rs = new ReportingService("http://localhost:5488");

        // Generate PDF
        var report = await rs.RenderAsync(new RenderRequest
        {
            Template = new Template
            {
                Content = "<h1>Confidential Report</h1>",
                Engine = Engine.None,
                Recipe = Recipe.ChromePdf
            }
        });

        // Write to temp file, apply watermark with secondary library
        var temp = Path.GetTempFileName() + ".pdf";
        using (var fs = new FileStream(temp, FileMode.Create))
            await report.Content.CopyToAsync(fs);

        // Apply watermark via iTextSharp (secondary library)
        using var reader  = new PdfReader(temp);
        using var outFs   = new FileStream("watermarked.pdf", FileMode.Create);
        using var stamper = new PdfStamper(reader, outFs);
        var font = BaseFont.CreateFont(BaseFont.HELVETICA_BOLD, BaseFont.CP1252, false);
        for (int i = 1; i <= reader.NumberOfPages; i++)
        {
            var cb = stamper.GetOverContent(i);
            cb.BeginText();
            cb.SetFontAndSize(font, 60);
            cb.SetColorFill(new BaseColor(200, 200, 200));
            cb.ShowTextAligned(Element.ALIGN_CENTER, "CONFIDENTIAL", 300, 400, 45);
            cb.EndText();
        }
        File.Delete(temp);
    }
}

After (IronPDF — no secondary library needed):

using IronPdf;
using IronPdf.Editing;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Confidential Report</h1>");

var stamper = new TextStamper
{
    Text = "CONFIDENTIAL",
    FontColor = IronSoftware.Drawing.Color.LightGray,
    FontSize = 60,
    Opacity = 30,
    Rotation = 45,
    VerticalAlignment = VerticalAlignment.Middle,
    HorizontalAlignment = HorizontalAlignment.Center
};
pdf.ApplyStamp(stamper);
pdf.SaveAs("watermarked.pdf");
// Guide: https://ironpdf.com/how-to/custom-watermark/

4. Password protection

Before (jsreport — not a native feature; secondary library pattern):

using jsreport.Client;
using jsreport.Types;
using iTextSharp.text.pdf;
using System.IO;
using System.Text;
using System.Threading.Tasks;

class SecurityExample
{
    static async Task Main()
    {
        var rs = new ReportingService("http://localhost:5488");

        var report = await rs.RenderAsync(new RenderRequest
        {
            Template = new Template
            {
                Content = "<h1>Private Document</h1>",
                Engine = Engine.None,
                Recipe = Recipe.ChromePdf
            }
        });

        // Stream to bytes, then encrypt with secondary library
        byte[] pdfBytes;
        using (var ms = new MemoryStream())
        {
            await report.Content.CopyToAsync(ms);
            pdfBytes = ms.ToArray();
        }

        using var reader  = new PdfReader(pdfBytes);
        using var fs      = new FileStream("secured.pdf", FileMode.Create);
        using var stamper = new PdfStamper(reader, fs, '\0', false);
        stamper.SetEncryption(
            Encoding.ASCII.GetBytes("userpass"),
            Encoding.ASCII.GetBytes("ownerpass"),
            PdfWriter.ALLOW_PRINTING,
            PdfWriter.ENCRYPTION_AES_128
        );
    }
}

After (IronPDF):

using IronPdf;
using IronPdf.Security;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Private Document</h1>");

pdf.SecuritySettings.UserPassword  = "userpass";
pdf.SecuritySettings.OwnerPassword = "ownerpass";
pdf.SecuritySettings.AllowUserPrinting = PdfPrintSecurity.FullPrintRights;
pdf.SaveAs("secured.pdf");
// Guide: https://ironpdf.com/how-to/pdf-permissions-passwords/

Critical migration notes

Template engine migration

jsreport templates use Handlebars, EJS, or similar engines running in Node.js. After migration, that template logic needs a .NET home. Common patterns:

// Option 1: String interpolation (simple cases)
string html = $"<h1>Invoice #{invoice.Number}</h1><p>Total: {invoice.Total:C}</p>";

// Option 2: Razor in a separate class library
// Use RazorLight or a similar Razor rendering library to compile .cshtml → string
// Then pass string to ChromePdfRenderer

// Option 3: Handlebars.NET
// NuGet: Handlebars.Net — allows reusing Handlebars template syntax in .NET
var template = Handlebars.Compile(handlebarsTemplate);
string html = template(data);
var pdf = renderer.RenderHtmlAsPdf(html);

jsreport.Local (embedded mode)

If you were using jsreport.Local (which embeds Node.js directly in the .NET process), the migration is simpler — the HTTP layer is already internal. The code change is still significant, but the deployment change is minimal.

Service removal

If jsreport runs as a separate Docker service in your compose or Kubernetes setup:

# docker-compose.yml — remove this service entirely:
# services:
#   jsreport:
#     image: jsreport/jsreport
#     ports:
#       - "5488:5488"

Update any service dependencies that reference the jsreport container.

Page indexing

IronPDF uses 0-based page indexing for all document operations. jsreport doesn't expose a page model (it renders and outputs), so this only matters if you added post-processing with page-aware operations.

Performance considerations

Eliminate HTTP round trip

Every jsreport PDF generation made a network round trip (or at least IPC). IronPDF renders in-process — no network latency:

// jsreport: HTTP call → jsreport Node process → Chromium → response
// Typical latency: 100-500ms+ depending on network and template complexity

// IronPDF: in-process → Chromium → return
// Same Chromium rendering, no network overhead

Renderer reuse in ASP.NET

// Register as singleton in ASP.NET Core for reuse
builder.Services.AddSingleton<ChromePdfRenderer>(sp =>
{
    var renderer = new ChromePdfRenderer();
    renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;
    return renderer;
});

Async rendering

// Async pattern for web handlers
var renderer = new ChromePdfRenderer();
var pdf = await renderer.RenderHtmlAsPdfAsync(html);
// Async guide: https://ironpdf.com/how-to/async/

// Return as file download
return File(pdf.Stream, "application/pdf", "report.pdf");

Azure / cloud deployment

IronPDF's in-process Chromium is more predictable in containerized environments than jsreport's Node.js + Chromium stack. Verify configuration for your specific Azure tier — see IronPDF Azure documentation.

Edge cases worth flagging

Handlebars template complexity — if your jsreport templates have complex Handlebars helpers or partials, inventory them before migrating. Each helper needs a .NET equivalent.
jsreport assets — images, fonts, and stylesheets referenced as jsreport assets need to be moved to accessible static paths or embedded in the HTML.
Scheduling and reporting workflows — jsreport includes scheduling features. If your system uses them, build those workflows separately in .NET after migration.

Migration checklist

Pre-migration

[ ] Find all jsreport client code: rg "jsreport\|ReportingService" --type cs -i
[ ] Inventory all jsreport templates — export from jsreport studio if needed
[ ] Identify non-PDF outputs (Excel, CSV) — plan separately
[ ] Identify scheduled reports — plan .NET-based scheduling separately
[ ] Map Handlebars helpers to .NET equivalents
[ ] Identify jsreport assets (images, fonts, styles)
[ ] Verify IronPDF .NET version compatibility
[ ] Check Azure / cloud tier for Chromium subprocess permissions if relevant
[ ] Set up IronPDF trial license in dev environment

Code migration

[ ] Remove jsreport.Client, jsreport.Local, jsreport.AspNetCore NuGet packages
[ ] Add IronPdf NuGet package
[ ] Replace ReportingService client with ChromePdfRenderer
[ ] Replace RenderRequest + Template with HTML string generation
[ ] Migrate Handlebars templates to .NET template engine (Razor, Handlebars.NET, etc.)
[ ] Replace merge operations (if any secondary library involved)
[ ] Replace watermark operations
[ ] Replace password protection
[ ] Add IronPDF license key to config
[ ] Register ChromePdfRenderer in DI if using ASP.NET

Testing

[ ] Render each template and compare output against jsreport reference PDFs
[ ] Test with production-representative data (edge cases in data binding)
[ ] Verify merge, watermark, security operations
[ ] Test async rendering under concurrent load
[ ] Test in target deployment environment (container, Azure, etc.)
[ ] Verify no Chromium subprocess permission issues in container

Post-migration

[ ] Remove jsreport Docker service from compose / Kubernetes config
[ ] Remove jsreport port from service discovery / firewall rules
[ ] Remove Node.js runtime from Docker images if jsreport was the only consumer
[ ] Update monitoring — replace jsreport health checks with in-process metrics
[ ] Monitor memory baseline (Chromium in-process vs external service)

Conclusion

The architectural shift from external reporting server to in-process library is the meaningful part of this migration. The API differences are straightforward once you've mapped the template engine and determined how non-PDF outputs will be handled.

Teams that hit friction tend to be the ones with large Handlebars template libraries — that migration is mechanical but takes time. And teams who depended on jsreport Studio for template management need to decide where that workflow goes.

What would you add to this migration checklist based on your own jsreport integration? Particularly interested in teams who had complex Handlebars helpers or were running jsreport in Kubernetes — those setups tend to have extra migration steps not covered here.

wkhtmltopdf Memory Leak and High Memory Usage (Issue Fixed)

IronSoftware — Fri, 24 Apr 2026 11:27:00 +0000

When wkhtmltopdf generates large documents, memory consumption escalates rapidly and often does not return to baseline after conversion completes. A 4,250-page document can require approximately 5GB of RAM. Tables with 400,000 records cause memory to climb at roughly 20MB per second. In containerized environments, this results in OOMKilled errors that terminate the process mid-conversion. The wkhtmltopdf project was archived in January 2023 with no further updates to address these memory management issues.

The Problem

wkhtmltopdf exhibits several memory-related behaviors that impact production deployments. Memory allocation grows proportionally with document complexity, but deallocation after conversion is incomplete. Successive conversions accumulate unreleased memory until the process is terminated.

The Qt WebKit rendering engine at the core of wkhtmltopdf was designed for interactive browser sessions, not batch document processing. When rendering large HTML tables or complex CSS layouts, WebKit allocates memory for the entire document tree. Elements with JavaScript animations or dynamic content consume additional memory that persists after rendering completes.

Container orchestration systems like Kubernetes enforce memory limits on pods. When wkhtmltopdf exceeds these limits, the Linux OOM killer terminates the container. This presents as sudden process death without meaningful error messages in application logs.

Error Messages and Symptoms

Developers encounter these errors related to wkhtmltopdf memory consumption:

OOMKilled in Docker/Kubernetes:

State:          Terminated
Reason:         OOMKilled
Exit Code:      137

Container killed due to memory limit exceeded
wkhtmltopdf process exited with code 137

System Memory Errors:

Cannot allocate memory

Memory limit too low

Process Hangs or Crashes:

Exit with code 1 due to network error: ContentOperationNotPermittedError

Killed

The symptoms include:

Memory usage increasing steadily during conversion (approximately 20MB/second for large tables)
Memory not returning to baseline after conversion completes
Multiple sequential conversions exhausting available RAM
Container restart loops in Kubernetes deployments
Process freezing or hanging during large document generation
Exit code 137 indicating OOM termination

Who Is Affected

This wkhtmltopdf memory issue impacts specific deployment scenarios:

Operating Systems: Linux servers, Docker containers (Debian, Ubuntu, Alpine), and cloud platform instances. Windows and macOS local development machines may not exhibit the issue due to higher default memory limits.

Container Platforms: Docker with default memory limits, Kubernetes pods with resource constraints, AWS ECS tasks, Azure Container Instances, and Google Cloud Run instances with 512MB-2GB limits.

Use Cases: Large report generation (1000+ pages), data export to PDF with extensive tables (100,000+ rows), batch processing of multiple documents in sequence, long-running services performing repeated conversions.

Scale Factors: The issue becomes critical when documents exceed approximately 500 pages, when tables contain more than 50,000 rows, when generating multiple PDFs without process restart, or when container memory is limited below 4GB.

Frameworks: Any .NET, Python, Ruby, PHP, or Node.js application using wkhtmltopdf through wrapper libraries (DinkToPdf, pdfkit, wicked_pdf, snappy, node-wkhtmltopdf).

Evidence from the Developer Community

The wkhtmltopdf memory leak has been documented across multiple platforms over several years.

Timeline

Date	Event	Source
2016-2017	Memory issues reported with large documents	GitHub Issues
2018-2019	Container memory problems widely discussed	Stack Overflow
2020	Recommendations emerge to limit container memory to 4GB+	GitHub, Forums
2022-12	Final wkhtmltopdf release (0.12.6.1-3)	GitHub
2023-01	Project archived with no memory fixes planned	GitHub
2024-2025	Legacy deployments continue experiencing OOM issues	Various platforms

Community Reports

"Generating a 4250-page PDF was using close to 5 gigs of memory."
— Developer, Stack Overflow, 2018

"Memory consumption is increasing around 20 MB per second during the build. My table records are 400k."
— Developer, GitHub Issues, 2019

"Complex CSS is causing memory to grow without bounds. We had to add a memory limit of 4GB to the container."
— Developer, Reddit r/docker, 2021

"Our wkhtmltopdf containers keep getting OOMKilled. We're seeing memory climb and never release between conversions."
— Developer, Stack Overflow, 2022

Multiple GitHub issues document the memory behavior:

Issue #3052: "High memory usage with large tables"
Issue #4120: "Memory not released after conversion"
Issue #4521: "OOM in Docker containers"

Root Cause Analysis

The wkhtmltopdf memory leak stems from several architectural factors:

Qt WebKit Memory Model: The underlying Qt WebKit engine maintains DOM nodes and rendering context in memory. Large documents create extensive node trees that persist beyond their use. WebKit's garbage collection is designed for interactive browsing, not single-use document generation.

Process Architecture: wkhtmltopdf runs as a single process that handles the entire conversion. Memory allocated during rendering phases is not released until the process terminates. Sequential conversions accumulate allocations.

CSS and Layout Engine: Complex CSS (especially flexible layouts, transforms, and nested elements) requires additional memory for layout calculations. Large tables trigger row-by-row rendering that holds all previous rows in memory.

JavaScript Execution: When JavaScript is enabled, the V8 engine (or JavaScriptCore in older builds) allocates memory for script execution contexts. Memory associated with completed scripts may not be released.

Image Handling: Embedded or referenced images are decoded and cached in memory. Large images or numerous images multiply memory consumption.

No Streaming Output: wkhtmltopdf builds the entire document in memory before writing output. There is no streaming mode that would allow memory-efficient processing of large documents.

Archived Project: With maintenance ended in January 2023, these memory management issues will not receive fixes. The underlying Qt WebKit has not been updated to modern memory management patterns.

Attempted Workarounds

Workaround 1: Disable JavaScript and Images

Approach: Reduce memory by disabling features that consume additional resources.

wkhtmltopdf --disable-javascript --no-images --lowquality input.html output.pdf

Command-line options:

--disable-javascript: Prevents V8 memory allocation for script execution
--no-images: Skips image decoding and caching
--lowquality: Reduces image quality and processing memory

Limitations:

Removes functionality required by many documents
JavaScript-dependent content will not render
Images will be missing from output
Not applicable when documents require these features

Workaround 2: Increase Container Memory Limits

Approach: Allocate 4GB or more to the container.

# Kubernetes deployment
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: pdf-generator
        resources:
          limits:
            memory: "4Gi"
          requests:
            memory: "2Gi"

# Docker run
docker run --memory=4g myapp-with-wkhtmltopdf

Limitations:

Increases infrastructure costs
May not be possible on constrained platforms (serverless, shared hosting)
Does not fix the leak, only delays OOM
4GB may still be insufficient for very large documents

Workaround 3: Process Isolation and Restart

Approach: Run each conversion in a new process and terminate it after completion.

# Python example: subprocess isolation
import subprocess
import os

def convert_with_isolation(html_path, pdf_path):
    """Run wkhtmltopdf in isolated subprocess to contain memory leaks."""
    process = subprocess.Popen(
        ['wkhtmltopdf', html_path, pdf_path],
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE
    )
    stdout, stderr = process.communicate(timeout=300)

    if process.returncode != 0:
        raise Exception(f"wkhtmltopdf failed: {stderr.decode()}")

    # Process terminates here, releasing all memory
    return pdf_path

// C# example: process-per-conversion
public class IsolatedWkhtmltopdf
{
    public void ConvertWithMemoryIsolation(string htmlPath, string pdfPath)
    {
        // Each conversion spawns a new process
        using (var process = new Process())
        {
            process.StartInfo = new ProcessStartInfo
            {
                FileName = "wkhtmltopdf",
                Arguments = $"\"{htmlPath}\" \"{pdfPath}\"",
                UseShellExecute = false,
                RedirectStandardError = true
            };

            process.Start();
            process.WaitForExit(300000); // 5 minute timeout

            // Process disposal releases memory
        }
    }
}

Limitations:

Process startup overhead for each conversion
Does not help with single large document that exceeds memory
Adds complexity to application code
Kubernetes container restarts may still occur during conversion

Workaround 4: Document Chunking

Approach: Split large documents into smaller segments and merge PDFs.

# Split large HTML table into chunks
def chunk_table_data(data, chunk_size=10000):
    """Generate separate PDFs for chunks of data, then merge."""
    for i in range(0, len(data), chunk_size):
        chunk = data[i:i + chunk_size]
        html = generate_html_table(chunk)
        yield convert_to_pdf(html)

    # Merge PDFs using pdftk or similar
    merge_pdfs(pdf_chunks, "final_output.pdf")

Limitations:

Requires document restructuring
Headers/footers may be inconsistent across chunks
Page numbering becomes complicated
Additional tooling required for PDF merge
Not applicable for documents that cannot be segmented

A Different Approach: IronPDF

For applications experiencing wkhtmltopdf memory issues, IronPDF offers an architecture designed for efficient memory usage during document generation. IronPDF uses an embedded Chromium rendering engine with memory management appropriate for server-side batch processing.

Why IronPDF Has Different Memory Characteristics

The architectural differences address the memory concerns:

Chromium's Memory Model: Chromium includes garbage collection and memory pooling designed for long-running processes, unlike Qt WebKit's browser-session assumptions
Proper Resource Disposal: IronPDF implements IDisposable patterns that release native memory when documents are disposed
Streaming Capabilities: Large documents can be processed with streaming patterns that reduce peak memory consumption
Active Maintenance: Memory issues can be addressed through updates, unlike the archived wkhtmltopdf

Code Example

using IronPdf;
using System;
using System.Collections.Generic;

/// <summary>
/// Demonstrates memory-efficient PDF generation for large documents.
/// Addresses the wkhtmltopdf memory leak issue by using IronPDF's
/// Chromium-based rendering with proper resource management.
/// </summary>
public class MemoryEfficientPdfGenerator
{
    public void GenerateLargeReport(List<ReportRow> data)
    {
        // Configure for server environments
        Installation.LinuxAndDockerDependenciesAutoConfig = true;

        var renderer = new ChromePdfRenderer();

        // Configure rendering for large documents
        renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;
        renderer.RenderingOptions.Timeout = 300; // 5 minutes for large documents

        // Build HTML with large data table
        string html = BuildLargeTableHtml(data);

        // Using statement ensures proper memory cleanup after conversion
        using (var pdf = renderer.RenderHtmlAsPdf(html))
        {
            pdf.SaveAs("/output/large-report.pdf");
            Console.WriteLine($"Generated PDF: {pdf.PageCount} pages, {pdf.BinaryData.Length} bytes");
        }
        // Memory released when pdf is disposed
    }

    public void ProcessMultipleDocumentsEfficiently(List<string> htmlDocuments)
    {
        // Single renderer instance can be reused without memory accumulation
        var renderer = new ChromePdfRenderer();

        foreach (var html in htmlDocuments)
        {
            // Each document is properly disposed after use
            using (var pdf = renderer.RenderHtmlAsPdf(html))
            {
                string filename = $"/output/doc-{Guid.NewGuid()}.pdf";
                pdf.SaveAs(filename);
            }
            // Memory from previous document is released before next iteration
        }
    }

    public void GenerateWithExplicitMemoryControl()
    {
        var renderer = new ChromePdfRenderer();

        // Configure rendering options that impact memory usage
        renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;

        // For very large tables, consider pagination in HTML
        string html = @"
            <!DOCTYPE html>
            <html>
            <head>
                <style>
                    table { width: 100%; border-collapse: collapse; }
                    th, td { border: 1px solid #ccc; padding: 8px; }
                    tr { page-break-inside: avoid; }
                    thead { display: table-header-group; }
                </style>
            </head>
            <body>
                <h1>Large Data Report</h1>
                <table>
                    <thead>
                        <tr><th>ID</th><th>Name</th><th>Value</th><th>Date</th></tr>
                    </thead>
                    <tbody>
                        <!-- Data rows would be generated here -->
                        " + GenerateTableRows(100000) + @"
                    </tbody>
                </table>
            </body>
            </html>";

        using (var pdf = renderer.RenderHtmlAsPdf(html))
        {
            pdf.SaveAs("/output/large-table.pdf");
        }
    }

    private string BuildLargeTableHtml(List<ReportRow> data)
    {
        var rows = string.Join("\n", data.Select(r =>
            $"<tr><td>{r.Id}</td><td>{r.Name}</td><td>{r.Value:C}</td></tr>"));

        return $@"
            <!DOCTYPE html>
            <html>
            <head>
                <style>
                    table {{ width: 100%; border-collapse: collapse; }}
                    th, td {{ border: 1px solid #ddd; padding: 8px; }}
                    th {{ background-color: #4CAF50; color: white; }}
                    tr:nth-child(even) {{ background-color: #f2f2f2; }}
                </style>
            </head>
            <body>
                <h1>Report with {data.Count:N0} Records</h1>
                <table>
                    <thead><tr><th>ID</th><th>Name</th><th>Value</th></tr></thead>
                    <tbody>{rows}</tbody>
                </table>
            </body>
            </html>";
    }

    private string GenerateTableRows(int count)
    {
        var sb = new System.Text.StringBuilder();
        for (int i = 0; i < count; i++)
        {
            sb.AppendLine($"<tr><td>{i}</td><td>Item {i}</td><td>{i * 1.5:F2}</td><td>2025-01-{(i % 28) + 1:D2}</td></tr>");
        }
        return sb.ToString();
    }
}

public class ReportRow
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Value { get; set; }
}

Docker configuration with appropriate memory:

FROM mcr.microsoft.com/dotnet/aspnet:8.0-bookworm-slim
WORKDIR /app

# IronPDF dependencies - memory-efficient compared to wkhtmltopdf stack
RUN apt-get update && apt-get install -y \
    libc6 \
    libgcc-s1 \
    libgssapi-krb5-2 \
    libicu72 \
    libssl3 \
    libstdc++6 \
    zlib1g \
    && rm -rf /var/lib/apt/lists/*

COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "YourApp.dll"]

# Kubernetes deployment - compare to wkhtmltopdf's 4GB requirement
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: pdf-service
        resources:
          limits:
            memory: "2Gi"  # Typically sufficient vs 4GB+ for wkhtmltopdf
          requests:
            memory: "1Gi"

Key points about this code:

using statements ensure native memory is released after each document
Single renderer instance can process multiple documents without memory accumulation
Timeout configuration prevents indefinite hangs on complex documents
Disposed resources are released back to the system, unlike wkhtmltopdf's retained allocations

API Reference

For more details on memory-efficient PDF generation:

Migration Considerations

Licensing

IronPDF is commercial software with per-developer licensing. A free trial allows evaluation. wkhtmltopdf is open source under LGPLv3. The licensing cost should be evaluated against infrastructure costs (higher memory containers) and engineering time spent managing wkhtmltopdf memory issues.

API Differences

Migration from wkhtmltopdf involves adapting to the IronPDF API:

Command-line flags to IronPDF properties:

wkhtmltopdf Flag	IronPDF Equivalent
`--disable-javascript`	`RenderingOptions.EnableJavaScript = false`
`--no-images`	`RenderingOptions.RenderImages = false`
`--lowquality`	`RenderingOptions.ImageQuality = 50`
`--page-size A4`	`RenderingOptions.PaperSize = PdfPaperSize.A4`
`--orientation Landscape`	`RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape`

Memory-related differences:

Aspect	wkhtmltopdf	IronPDF
Memory after conversion	Not fully released	Released on dispose
Sequential conversions	Memory accumulates	Memory stable
Recommended container memory	4GB+	2GB typical
Process restart for memory	Often required	Not required

What You Gain

Proper memory release after document generation
Ability to process sequential documents without memory accumulation
Lower container memory requirements
No OOMKilled errors under normal operation
Active maintenance and bug fixes

What to Consider

Commercial licensing cost
Different rendering engine may produce visual differences
API migration effort from wrapper libraries
Chromium runtime is larger than Qt WebKit binary

Conclusion

wkhtmltopdf's memory management behavior makes it unsuitable for generating large documents or processing multiple conversions in memory-constrained environments. The project's archived status means these issues will not be resolved. For applications experiencing OOMKilled errors, memory accumulation between conversions, or needing to process documents exceeding several hundred pages, migrating to a library with proper resource disposal addresses the root cause rather than working around it with increased memory limits.

Written by Jacob Mellor, the original developer of IronPDF with 25+ years of commercial software experience.

References

wkhtmltopdf GitHub Repository - Archived{:rel="nofollow"} - Official repository, archived January 2023
wkhtmltopdf Memory Issues on Stack Overflow{:rel="nofollow"} - Community questions about memory consumption
wkhtmltopdf Issue #3052: High Memory Usage{:rel="nofollow"} - GitHub issue documenting memory with large tables
Kubernetes OOMKilled Documentation{:rel="nofollow"} - Understanding container memory limits
wkhtmltopdf Known Issues{:rel="nofollow"} - Official status page listing limitations

For IronPDF documentation and tutorials, visit ironpdf.com.

Migrating from Ghostscript GPL to IronPDF: what actually changes in your code

IronSoftware — Fri, 24 Apr 2026 10:33:00 +0000

Ghostscript GPL maintenance status: Actively maintained by Artifex Software. GPL version is open source; commercial license (Ghostscript AGPL → commercial) is available. Source: https://www.ghostscript.com — verify current version (10.x as of 2025).
Technical approach + .NET versions: Ghostscript is a native C library invoked via CLI subprocess, P/Invoke wrapper, or third-party .NET wrapper (e.g., Ghostscript.NET). No first-party .NET SDK. Verify wrapper library versions and .NET compatibility.
Install footprint: Native Ghostscript binary installation required (gs on Linux/macOS, gswin64c.exe on Windows). .NET wrappers vary in package quality. Container images require explicit apt-get install ghostscript.
IronPDF doc links: https://ironpdf.com/how-to/license-keys/ · https://ironpdf.com/how-to/html-string-to-pdf/ · https://ironpdf.com/how-to/merge-or-split-pdfs/ · https://ironpdf.com/how-to/pdf-permissions-passwords/ · https://ironpdf.com/how-to/rendering-options/
What Ghostscript is for: PostScript/PDF interpretation, conversion, rendering, rasterization. Not an HTML-to-PDF tool. Primary use in .NET: PDF-to-image conversion, PDF manipulation via shell command.
No-guess rule applied: All .NET wrapper API calls marked "verify in docs."

Checklist: What to Read Before You Start

Before writing a single line of replacement code, confirm these items.

[ ] Identify your Ghostscript invocation pattern — subprocess call, Ghostscript.NET wrapper, or direct P/Invoke?
[ ] Audit GPL exposure — Ghostscript GPL is AGPL-licensed; distributing software that links against it may require your source to be open or a commercial Ghostscript license. Verify with your legal team.
[ ] List every gs argument combination in your codebase — each combination is a feature that needs a migration target.
[ ] Determine which operations you actually use — Ghostscript does a lot; you probably use 10% of it.
[ ] Check IronPDF feature overlap — IronPDF is not a PostScript interpreter; some Ghostscript use cases have no IronPDF equivalent.

Why Migrate (Without Drama)

Teams using Ghostscript in .NET applications often encounter a familiar set of issues depending on their use case and deployment environment:

GPL/AGPL license obligations — Ghostscript under GPL requires derivative works to also be GPL unless a commercial license is purchased; this drives migration for commercial software.
No first-party .NET library — Ghostscript requires subprocess invocation or third-party wrappers; both add fragility.
Subprocess fragility — path resolution, process management, and argument escaping are error-prone across environments.
Native binary dependency — Ghostscript must be installed on every machine, container, and CI runner; version mismatches cause subtle failures.
No HTML-to-PDF capability — Ghostscript doesn't render HTML; if you've added a web-based report layer, you're already using a second tool.
Error handling — Ghostscript returns exit codes and stderr output; structured error handling requires parsing text output.
Thread safety — running multiple Ghostscript processes concurrently requires process management; a managed library is simpler.
Windows vs. Linux binary differences — gswin64c.exe vs. gs adds conditional logic to process invocations.
Upgrade fragility — Ghostscript version upgrades sometimes change argument behavior or output format.
Container overhead — apt-get install ghostscript in Dockerfiles pulls native dependencies; image sizes grow and dependency audits become more complex.

Comparison Table

Aspect	Ghostscript (via .NET wrapper/subprocess)	IronPDF
Focus	PostScript/PDF interpretation, rasterization, conversion	HTML-to-PDF rendering + document manipulation
Pricing	GPL (free with AGPL conditions) or commercial license	Commercial license
API Style	Subprocess args / P/Invoke / wrapper library	Fluent .NET library
Learning Curve	High — PostScript model, arg-based configuration	Medium — .NET-native API
HTML Rendering	Not supported	Primary capability (Chromium-based)
Page Indexing	1-based in most CLI contexts	0-based
Thread Safety	Process-per-operation (subprocess) or verify wrapper	Renderer-per-thread recommended
Namespace	`Ghostscript.NET` (third-party) or System.Diagnostics.Process	`IronPdf`

Migration Complexity Assessment

Effort by Feature

Feature	Effort	Notes
HTML to PDF	Low (IronPDF)	Ghostscript can't do this; IronPDF is new capability
PDF to image (rasterize)	Medium-High	Ghostscript strength; verify IronPDF rasterization
PDF merge	Low	IronPDF supports; Ghostscript merge via `-sDEVICE=pdfwrite`
PDF split	Medium	Both support; different API shape
PDF compression	Medium	Ghostscript `-dPDFSETTINGS` vs IronPDF compression options
PostScript to PDF	N/A for IronPDF	Ghostscript-only; no IronPDF equivalent
Font embedding	Medium	Handled differently in Chromium-based rendering
Password protection	Low	IronPDF supports natively
Watermarking	Low	IronPDF supports natively
Batch processing	Medium	Subprocess batching → managed async pattern

Decision Matrix

Business Scenario	Recommendation
PostScript processing required	Retain Ghostscript; no IronPDF equivalent
HTML-to-PDF primary workload	IronPDF migration is well-scoped
PDF-to-image rasterization required	Verify IronPDF raster export; test quality
GPL license compliance concern	Commercial Ghostscript license or migrate; verify with legal

Before You Start

Prerequisites

.NET 6, 7, or 8 project
Ghostscript invocation audit complete
IronPDF license key (https://ironpdf.com/how-to/license-keys/)

Find Ghostscript References in Your Codebase

# Find subprocess calls to gs/gswin64c
rg "gswin|ghostscript|\"gs\"" --type cs -i

# Find Ghostscript.NET wrapper references
rg "Ghostscript\.NET" --type cs

# Find process start calls (broader scan)
rg "Process\.Start" --type cs

# Find NuGet package references
rg -i "ghostscript" **/*.csproj

Remove Ghostscript Wrapper, Add IronPDF

# Remove Ghostscript.NET wrapper (if used — verify package name)
dotnet remove package Ghostscript.NET

# Add IronPDF
dotnet add package IronPdf

dotnet restore

Note: The Ghostscript native binary installation (OS package) is separate from any NuGet wrapper. If you remove all Ghostscript usages, you can also remove the native binary from container images, Dockerfiles, and CI provisioning scripts.

Quick Start Migration (3 Steps)

Step 1: License Configuration

Before (Ghostscript — no .NET license initialization)

// Ghostscript doesn't have a .NET license initialization step.
// Licensing is handled at the OS/binary level.
// GPL usage is governed by Ghostscript's AGPL license terms — verify legal compliance.
using System.Diagnostics;

// Typical Ghostscript process setup:
var psi = new ProcessStartInfo
{
    FileName  = RuntimeInformation.IsOSPlatform(OSPlatform.Windows)
                    ? "gswin64c.exe"
                    : "gs",
    Arguments = "-dNOPAUSE -dBATCH ...", // varies per operation
    RedirectStandardOutput = true,
    RedirectStandardError  = true,
    UseShellExecute = false
};

After (IronPDF)

using IronPdf;

// See: https://ironpdf.com/how-to/license-keys/
IronPdf.License.LicenseKey = "YOUR_IRONPDF_KEY";
// One line. No binary path resolution. No platform branching.

Step 2: Namespace Imports

Before

using System.Diagnostics;
using System.Runtime.InteropServices;
// If using Ghostscript.NET wrapper:
// using Ghostscript.NET;
// using Ghostscript.NET.Processor;

After

using IronPdf;
using IronPdf.Rendering;
using IronPdf.Editing;

Step 3: Basic Conversion

Before (Ghostscript PDF merge via subprocess)

using System.Diagnostics;
using System.Runtime.InteropServices;

// Ghostscript PDF merge — subprocess approach
static void MergeWithGhostscript(string[] inputs, string output)
{
    string gs = RuntimeInformation.IsOSPlatform(OSPlatform.Windows)
                    ? "gswin64c.exe"
                    : "gs";

    // Build input file args
    string inputArgs = string.Join(" ", inputs.Select(f => $"\"{f}\""));

    var psi = new ProcessStartInfo
    {
        FileName  = gs,
        Arguments = $"-dNOPAUSE -dBATCH -sDEVICE=pdfwrite " +
                    $"-sOutputFile=\"{output}\" {inputArgs}",
        RedirectStandardOutput = true,
        RedirectStandardError  = true,
        UseShellExecute = false
    };

    using var proc = Process.Start(psi)!;
    proc.WaitForExit();

    if (proc.ExitCode != 0)
    {
        string error = proc.StandardError.ReadToEnd();
        throw new Exception($"Ghostscript exited {proc.ExitCode}: {error}");
    }
}

After (IronPDF)

using IronPdf;

// See: https://ironpdf.com/how-to/merge-or-split-pdfs/
IronPdf.License.LicenseKey = "YOUR_KEY";

static void MergeWithIronPdf(string[] inputs, string output)
{
    var docs = inputs.Select(PdfDocument.FromFile).ToList();
    using var merged = PdfDocument.Merge(docs);
    merged.SaveAs(output);
    foreach (var d in docs) d.Dispose();
}

API Mapping Tables

Namespace Mapping

Ghostscript Approach	IronPDF Equivalent	Purpose
`System.Diagnostics.Process`	`IronPdf` (no subprocess)	Process management → managed API
`Ghostscript.NET.Processor`	`ChromePdfRenderer`	Document processing
`-sDEVICE=pdfwrite` args	`PdfDocument` operations	PDF output device

Core Class/Concept Mapping

Ghostscript Concept	IronPDF Equivalent	Description
`gs` process	`ChromePdfRenderer` / `PdfDocument`	Core processing unit
`-sOutputFile=` arg	`pdf.SaveAs(path)`	Output path
Exit code check	`try/catch (PdfException)`	Error handling
Stdin/file input	`PdfDocument.FromFile(path)`	Document loading

Document Loading

Operation	Ghostscript	IronPDF
Load PDF for processing	Input file arg to process	`PdfDocument.FromFile(path)`
Load from bytes	Temp file + process	`PdfDocument.FromBytes(bytes)`
Load from stream	Temp file + process	`PdfDocument.FromStream(stream)`
HTML to PDF	Not supported	`renderer.RenderHtmlAsPdf(html)`

Page Operations

Operation	Ghostscript CLI	IronPDF
Page count	Parse output or use wrapper	`pdf.PageCount`
Extract page range	`-dFirstPage=N -dLastPage=M`	`pdf.CopyPages(indices)`
Page size	Parse pagesize output	`pdf.Pages[0].Width/Height`
Rotate	`-c "<< /Rotate 90 >> setpagedevice"` (complex)	`page.Rotation = 90`

Merge/Split Operations

Operation	Ghostscript	IronPDF
Merge PDFs	`-sDEVICE=pdfwrite` + multiple input files	`PdfDocument.Merge(docs)`
Split by page range	`-dFirstPage=N -dLastPage=M` per range	`pdf.CopyPages(indices)`

Four Complete Before/After Migrations

1. HTML to PDF

Before (Ghostscript — not applicable)

// Ghostscript does not render HTML to PDF.
// If you have an HTML-to-PDF requirement with Ghostscript in your stack,
// you're likely using a second tool (wkhtmltopdf, headless Chrome, etc.)
// or converting HTML→PostScript→PDF via an intermediate step.

// Ghostscript can convert PostScript to PDF:
// gs -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -sOutputFile=out.pdf in.ps
// But this is PostScript, not HTML.

Console.WriteLine("Ghostscript cannot render HTML; this is new capability in IronPDF");

After (IronPDF)

using IronPdf;

// See: https://ironpdf.com/how-to/html-string-to-pdf/
IronPdf.License.LicenseKey = "YOUR_KEY";

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;

string html = "<html><body><h1>Report</h1><p>Generated via IronPDF.</p></body></html>";
using var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");
Console.WriteLine($"Created {pdf.PageCount} page(s)");

2. Merge PDFs

Before (Ghostscript subprocess)

using System.Diagnostics;
using System.Runtime.InteropServices;

class MergeExample
{
    static void Main(string[] args)
    {
        string[] inputFiles = { "file1.pdf", "file2.pdf", "file3.pdf" };
        string outputFile   = "merged.pdf";

        string gs = RuntimeInformation.IsOSPlatform(OSPlatform.Windows)
                        ? "gswin64c.exe" : "gs";

        // Escape and join input paths
        string inputs = string.Join(" ", inputFiles.Select(f => $"\"{f}\""));

        var psi = new ProcessStartInfo
        {
            FileName  = gs,
            Arguments = $"-dNOPAUSE -dBATCH -sDEVICE=pdfwrite " +
                        $"-dCompatibilityLevel=1.7 " +
                        $"-sOutputFile=\"{outputFile}\" {inputs}",
            RedirectStandardOutput = true,
            RedirectStandardError  = true,
            UseShellExecute        = false
        };

        using var proc = Process.Start(psi)!;
        string stderr = proc.StandardError.ReadToEnd();
        proc.WaitForExit();

        if (proc.ExitCode != 0)
            throw new Exception($"Ghostscript merge failed (exit {proc.ExitCode}): {stderr}");

        Console.WriteLine($"Merged to {outputFile}");
    }
}

After (IronPDF)

using IronPdf;

// See: https://ironpdf.com/how-to/merge-or-split-pdfs/
IronPdf.License.LicenseKey = "YOUR_KEY";

var docs = new[] { "file1.pdf", "file2.pdf", "file3.pdf" }
              .Select(PdfDocument.FromFile)
              .ToList();

using var merged = PdfDocument.Merge(docs);
merged.SaveAs("merged.pdf");
foreach (var d in docs) d.Dispose();
Console.WriteLine($"Merged: {merged.PageCount} pages");

3. Watermark

Before (Ghostscript — PostScript-based, complex)

using System.Diagnostics;
using System.IO;

class WatermarkExample
{
    static void Main(string[] args)
    {
        // Ghostscript watermarking requires injecting PostScript content
        // via a stamp/overlay file — a non-trivial approach

        // Step 1: Create a PostScript watermark file
        string watermarkPs = Path.GetTempFileName() + ".ps";
        File.WriteAllText(watermarkPs, @"
            /watermark {
                gsave
                0.3 setgray
                /Helvetica-Bold 40 selectfont
                200 400 moveto
                45 rotate
                (CONFIDENTIAL) show
                grestore
            } def
        ");

        // Step 2: Apply via Ghostscript — exact args vary
        // This is a simplified illustration; real implementation is more involved
        string gs = System.Runtime.InteropServices.RuntimeInformation
                         .IsOSPlatform(System.Runtime.InteropServices.OSPlatform.Windows)
                         ? "gswin64c.exe" : "gs";

        var psi = new ProcessStartInfo
        {
            FileName  = gs,
            Arguments = $"-dNOPAUSE -dBATCH -sDEVICE=pdfwrite " +
                        $"-sOutputFile=\"watermarked.pdf\" " +
                        $"\"{watermarkPs}\" \"input.pdf\"",
            UseShellExecute = false
        };
        using var proc = Process.Start(psi)!;
        proc.WaitForExit();
        File.Delete(watermarkPs);
    }
}

After (IronPDF)

using IronPdf;
using IronPdf.Editing;

// See: https://ironpdf.com/how-to/custom-watermark/
IronPdf.License.LicenseKey = "YOUR_KEY";

using var pdf = PdfDocument.FromFile("input.pdf");

var stamp = new TextStamper
{
    Text                = "CONFIDENTIAL",
    FontSize            = 40,
    Opacity             = 0.3,
    Rotation            = -45,
    VerticalAlignment   = VerticalAlignment.Middle,
    HorizontalAlignment = HorizontalAlignment.Center
};

pdf.ApplyStamp(stamp);
pdf.SaveAs("watermarked.pdf");

4. Password Protection

Before (Ghostscript)

using System.Diagnostics;
using System.Runtime.InteropServices;

class SecurityExample
{
    static void Main(string[] args)
    {
        string gs = RuntimeInformation.IsOSPlatform(OSPlatform.Windows)
                        ? "gswin64c.exe" : "gs";

        // Ghostscript password protection via -sOwnerPassword / -sUserPassword
        var psi = new ProcessStartInfo
        {
            FileName  = gs,
            Arguments = "-dNOPAUSE -dBATCH -sDEVICE=pdfwrite " +
                        "-dEncryptionR=3 -dKeyLength=128 " +
                        "-sOwnerPassword=owner456 " +
                        "-sUserPassword=user123 " +
                        "-dPermissions=-3904 " +      // permission bitmask — verify values
                        "-sOutputFile=\"protected.pdf\" \"input.pdf\"",
            RedirectStandardError = true,
            UseShellExecute       = false
        };

        using var proc = Process.Start(psi)!;
        proc.WaitForExit();

        if (proc.ExitCode != 0)
            throw new Exception($"Ghostscript encryption failed: {proc.StandardError.ReadToEnd()}");

        Console.WriteLine("Protected PDF created");
    }
}

After (IronPDF)

using IronPdf;
using IronPdf.Security;

// See: https://ironpdf.com/how-to/pdf-permissions-passwords/
IronPdf.License.LicenseKey = "YOUR_KEY";

using var pdf = PdfDocument.FromFile("input.pdf");

pdf.SecuritySettings.UserPassword  = "user123";
pdf.SecuritySettings.OwnerPassword = "owner456";
pdf.SecuritySettings.AllowUserPrinting         = PdfPrintSecurity.FullPrintRights;
pdf.SecuritySettings.AllowUserCopyPasteContent = false;

pdf.SaveAs("protected.pdf");

Critical Migration Notes

Page Indexing

Ghostscript CLI uses 1-based page numbering (-dFirstPage=1). IronPDF uses 0-based indexing. Adjust any page number calculations.

// Ghostscript: -dFirstPage=1 -dLastPage=3 extracts pages 1, 2, 3
// IronPDF equivalent:
int[] pageIndices = { 0, 1, 2 }; // 0-based: first three pages
using var extracted = pdf.CopyPages(pageIndices);

Error Handling: Exit Codes vs Exceptions

Ghostscript returns exit codes; IronPDF raises exceptions. Remove all ExitCode != 0 checks and replace with try/catch.

// Replace exit code checks:
// if (proc.ExitCode != 0) throw new Exception(...)

// With exception handling:
try
{
    using var pdf = PdfDocument.FromFile("input.pdf");
    // operations
}
catch (IronPdf.Exceptions.PdfException ex)
{
    // Structured exception with message, no stderr parsing
    Console.Error.WriteLine(ex.Message);
}

No PostScript Support

IronPDF cannot interpret PostScript (.ps) files. If your pipeline processes .ps input, you have two options: convert PostScript to PDF first (retain Ghostscript for that step only), or restructure the input pipeline to start from HTML/PDF.

Performance Considerations

Subprocess Overhead Elimination

Ghostscript subprocess invocations carry process creation overhead per operation. IronPDF operates in-process. For high-throughput pipelines, this overhead reduction is measurable — but benchmark against your actual workload.

Parallel Processing

Ghostscript parallel processing requires managing multiple processes. IronPDF parallel processing uses Task/Parallel with one ChromePdfRenderer per task:

// See: https://ironpdf.com/examples/parallel/
var results = await Task.WhenAll(
    htmlDocuments.Select(async html =>
    {
        var r = new ChromePdfRenderer();
        using var pdf = await r.RenderHtmlAsPdfAsync(html);
        return pdf.BinaryData;
    })
);

Container Image Size

Removing Ghostscript from Docker images reduces the native dependency footprint. IronPDF adds Chromium binaries. Net effect on image size depends on your Ghostscript version and IronPDF version — measure before and after.

# Before: Ghostscript in Dockerfile
# RUN apt-get update && apt-get install -y ghostscript

# After: remove above line; IronPDF handles Chromium deps automatically

Migration Checklist

Pre-Migration

[ ] Audit all Ghostscript subprocess invocations — list every argument pattern
[ ] Identify PostScript processing (.ps inputs) — these cannot be migrated to IronPDF
[ ] Confirm GPL/AGPL license compliance intent with legal team
[ ] Verify IronPDF covers all required operations (especially rasterization if needed)
[ ] Obtain IronPDF license key; confirm activation
[ ] Review https://ironpdf.com/how-to/license-keys/
[ ] Create migration branch
[ ] Document current Ghostscript version in all environments

Code Migration

[ ] Remove Ghostscript.NET NuGet package (if used)
[ ] Add IronPdf NuGet package
[ ] Replace all Process.Start("gs*") calls
[ ] Replace Ghostscript.NET wrapper calls
[ ] Implement IronPdf.License.LicenseKey initialization at startup
[ ] Replace merge subprocess calls with PdfDocument.Merge(...)
[ ] Replace security subprocess calls with pdf.SecuritySettings
[ ] Replace watermark subprocess/PS calls with TextStamper / ImageStamper
[ ] Replace page index logic: 1-based → 0-based
[ ] Replace exit code checks with try/catch

Testing

[ ] Visual comparison of merged PDFs (page order, content)
[ ] Test password protection roundtrip
[ ] Test watermark rendering on 3+ page types
[ ] Verify page extraction by index (check off-by-one)
[ ] Test concurrent operations under load
[ ] Compare file sizes for compressed outputs
[ ] Verify no gs or gswin64c references remain in code or scripts

Post-Migration

[ ] Remove Ghostscript from all Dockerfiles and provisioning scripts
[ ] Remove Ghostscript from CI/CD runner setup
[ ] Remove Ghostscript license keys or binaries from deployment packages
[ ] Update deployment docs: remove Ghostscript installation steps

Where to Go From Here

The Ghostscript migration is often the most impactful from an architecture perspective, because Ghostscript isn't a .NET library — it's a native binary invoked via subprocess. Replacing it with a managed NuGet package removes an entire category of deployment complexity: binary path resolution, platform-specific process names, stderr parsing for error detection, and native package management in containers.

The capability gaps are real: PostScript interpretation and certain rasterization workflows don't have direct IronPDF equivalents. For those, retaining a minimal Ghostscript deployment or restructuring the pipeline is the honest answer.

A practical question for the comments: when you've audited your Ghostscript subprocess calls, how many distinct argument patterns did you find, and which ones proved hardest to map to a managed library? The range of Ghostscript usage in production .NET applications is wider than most expect.

Nutrient.io vs IronPDF: side by side for .NET teams in 2026

IronSoftware — Fri, 24 Apr 2026 10:30:00 +0000

A supply chain platform needed to generate shipping manifests from HTML templates and let warehouse managers annotate them on tablets. The architect chose Nutrient (then PSPDFKit) because the marketing materials showed both PDF generation and annotation in one package. Two sprints into development, the team realized they'd purchased a Ferrari when they needed a pickup truck.

Nutrient excels at building interactive PDF viewers—think Dropbox's document preview pane or DocuSign's signing interface. Its annotation tools, form-filling UI, and real-time collaboration features power enterprise document workflows at IBM, Disney, and government agencies. What it doesn't do well: generate PDFs from HTML templates at scale without building custom UI.

The supply chain team ended up with two problems: their HTML-to-PDF pipeline required converting content to Nutrient's document model (not a direct HTML string→PDF path), and they were paying for annotation and viewer capabilities their backend batch process would never use. Six months later, they'd factored out the HTML generation into a separate library and kept Nutrient only for the tablet annotation interface.

This isn't a complaint about Nutrient's quality—it's extremely well-built for its intended use case. It's a scope mismatch story. Teams search for ".NET PDF library" expecting HTML-to-PDF tools and land on feature-complete SDKs designed for interactive document experiences. This guide helps you diagnose whether that scope mismatch applies to your requirements.

Understanding IronPDF

IronPDF focuses on one workflow: converting HTML (strings, files, URLs) to PDF documents using an embedded Chromium engine. The API surfaces HTML-to-PDF rendering methods first, with PDF manipulation capabilities (merge, split, watermark, encrypt, extract text) integrated alongside. The design priority is backend document generation—invoice rendering, report exports, automated document assembly—not building PDF viewer interfaces.

No UI components ship with IronPDF. No annotation toolbars. No form-filling widgets. If your requirement is "generate PDF from HTML template and serve it as download," IronPDF matches directly. If your requirement is "embed a PDF viewer where users can highlight text and add comments," you need a viewer SDK like Nutrient.

Key Limitations of Nutrient.io for HTML-to-PDF Workflows

Product Status

Actively maintained (monthly releases) but positioned as PDF viewer/editor SDK, not HTML-to-PDF generator. The .NET offering includes HTML conversion via Processor microservice or client SDK, but this is not the primary documented workflow.

Missing Capabilities (for HTML-to-PDF use cases)

No direct RenderHtmlStringAsPdf(string html) method—conversion typically requires Processor service deployment or document model construction. HTML-to-PDF conversion documented primarily for their cloud Processor API, not the .NET SDK's core workflow. Licensing tailored for interactive viewer applications (per-device/per-user), not batch generation servers.

Technical Issues

Large download footprint (100MB+ for full SDK) when you only need generation. OCR, barcode, imaging, TWAIN scanning bundled even if unused. Steep learning curve for teams expecting simple HTML→PDF API. HTML conversion capabilities exist but require understanding Nutrient's document abstraction layer.

Support Status

Excellent support for viewer/editor scenarios. Support resources heavily skewed toward UI integration (React components, MAUI embedding, iOS/Android views) rather than backend generation workflows. Teams using Nutrient purely for HTML-to-PDF generation often report confusion navigating docs.

Architecture Problems

Modular SDK architecture means picking correct packages for HTML generation isn't obvious. The Processor microservice offers HTML-to-PDF but requires separate Docker deployment. Client SDK can generate PDFs programmatically but API differs from HTML-first libraries. Licensing model doesn't fit "generate 100k invoice PDFs per month" usage pattern—designed for "deploy PDF viewer to 500 end-user devices."

Feature Comparison Overview

Feature	Nutrient.io .NET SDK	IronPDF
Current Status	Active (monthly releases, rebranded from PSPDFKit 2024)	Active development, monthly releases
HTML Support	Via Processor API or SDK conversion	Direct Chromium-based HTML rendering
Rendering Quality	PDFium-based viewer, HTML conversion quality varies	Pixel-perfect HTML5/CSS3/JS rendering
Installation	100MB+ modular SDK, many features	Focused NuGet package, HTML-to-PDF core
Support	Excellent for viewer/editor scenarios	24/5 for generation scenarios
Future Viability	Evolving toward comprehensive document platform	Focused HTML-to-PDF product

Troubleshooting: HTML String Fails to Render Correctly

Problem: Nutrient — HTML Content Doesn't Match Template

Scenario: You pass an HTML invoice template to Nutrient's conversion API expecting a simple render, but CSS Grid layouts collapse, images don't load, or the result doesn't match your browser preview.

Root cause: Nutrient's HTML-to-PDF path is not its primary feature. If using the Processor API, HTML is rendered server-side in that service's environment—CSS/JS execution context differs from your development browser. If using the .NET SDK to construct PDFs, you're working with a document object model, not direct HTML rendering.

Diagnostic steps:

Verify which Nutrient component you're using (Processor API vs .NET SDK programmatic generation)
Check Processor API documentation for HTML conversion limitations
If using SDK, confirm you're not expected to build the document structure from HTML yourself
Test with minimal HTML first: <html><body>Test</body></html> before adding CSS

Workaround (if confirmed limitation):
Convert HTML to Nutrient's document structure using their provided APIs. This often means parsing your HTML and reconstructing layout using Nutrient's drawing/text placement methods—essentially a rewrite of your template logic.

Solution: IronPDF — Direct HTML Rendering

For comprehensive rendering documentation, see Pixel-Perfect HTML to PDF.

using IronPdf;

// Direct HTML to PDF conversion
var renderer = new ChromePdfRenderer();

// CSS Grid and Flexbox work exactly as in Chrome
string htmlContent = @"
    <style>
        .invoice {
            display: grid;
            grid-template-columns: 2fr 1fr;
            gap: 20px;
        }
    </style>
    <div class='invoice'>
        <div>Left column content</div>
        <div>Right column content</div>
    </div>";

var pdf = renderer.RenderHtmlAsPdf(htmlContent);
pdf.SaveAs("invoice.pdf");

Why this works: IronPDF uses Chromium Blink engine—the same renderer as Chrome browser. If your HTML displays correctly in Chrome print preview, IronPDF will match it exactly. No separate conversion layer or document model.

Troubleshooting: PDF Generation Requires Complex Setup

Problem: Nutrient — Deployment Requires Multiple Services

Scenario: Documentation suggests deploying Nutrient Processor as a separate microservice for HTML-to-PDF conversion. Your infrastructure team questions why a PDF library needs Docker deployments and service-to-service calls.

Root cause: Nutrient's architecture separates concerns: client SDKs handle PDF manipulation and viewing; Processor handles conversions (HTML→PDF, Office→PDF, OCR). This makes sense for interactive document applications but adds complexity for simple generation workflows.

Diagnostic steps:

Confirm whether your Nutrient plan includes Processor or only client SDK
Check if .NET SDK offers HTML-to-PDF without Processor
Estimate operational overhead: Docker images, service monitoring, network latency
Calculate licensing costs for Processor instances vs. client SDK usage

Workaround (if Processor required):
Deploy Processor as containerized service. Add health checks, monitoring, and retry logic to your application's PDF generation code. Accept 200-500ms additional latency from service round-trips.

Solution: IronPDF — Single Package, No External Services

using IronPdf;

// Installation: dotnet add package IronPdf
// No external services, no microservices, no containers required

var renderer = new ChromePdfRenderer();

// Entire conversion happens in-process
var pdf = renderer.RenderHtmlAsPdf("<html><body>Content</body></html>");
pdf.SaveAs("output.pdf");

// No network calls, no service dependencies
// Latency: 50-200ms for typical documents

Why this works: IronPDF embeds Chromium engine in the library. All rendering happens in your application's process space. No separate deployments. No service mesh complexity. For complete API reference, see ChromePdfRenderer class documentation.

Troubleshooting: High Memory Usage During Batch Processing

Problem: Nutrient — SDK Memory Footprint Impacts Batch Jobs

Scenario: You're batch-generating 500 PDFs from HTML templates. Memory usage climbs steadily, and the process eventually crashes with OutOfMemoryException after ~200 documents.

Root cause: Nutrient SDK is comprehensive, loading OCR engines, imaging libraries, barcode readers, TWAIN interfaces even if your code only uses PDF generation. The full feature set has memory overhead.

Diagnostic steps:

Profile memory usage: which Nutrient assemblies are loaded?
Check if you're disposing of PDF objects after each generation
Verify whether you need any Nutrient features beyond HTML→PDF
Test if selective package installation reduces footprint (if supported)

Workaround:
Process batches in smaller chunks (50-100 documents), recycling the app domain between chunks. Add aggressive garbage collection. Consider horizontal scaling rather than single-process batching.

Solution: IronPDF — Designed for Batch Processing

using IronPdf;
using System.IO;
using System.Linq;
using System.Threading.Tasks;

// Parallel processing with memory-efficient design
var renderer = new ChromePdfRenderer();
var htmlFiles = Directory.GetFiles("templates/", "*.html");

Parallel.ForEach(htmlFiles, htmlFile =>
{
    using var pdf = renderer.RenderHtmlFileAsPdf(htmlFile);
    pdf.SaveAs(Path.ChangeExtension(htmlFile, ".pdf"));
    // Explicit disposal releases Chromium resources immediately
});

Why this works: IronPDF is designed for batch scenarios. Chromium engine resources are pooled and reused across conversions. Proper disposal patterns prevent memory accumulation. Thread-safe architecture supports parallel execution without overhead multiplication.

Troubleshooting: Licensing Costs Don't Match Usage Pattern

Problem: Nutrient — Viewer-Focused Licensing for Backend Generation

Scenario: You need to generate 50,000 PDFs per month from a batch job that runs on 3 backend servers. Nutrient's licensing is per-device or per-user, designed for interactive viewer deployments.

Root cause: Nutrient's business model targets applications where end users interact with PDFs through viewer interfaces. Pricing reflects "50 users with annotation capabilities" not "50,000 documents generated." For pure backend generation, the licensing math often doesn't favor this SDK.

Diagnostic steps:

Request Nutrient quote specifically for backend batch generation usage
Compare cost per document vs. alternative libraries
Evaluate whether you need Nutrient's viewer/editor features at all
Check if Processor API licensing differs from SDK licensing

Workaround:
Negotiate custom licensing terms for backend generation. Some vendors offer "document transaction" licensing for these scenarios, but verify whether Nutrient supports this model.

Solution: IronPDF — Generation-Focused Licensing

IronPDF licensing is based on developers and deployment servers, not documents generated or end-user counts. A license covers unlimited PDF generation volume. Pricing structure: IronPDF Licensing Options.

using IronPdf;

// Set license once at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

// Generate unlimited PDFs with this license
var renderer = new ChromePdfRenderer();

for (int i = 0; i < 50000; i++)
{
    var pdf = renderer.RenderHtmlAsPdf($"<html><body>Invoice {i}</body></html>");
    pdf.SaveAs($"invoice_{i}.pdf");
    pdf.Dispose();
}

// No per-document costs, no usage tracking, no throttling

Why this works: IronPDF's licensing aligns with backend generation workloads. You pay for developers writing code and servers running it, not for volume generated.

Troubleshooting: CSS/JavaScript Compatibility Issues

Problem: Nutrient — Modern CSS Features Don't Render

Scenario: Your HTML templates use CSS Grid for layout and custom CSS properties (variables). In browser they look perfect. Nutrient-generated PDFs have collapsed layouts or missing styles.

Root cause (requires verification): Nutrient's HTML-to-PDF path may use a different rendering engine than PDFium (their viewer engine). HTML conversion quality depends on whether you're using Processor API (which engine?) or SDK methods (which rendering path?). Official docs needed to confirm current capabilities.

Diagnostic steps:

Verify current Nutrient docs for HTML-to-PDF rendering engine specifications
Test with minimal HTML containing display: grid;
Check Processor API release notes for rendering engine updates
Contact Nutrient support with specific CSS/JS compatibility questions

Workaround:
Rewrite templates using table-based layouts instead of CSS Grid/Flexbox. Avoid CSS variables. Test against whichever rendering engine Nutrient actually uses for your configuration.

Solution: IronPDF — Full Modern Web Standards Support

Complete rendering options reference: ChromePdfRenderOptions documentation.

using IronPdf;

var renderer = new ChromePdfRenderer();

// Modern CSS just works - Chromium Blink engine
string modernHtml = @"
    <style>
        :root {
            --primary-color: #007bff;
            --spacing: 20px;
        }
        .container {
            display: grid;
            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
            gap: var(--spacing);
        }
        .card {
            background: var(--primary-color);
            padding: var(--spacing);
        }
    </style>
    <div class='container'>
        <div class='card'>Card 1</div>
        <div class='card'>Card 2</div>
        <div class='card'>Card 3</div>
    </div>";

var pdf = renderer.RenderHtmlAsPdf(modernHtml);
pdf.SaveAs("modern_layout.pdf");

Why this works: Chromium Blink renderer in IronPDF supports CSS Grid, Flexbox, CSS Variables, Subgrid, Container Queries, and other modern features. If it works in Chrome 120+, it works in IronPDF.

API Mapping Reference

Nutrient.io Concept	IronPDF Equivalent
Processor API HTML conversion	`ChromePdfRenderer.RenderHtmlAsPdf()`
Document object model construction	Direct HTML rendering (no intermediate model)
PDFium viewer rendering	Chromium Blink rendering (for PDF creation)
Annotation UI components	Not applicable (no UI in IronPDF)
Form filling widget	`RenderingOptions.CreatePdfFormsFromHtml = true`
Digital signature UI	`PdfDocument.Sign()` method (programmatic)
Text extraction API	`PdfDocument.ExtractText()`
Page manipulation	`PdfDocument.CopyPage()`, `PdfDocument.RemovePage()`
OCR capabilities	Not included (IronOCR available separately)
Barcode reading	Not included (IronBarcode available separately)
Document collaboration	Not applicable (no real-time features)
Redaction tools	`PdfDocument.RedactTextByRegex()`
Watermarking	`PdfDocument.ApplyWatermark()`

Comprehensive Feature Comparison

Category	Feature	Nutrient.io	IronPDF
Status	Last Update	Monthly releases	Monthly releases
	Maintenance Mode	Active development	Active development
	Primary Focus	Viewer/editor SDKs	HTML-to-PDF generation
Support	Documentation for HTML→PDF	Limited (viewer-focused docs)	Comprehensive generation docs
	Technical Support	Excellent for viewer scenarios	24/5 for generation scenarios
	SLA Available	Yes	Yes (Enterprise)
Content Creation	HTML to PDF	Via Processor or SDK	Direct Chromium rendering
	URL to PDF	Via Processor	Yes with async
	CSS3 Support	Varies by component	Full modern CSS
	JavaScript Support	Varies by component	Full ES2020+
	Custom Fonts	Supported	All formats including WOFF2
	Headers/Footers	Verify current API	Full HTML/CSS headers
	Watermarks	Programmatic API	Built-in
	Page Numbering	Supported	Flexible placeholders
PDF Operations	Merge PDFs	Yes	Yes
	Split PDFs	Yes	Yes
	Extract Text	Yes	Yes
	Extract Images	Yes	Yes
	Fill Forms	Yes	Yes
	Create Forms from HTML	Yes (via UI or programmatic)	Yes
	Digital Signatures	Yes	Yes
	Encryption	Yes	Yes
	Password Protection	Yes	Yes
Interactive Features	Annotation UI	Core feature	Not included
	Form-Filling UI	Core feature	Not included
	Collaboration	Yes	Not applicable
	Viewer Component	Core feature	Not included
Specialized Features	OCR	Yes (built-in)	Separate library (IronOCR)
	Barcode Reading	Yes (built-in)	Separate library (IronBarcode)
	TWAIN Scanning	Yes	Not applicable
	Image Processing	Extensive	Basic
Development	Async/Await Support	Yes	Full async support
	Thread Safety	Yes	Fully thread-safe
	Parallel Processing	Yes	Designed for it
	Docker Support	Processor requires container	Works in containers
	Cross-Platform	Full cross-platform	Full cross-platform
	.NET Version Support	.NET Framework, Core, 6+	.NET Framework, 6-10+

Installation Comparison

Nutrient.io Installation

# Installation varies by feature requirements
# Check current documentation for correct packages
dotnet add package Nutrient.NET.SDK
# Or for specific features:
# dotnet add package GdPicture.NET.14
# (Package names may vary - verify official docs)

using GdPicture14; // or Nutrient namespace - verify docs

// SDK initialization and licensing
// (Specific API calls require current documentation)
GdPictureDocumentConverter converter = new GdPictureDocumentConverter();
// Further usage depends on whether using SDK directly
// or calling Processor API

Nutrient requires reviewing documentation to select appropriate packages for your use case. Full SDK is 100MB+. Processor API requires separate service deployment.

IronPDF Installation

Step-by-step guide: HTML String to PDF Tutorial.

dotnet add package IronPdf

using IronPdf;

// Works immediately, no additional setup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<html><body>Content</body></html>");
pdf.SaveAs("output.pdf");

IronPDF installation is single NuGet package. No external services. No microservice deployments. No complexity beyond standard .NET library usage.

When to Use Nutrient, When to Use IronPDF

Use Nutrient when you're building interactive PDF experiences: document viewers with annotation toolbars, form-filling interfaces, real-time collaboration features, or apps where users need to markup and sign PDFs within your UI. Nutrient excels at these scenarios and provides cross-platform viewer SDKs (Web, iOS, Android, desktop) with consistent APIs.

Use IronPDF when your requirement is backend document generation: rendering invoices from HTML templates, exporting reports to PDF, batch-converting content for archival, or automated document assembly. IronPDF's direct HTML-to-PDF workflow and generation-focused licensing align with these use cases.

The red flag scenario: you're using Nutrient purely for HTML-to-PDF generation without leveraging its viewer/editor capabilities. In these cases, you're paying for features you don't use and working with an SDK optimized for different problems.

The green flag scenario: you need both generation and interactive viewing. Evaluate whether Nutrient's comprehensive approach makes sense or whether combining IronPDF (generation) + a simpler viewer library (PDF.js, browser native) costs less and integrates easier.

For teams generating thousands of PDFs per day from HTML templates with no interactive viewing requirements, IronPDF's focused API and licensing structure typically prove more cost-effective. For teams building document-centric applications where users annotate, sign, and collaborate on PDFs, Nutrient's comprehensive SDK justifies its scope.

Have you hit any of these Nutrient integration pain points? How did you handle the decision between comprehensive PDF SDKs versus focused HTML-to-PDF libraries?

Related resources:

ComPDFKit vs IronPDF: a technical breakdown for 2026

IronSoftware — Fri, 24 Apr 2026 10:29:00 +0000

A software team chose ComPDFKit to build a document management system. The vendor pitch emphasized "comprehensive PDF features" and showed a polished demo with annotations, form filling, and digital signatures working smoothly. Three months into development, marketing requested invoice generation from HTML email templates. The team discovered ComPDFKit's core SDK doesn't include HTML-to-PDF conversion—that requires purchasing the separate HtmlConverter product with its own license. The "comprehensive" toolkit turned out to be a multi-product suite where each capability required evaluation of which component to license.

ComPDFKit is a mature PDF SDK with strong viewer and editor features for building PDF applications. IronPDF is a unified library focused on HTML-to-PDF conversion and programmatic PDF manipulation. This comparison helps teams understand when UI-focused SDKs serve document viewer requirements versus when server-side HTML rendering drives the architecture.

Understanding IronPDF

IronPDF is a .NET library for HTML-to-PDF conversion and PDF manipulation. Install via Install-Package IronPdf—no separate products for HTML rendering versus PDF editing. The ChromePdfRenderer converts HTML using embedded Chromium, while PdfDocument handles merging, splitting, forms, and security. One library, one license, no UI components.

For server-side teams, this means generating PDFs from web content, API responses, or data templates without building viewer interfaces. HTML-to-PDF and PDF manipulation work together in the same namespace.

Key Limitations of ComPDFKit

Product Status

ComPDFKit is actively maintained by PDF Technologies Inc. as a commercial multi-platform SDK. Multiple .NET packages: ComPDFKit v3.0.0 (June 2025), ComPDFKit.NetCore v2.0.0 (May 2024), ComPDFKit.NetFramework v2.2.0 (December 2024). The SDK targets PDF viewer/editor applications with desktop UI focus (WPF SDK for Windows, UWP SDK). Also supports iOS, Android, Web, React Native, Flutter.

Product suite includes: PDF SDK (viewing/editing), Conversion SDK (Office to PDF), HtmlConverter SDK (HTML to PDF—separate product). Each product requires separate licensing and integration.

Missing Capabilities

ComPDFKit's core PDF SDK is designed for building PDF viewer/editor UI applications. It excels at displaying PDFs, adding annotations, form filling, and digital signatures in desktop apps. However, HTML-to-PDF conversion requires the separate HtmlConverter product with additional licensing.

The architectural focus on UI components means teams building server-side PDF generation (invoices from HTML, reports from templates) face integration complexity. HtmlConverter SDK is a separate NuGet package (ceTe.DynamicPDF.HtmlConverter.NET) that must be licensed and integrated alongside the core SDK.

.NET 9/10 support: verify with vendor. NuGet packages list .NET 5-8 compatibility. Native library dependencies (ComPDFKitNative.so on Linux) require deployment alongside .NET assemblies.

Technical Issues

Multi-product complexity: Teams needing both PDF manipulation and HTML rendering must license and integrate multiple ComPDFKit products. Core SDK + HtmlConverter = two separate purchases, two license keys, two sets of documentation. This mirrors patterns seen in other multi-product PDF suites.

UI-first architecture: ComPDFKit SDK includes viewer controls (CPDFViewer) and editor components designed for WPF/UWP desktop applications. Server-side API applications don't need UI controls but must still integrate the SDK's UI-oriented architecture. Teams report (in community forums) navigating around viewer components when only programmatic PDF operations are needed.

License key management: Every ComPDFKit product requires license key verification. Keys are project-specific. Production deployments require managing license files. Trial licenses available but must be obtained through vendor contact.

Support Status

Commercial support from PDF Technologies Inc. Documentation available per product (PDF SDK docs, Conversion SDK docs, HtmlConverter docs separately). Community license offered for startups/individual developers—verify eligibility and limitations with vendor.

Support includes 1v1 technical assistance (per marketing materials). Response times and SLA terms vary by license tier. GitHub repository provides code samples but core SDK is closed-source commercial product.

Architecture Problems

The multi-product strategy creates decision overhead: which SDK for which task, how products integrate, separate licensing per component, version compatibility between products. For teams needing server-side HTML-to-PDF plus PDF manipulation, this means licensing and configuring at least two products (HtmlConverter + PDF SDK) versus a single integrated library.

Desktop UI focus creates deployment surface area for server applications. Viewer controls, annotation toolbars, and UI resources ship with SDK even when building headless API services. Teams must configure which components to load and which to ignore.

Feature Comparison Overview

Aspect	ComPDFKit (SDK + HtmlConverter)	IronPDF
Current Status	Active (v3.0.0, Jun 2025)	Active (regular updates)
HTML Support	HtmlConverter (separate product)	Built-in Chromium
Rendering Quality	Verify with vendor	Chromium (pixel-perfect)
Installation	Multi-package + license keys	Single NuGet package
Support	Commercial (PDF Technologies)	Commercial (Iron Software)
Future Viability	Active (multi-platform focus)	Active

PDF Annotation and Form Filling

ComPDFKit — Viewer-Oriented SDK

using ComPDFKit.PDFDocument;
using ComPDFKit.PDFAnnotation;
using System;
using System.IO;

public class ComPdfKitAnnotator
{
    public byte[] AddAnnotationsAndFillForm(
        string pdfPath,
        Dictionary<string, string> formData)
    {
        // ComPDFKit SDK emphasizes viewer/editor UI workflows
        // API designed for desktop applications with UI controls

        // Step 1: Initialize license (required for all operations)
        // License verification necessary before SDK usage
        // Verify exact API in ComPDFKit documentation

        // Step 2: Load PDF document
        // CPDFDocument class represents PDF file
        CPDFDocument document = CPDFDocument.InitWithFilePath(pdfPath);

        if (document == null)
        {
            throw new Exception("Failed to load PDF document");
        }

        try
        {
            // Step 3: Add text annotation (viewer-style API)
            // Annotations designed for interactive viewing
            var page = document.PageAtIndex(0);

            // Create annotation (API patterns from SDK samples)
            // Exact method names verify in ComPDFKit documentation
            // Typical pattern: create annotation, set properties, add to page

            // Step 4: Fill form fields
            // Form API requires iterating widgets
            // Field identification by name
            foreach (var fieldName in formData.Keys)
            {
                // Field filling pattern (verify API in docs)
                // ComPDFKit uses widget-based form model
                // Must locate field by name, get widget, set value
            }

            // Step 5: Save modified document
            string outputPath = Path.GetTempFileName() + ".pdf";
            bool saved = document.WriteToFilePath(outputPath);

            if (!saved)
            {
                throw new Exception("Failed to save PDF");
            }

            // Step 6: Read file bytes for return
            byte[] pdfBytes = File.ReadAllBytes(outputPath);
            File.Delete(outputPath);

            return pdfBytes;
        }
        finally
        {
            // Step 7: Release document resources
            document.Release();
        }
    }
}

// Usage requires license key configuration
// Contact ComPDFKit for license: https://www.compdf.com/contact-us
var annotator = new ComPdfKitAnnotator();
var formData = new Dictionary<string, string>
{
    { "CustomerName", "Acme Corp" },
    { "InvoiceNumber", "INV-2026-001" }
};

byte[] pdf = annotator.AddAnnotationsAndFillForm("template.pdf", formData);

Technical limitations:

License key required: All SDK operations require valid license verification
File-based operations: Primary APIs work with file paths, not streams
UI-oriented architecture: Designed for viewer applications, not headless servers
Manual resource management: Explicit Release() calls required
Multi-product for complete workflow: HTML conversion requires separate HtmlConverter
Desktop SDK deployment: Viewer controls ship with SDK even for server use

IronPDF — Server-Optimized API

using IronPdf;
using System.Collections.Generic;
using System.Threading.Tasks;

public class IronPdfAnnotator
{
    public async Task<byte[]> AddAnnotationsAndFillFormAsync(
        string pdfPath,
        Dictionary<string, string> formData)
    {
        // Load existing PDF
        using var pdf = PdfDocument.FromFile(pdfPath);

        // Fill form fields
        var form = pdf.Form;
        foreach (var field in formData)
        {
            if (form.Fields.ContainsKey(field.Key))
            {
                form.Fields[field.Key].Value = field.Value;
            }
        }

        // Add text annotation (programmatic, not UI-based)
        pdf.AddTextAnnotation("Review required", 0, 100, 100);

        return pdf.BinaryData;
    }
}

// Usage - no license key in code
var annotator = new IronPdfAnnotator();
var formData = new Dictionary<string, string>
{
    { "CustomerName", "Acme Corp" },
    { "InvoiceNumber", "INV-2026-001" }
};

byte[] pdf = await annotator.AddAnnotationsAndFillFormAsync("template.pdf", formData);

IronPDF uses server-focused APIs: stream-based operations, automatic disposal, no UI controls. See PDF generation settings.

HTML to PDF Conversion Requires Separate Product

ComPDFKit — HtmlConverter SDK Integration

// NOTE: HTML-to-PDF requires ComPDFKit HtmlConverter
// This is a SEPARATE PRODUCT from the core ComPDFKit SDK
// Requires separate licensing and NuGet package
// Package: ceTe.DynamicPDF.HtmlConverter.NET (verify name with vendor)

using System;
using System.IO;

public class ComPdfKitHtmlConverter
{
    public byte[] ConvertHtmlToPdf(string html)
    {
        // HtmlConverter is separate ComPDFKit product
        // Separate purchase, separate license key
        // Installation steps:
        // 1. Contact ComPDFKit for HtmlConverter license
        // 2. Install HtmlConverter NuGet package
        // 3. Configure license key for HtmlConverter
        // 4. Integrate HtmlConverter API (different from PDF SDK API)

        // Exact API pattern: verify in HtmlConverter documentation
        // Typical workflow (conceptual):
        // - Initialize HtmlConverter with license
        // - Configure conversion options
        // - Execute conversion
        // - Retrieve PDF bytes

        throw new NotImplementedException(
            "ComPDFKit HtmlConverter is a separate product. " +
            "Requires separate license and installation. " +
            "Contact ComPDFKit for HtmlConverter licensing: " +
            "https://www.compdf.com/contact-us");
    }
}

// MULTI-PRODUCT ARCHITECTURE IMPLICATIONS:
// - Core ComPDFKit SDK: PDF viewing, editing, annotations → License A
// - ComPDFKit Conversion SDK: Office to PDF → License B
// - ComPDFKit HtmlConverter: HTML to PDF → License C
// Total licensing: negotiate with vendor for multi-product needs
// Integration: configure each product separately
// Deployment: multiple NuGet packages, multiple license keys

Multi-product challenges:

Separate HtmlConverter purchase: Not included in base ComPDFKit SDK
Additional license negotiation: HtmlConverter licensed separately
Multiple API integrations: Learn PDF SDK API + HtmlConverter API
Version coordination: Ensure SDK and HtmlConverter versions compatible
Procurement overhead: Multiple vendor discussions for complete workflow
Deployment complexity: Manage multiple products in production

IronPDF — Integrated HTML Rendering

using IronPdf;
using System.Threading.Tasks;

public class IronPdfHtmlConverter
{
    public async Task<byte[]> ConvertHtmlToPdfAsync(string html)
    {
        var renderer = new ChromePdfRenderer();
        using var pdf = await renderer.RenderHtmlAsPdfAsync(html);
        return pdf.BinaryData;
    }
}

// Usage
var converter = new IronPdfHtmlConverter();
string html = @"
<!DOCTYPE html>
<html>
<head>
    <style>
        body { font-family: Arial; margin: 20px; }
        .invoice { border: 2px solid #333; padding: 20px; }
        table { width: 100%; border-collapse: collapse; margin: 15px 0; }
        th, td { border: 1px solid #ddd; padding: 10px; text-align: left; }
        th { background: #f0f0f0; }
    </style>
</head>
<body>
    <div class='invoice'>
        <h1>Invoice #2026-001</h1>
        <p><strong>Customer:</strong> Acme Corporation</p>
        <table>
            <tr><th>Item</th><th>Amount</th></tr>
            <tr><td>Services</td><td>$1,500.00</td></tr>
            <tr><td>License</td><td>$2,000.00</td></tr>
        </table>
        <p><strong>Total:</strong> $3,500.00</p>
    </div>
</body>
</html>";

byte[] pdf = await converter.ConvertHtmlToPdfAsync(html);
// HTML-to-PDF included in base IronPDF package
// No separate HtmlConverter product needed

IronPDF includes Chromium-based HTML rendering in base package. No additional products to license. See HTML string to PDF guide.

PDF Viewer Controls vs. Programmatic APIs

ComPDFKit — Desktop UI Components

// ComPDFKit SDK architecture focuses on UI viewer controls
// Designed for WPF, UWP desktop applications

using ComPDFKit.Controls.PDFControl;
using System.Windows.Controls;

public class ComPdfKitViewerIntegration
{
    public void IntegrateViewerInDesktopApp(Grid container)
    {
        // ComPDFKit provides CPDFViewer control for WPF apps
        // Rich UI features: toolbar, annotation tools, form filling

        var pdfViewer = new CPDFViewer();

        // Configure viewer properties
        // UI customization: show/hide toolbars, annotation palette
        // Event handlers for user interactions

        container.Children.Add(pdfViewer);

        // Load PDF into viewer
        // Viewer displays PDF with interactive controls

        // SERVER-SIDE CONSIDERATION:
        // API services don't need viewer controls
        // But SDK includes UI components in deployment
        // Teams must work around viewer-focused architecture
        // when building headless PDF processing
    }
}

// ARCHITECTURAL MISMATCH FOR SERVER SCENARIOS:
// - Server APIs generate PDFs programmatically (no UI)
// - ComPDFKit SDK ships with viewer controls and UI resources
// - WPF/UWP dependencies in SDK even for console apps
// - Need to isolate programmatic APIs from UI components
// - Deployment includes viewer assets unused in server context

UI architecture considerations:

Viewer controls included: SDK ships with CPDFViewer for desktop apps
WPF/UWP dependencies: Desktop UI framework requirements
Server deployment overhead: UI components deployed to servers unnecessarily
API isolation needed: Separate viewer features from programmatic APIs
Desktop licensing model: SDK priced for desktop app integration
Documentation emphasis: Heavy focus on viewer customization vs. server APIs

IronPDF — Headless Processing Architecture

using IronPdf;
using System.Threading.Tasks;

public class IronPdfProgrammaticApi
{
    public async Task<byte[]> GenerateInvoiceAsync(InvoiceData data)
    {
        // No UI components - pure programmatic API
        // Designed for server-side PDF generation

        string html = BuildInvoiceHtml(data);

        var renderer = new ChromePdfRenderer();
        using var pdf = await renderer.RenderHtmlAsPdfAsync(html);

        // Add watermark programmatically
        pdf.ApplyWatermark("<h2 style='color:red'>DRAFT</h2>");

        return pdf.BinaryData;
    }

    private string BuildInvoiceHtml(InvoiceData data)
    {
        return $@"
<!DOCTYPE html>
<html>
<head><style>/* CSS */</style></head>
<body>
    <h1>Invoice #{data.InvoiceNumber}</h1>
    <p>Total: ${data.Total}</p>
</body>
</html>";
    }
}

// SERVER-OPTIMIZED:
// - No viewer controls
// - No UI framework dependencies
// - Headless Chromium rendering
// - Stream-based operations
// - Async/await throughout
// - Standard .NET deployment

IronPDF has no UI components. Headless processing for APIs and background jobs. See ChromePdfRenderer API.

API Mapping Reference

ComPDFKit Concept	IronPDF Equivalent
CPDFDocument class	PdfDocument class
InitWithFilePath()	PdfDocument.FromFile()
PageAtIndex()	pdf.Pages[index]
WriteToFilePath()	pdf.SaveAs() or pdf.BinaryData
Release()	Dispose() (automatic with using)
License key verification	License in code or config
CPDFViewer control	N/A (no UI components)
HtmlConverter (separate)	ChromePdfRenderer (built-in)
Conversion SDK (separate)	Built-in conversion
Multi-product suite	Single library
WPF/UWP focus	Server-first architecture
Desktop licensing model	Server/desktop licensing

Comprehensive Feature Comparison

Feature Category	ComPDFKit	IronPDF
Status
Maintenance	Active (v3.0.0, Jun 2025)	Active
Architecture	Multi-product suite	Unified library
Primary Focus	PDF viewer/editor UI	Server-side PDF generation
Support
Commercial Support	PDF Technologies Inc.	Iron Software
Documentation	Per-product docs	Unified documentation
Community License	Startups/individuals	Trial available
Content Creation
HTML to PDF	HtmlConverter (separate)	Built-in Chromium
PDF Viewer UI	CPDFViewer control (WPF/UWP)	N/A (headless only)
Annotations	UI-focused annotation tools	Programmatic annotations
Form Filling	Interactive + programmatic	Programmatic
PDF Operations
Create PDFs	SDK + Viewer	Yes
Merge PDFs	SDK	Yes
Split PDFs	SDK	Yes
Extract Text	SDK	Yes
Digital Signatures	SDK	Yes
Watermarks	SDK	Yes
Encryption	SDK	Yes
Development
.NET Framework	.NET Framework	4.6.2+
.NET Core / .NET 5+	.NET Core 2.1+, .NET 5-8	3.1+ / 5-10
Installation	Multiple NuGet packages	Single NuGet package
License Keys	Required per product	License in code/config
API Style	UI-oriented + programmatic	Server-optimized
UI Components	Included (WPF/UWP)	None

Installation Comparison

ComPDFKit:

# Core PDF SDK
Install-Package ComPDFKit.NetCore
# or for .NET Framework:
Install-Package ComPDFKit.NetFramework

# For HTML-to-PDF, also need HtmlConverter:
# 1. Contact ComPDFKit for HtmlConverter license
# 2. Install HtmlConverter package (verify package name with vendor)
# 3. Configure license keys for each product

# For Office conversion:
# Install-Package ComPDFKit.Conversion.SDK (verify with vendor)

using ComPDFKit.PDFDocument;

// License verification required
// Contact: https://www.compdf.com/contact-us

CPDFDocument document = CPDFDocument.InitWithFilePath("file.pdf");
// ... operations ...
document.Release();

IronPDF:

Install-Package IronPdf
# All features included: HTML-to-PDF, manipulation, forms

using IronPdf;

var renderer = new ChromePdfRenderer();
using var pdf = renderer.RenderHtmlAsPdf("<h1>Hello</h1>");
pdf.SaveAs("output.pdf");

Conclusion

ComPDFKit is a mature multi-platform SDK with 20+ years backing (ceTe Software/PDF Technologies Inc.) serving enterprises that build PDF viewer and editor applications. The SDK excels at desktop PDF applications with rich UI controls, annotation toolbars, and interactive form filling in WPF and UWP environments. For teams building PDF readers, document editors, or annotation tools into Windows desktop apps, ComPDFKit provides comprehensive viewer components.

However, the multi-product architecture creates integration complexity for server-side scenarios: HTML-to-PDF requires the separate HtmlConverter product with additional licensing, Office conversion requires the Conversion SDK, and complete workflows span multiple products with separate license keys and documentation. The UI-focused architecture means server applications deploy viewer controls and desktop dependencies they don't use.

The story that opened this comparison—discovering HTML conversion requires a separate product after licensing the core SDK—reflects a common pattern with multi-product PDF suites. Teams building server-side PDF generation face procurement overhead coordinating multiple licenses and integration complexity managing multiple SDKs.

Migration from ComPDFKit to IronPDF makes sense when:

Primary need is server-side HTML-to-PDF generation (not desktop PDF viewing)
Team prefers unified library over multi-product suite
HtmlConverter licensing adds complexity or cost to ComPDFKit deployment
Desktop UI components unnecessary for headless API services
Simplified procurement (single vendor, single license) reduces administrative overhead
Chromium-based rendering preferred over vendor-specific HTML engine

ComPDFKit serves teams building PDF viewer applications into desktop software. IronPDF serves teams generating PDFs from HTML in server applications. Evaluate based on whether you're building a PDF editor UI or processing PDFs headlessly—the architectures optimize for different use cases.

If you're using ComPDFKit, did you need the HtmlConverter or Conversion SDK? How did multi-product integration work for your team?

Related Resources:

How to prevent Foreign Key crashes with Stripe Webhooks in .NET 10.

Francisco Simões — Fri, 24 Apr 2026 09:53:52 +0000

When integrating Stripe Subscriptions in a .NET application using Entity Framework Core, one of the most common issues developers face is dealing with the checkout.session.completed webhook.

If you have a relational database, you probably have a SubscriptionPlans table and a UserSubscriptions table.

A frequent mistake is forgetting to map the Stripe Price ID back to your internal Database Plan ID when the webhook fires. If you just try to insert the subscription, EF Core will default your Foreign Key to 0, resulting in a nasty Foreign Key constraint violation (Error 500).

Here is the clean way to handle the webhook and map the Stripe Price ID to your internal database ID:

private async Task HandleCheckoutSessionCompleted(Session session)
{
    var userId = session.ClientReferenceId; // We passed this during checkout

    var subscriptionService = new SubscriptionService();
    var stripeSubscription = await subscriptionService.GetAsync(session.SubscriptionId);

    // 1. Extract the Stripe Price ID (price_...) from the invoice items
    var stripePriceId = stripeSubscription.Items.Data.FirstOrDefault()?.Price.Id;

    // 2. Look up the internal Plan ID in your database using the Stripe Price ID
    var plan = await _context.SubscriptionPlans.FirstOrDefaultAsync(p => p.StripePriceId == stripePriceId);

    // 3. Fallback to ID 1 to prevent Foreign Key constraint errors if sync is missing
    int planId = plan != null ? plan.Id : 1; 

    // Now you can safely insert or update your user's subscription record
    var userSubscription = await _context.UserSubscriptions
        .FirstOrDefaultAsync(u => u.UserId == userId);

    if (userSubscription == null)
    {
        userSubscription = new UserSubscription
        {
            UserId = userId,
            StripeSubscriptionId = stripeSubscription.Id,
            StripeCustomerId = stripeSubscription.CustomerId,
            Status = "Active",
            SubscriptionPlanId = planId // Safe to insert!
        };
        _context.UserSubscriptions.Add(userSubscription);
    }

    await _context.SaveChangesAsync();
}

Why this works:
Failsafe mapping: By querying your database for the StripePriceId, you ensure your relational data stays intact.

Fallback: If you forgot to add the plan to your local DB but created it on Stripe, it gracefully falls back to a default plan instead of crashing the API.

Setting up Stripe Webhooks, Identity, and Clean Architecture from scratch usually takes weeks of trial and error.

If you want to skip this headache, I actually packaged my entire setup into a Premium .NET SaaS Boilerplate. It has Authentication, Stripe Billing, the Customer Portal, and EF Core completely wired up and ready for production.

You can grab the code and start building your product today here:
👉 https://s1moes.gumroad.com/l/pdjrrt

Happy coding!

wkhtmltopdf Generates Blank or Empty Output: Causes and Solutions

IronSoftware — Fri, 24 Apr 2026 08:26:00 +0000

Developers using wkhtmltopdf frequently encounter a frustrating issue: the tool completes without error but produces a blank or nearly empty PDF file. The converted document may show only a white page, contain a 2KB file with no content, or display partial rendering with missing sections. This problem has generated hundreds of GitHub issues and Stack Overflow questions, yet many cases remain unresolved because wkhtmltopdf was archived in January 2023 and will never receive fixes for these issues.

The Problem

wkhtmltopdf's blank output problem manifests in several ways. Some users report completely empty PDFs where the file size indicates zero or minimal content. Others see PDFs that render correctly in browsers but produce blank pages when converted. The most frustrating variation involves intermittent failures where the same HTML sometimes works and sometimes produces empty output.

The root cause typically involves timing and rendering synchronization. wkhtmltopdf uses an outdated Qt WebKit rendering engine that predates modern JavaScript execution patterns. When HTML pages load content dynamically through JavaScript or AJAX, wkhtmltopdf often captures the page before that content has finished loading. The tool starts rendering immediately after the initial DOM is constructed, without waiting for asynchronous operations to complete.

This timing issue is compounded by wkhtmltopdf's architecture. Unlike modern browser-based solutions that wait for page load events and network idle states, wkhtmltopdf relies on fixed delays and manual synchronization. The --javascript-delay option exists specifically because the tool cannot intelligently detect when a page is "ready" for conversion.

Error Messages and Symptoms

Blank output rarely produces clear error messages. Common symptoms include:

Exit with code 0 (appears successful, but PDF is empty)
Warning: SSL error ignored
Loading page (1/2)
Printing pages (2/2)
Done (file is blank)

In cases where debugging is enabled:

Warning: SyntaxError: Parse error
(PDF generates but contains no visible content)

When JavaScript console output is enabled:

$ wkhtmltopdf --debug-javascript http://example.com output.pdf
Loading page (1/2)
JavaScript console message: Uncaught ReferenceError: ... is not defined
Printing pages (2/2)
Done

Who Is Affected

The blank PDF issue affects developers across multiple scenarios:

Dynamic Web Applications: Single-page applications built with React, Vue, Angular, or similar frameworks that render content client-side after the initial page load. These applications may show loading spinners or skeleton screens in the PDF instead of actual content.

AJAX-Heavy Pages: Applications that load data through API calls and inject it into the DOM after the initial render. Dashboard applications, reporting systems, and data-driven pages are particularly vulnerable.

Pages with External Resources: HTML that references external stylesheets, fonts, or scripts from CDNs. SSL certificate issues or CORS restrictions can cause silent failures where resources fail to load.

Authentication-Protected Content: Pages behind login walls that redirect unauthenticated requests. wkhtmltopdf may capture the login page instead of the intended content.

Modern CSS Layouts: Pages using Flexbox, CSS Grid, or other modern layout techniques that the outdated WebKit engine cannot render correctly, resulting in elements positioned outside the visible area.

Evidence from the Developer Community

The wkhtmltopdf GitHub repository accumulated thousands of issues related to blank output before being archived. These issues span multiple years and remain unresolved.

Timeline

Date	Event	Source
2016-05-14	"outputing empty pdf" reported	GitHub Issue #2177
2017-01-28	"empty pdf" issue filed with workaround requests	GitHub Issue #2540
2017-07-15	"Empty page at end of PDF" documented	GitHub Issue #3088
2018-01-10	"Empty pdf when saving a website to pdf" reported	GitHub Issue #3086
2018-09-04	"I got an empty PDF document but in browser is normal"	GitHub Issue #3273
2020-06-09	Version 0.12.6 released (final release)	GitHub Releases
2023-01-02	Repository archived, no further fixes	GitHub

Community Reports

"If I try to render an html page served by localhost everything is ok. But if I try to render the same pdf directly from file I obtain an empty pdf."
— Developer, wkhtmltopdf-general mailing list

The distinction between localhost and file-based rendering reveals wkhtmltopdf's inconsistent handling of content origins.

"wkhtmltopdf 0.12.2.4 (with patched qt) on Windows XP can return an empty pdf when converting certain URLs, even though printing from Chrome works fine."
— Issue #2540, GitHub

This demonstrates the rendering gap between wkhtmltopdf's outdated engine and modern browsers.

"Having put in the debug, I can see there's a warning for a parse error in the page's javascript... Blank pages even with a long javascript-delay."
— wkhtmltopdf-general mailing list

JavaScript parsing errors can silently cause blank output without clear indication of the failure cause.

Root Cause Analysis

Blank PDF output from wkhtmltopdf stems from several technical limitations:

1. JavaScript Timing Issues

wkhtmltopdf cannot intelligently wait for JavaScript execution to complete. The --javascript-delay option provides a fixed wait time, but this approach has fundamental problems:

Too short a delay captures the page before content loads
Too long a delay wastes time on fast pages
Network latency variations make any fixed value unreliable
The delay does not respond to actual page readiness

The --window-status option offers an alternative, allowing JavaScript to signal readiness by setting window.status. However, this requires modifying the HTML being converted, which is not always possible.

2. AJAX Content Not Loading

Modern web applications load data asynchronously. A typical pattern:

Initial HTML loads with loading indicators
JavaScript executes and makes API calls
API responses arrive and content is injected into DOM
Page becomes "ready" for viewing

wkhtmltopdf may capture at step 1 or 2, producing a PDF of loading spinners rather than actual content.

3. SSL Certificate Failures

wkhtmltopdf may silently skip HTTPS resources when SSL certificate validation fails:

Warning: SSL error ignored
Failed to load https://cdn.example.com/styles.css

Without stylesheets, the page may render with content positioned off-screen or invisible.

4. Authentication and Redirects

When wkhtmltopdf requests a protected page, the server may redirect to a login page. The resulting PDF contains the login form instead of the expected content. Cookie-based session management is complex to configure correctly.

5. CORS Restrictions

When HTML makes cross-origin requests, wkhtmltopdf may fail to load those resources due to CORS policies that do not account for the tool's unusual request patterns.

6. Missing DOCTYPE Declaration

The absence of <!DOCTYPE html> can cause wkhtmltopdf to enter quirks mode, resulting in unpredictable rendering including blank output.

7. Content Size Zero

If the HTML body contains only absolutely positioned elements or content that flows outside the document bounds, the PDF may appear blank despite technically containing elements.

Attempted Workarounds

The developer community has tried numerous approaches to fix blank output, with varying success.

Workaround 1: Increasing JavaScript Delay

Approach: Use --javascript-delay to wait longer for content to load.

wkhtmltopdf --javascript-delay 5000 http://example.com output.pdf

Limitations:

Arbitrary delay values are unreliable across different pages
Network latency can exceed any fixed delay
Slows conversion significantly for pages that load quickly
Does not address fundamental timing architecture issues

Workaround 2: Window Status Signaling

Approach: Use --window-status combined with JavaScript that signals when the page is ready.

wkhtmltopdf --window-status ready http://example.com output.pdf

With corresponding JavaScript in the page:

window.onload = function() {
    setTimeout(function() {
        window.status = 'ready';
    }, 1000);
};

Limitations:

Requires modifying the HTML being converted
Not applicable when converting external websites
Interaction with --javascript-delay is confusing and poorly documented
Some users report the combination hangs indefinitely

Workaround 3: Using run-script for Timing

Approach: Inject JavaScript to delay rendering.

wkhtmltopdf --run-script 'window.setTimeout(function(){window.status="FOOBAR";},2000);' --window-status 'FOOBAR' http://example.com output.pdf

Limitations:

Complex command-line syntax prone to quoting issues
Fixed timeout still unreliable
Does not wait for actual content loading

Workaround 4: SSL Certificate Bypass

Approach: Ignore SSL errors to load HTTPS resources.

wkhtmltopdf --ssl-protocol any --ignore-ssl-errors http://example.com output.pdf

Limitations:

Security risk in production environments
May not resolve all SSL-related loading issues
Does not address underlying resource loading problems

Workaround 5: Using Xvfb on Headless Servers

Approach: Run wkhtmltopdf with a virtual framebuffer.

xvfb-run wkhtmltopdf http://example.com output.pdf

Limitations:

Adds complexity and dependencies
Does not address JavaScript timing issues
Can cause additional memory and process management problems

A Different Approach: IronPDF

For developers who need consistent PDF output from dynamic web content, IronPDF provides an architectural solution to the blank output problem. Rather than wrapping an external command-line tool with fixed timing mechanisms, IronPDF embeds a Chromium rendering engine that uses the same intelligent page loading detection as modern browsers.

Why IronPDF Avoids Blank Output Issues

The fundamental difference is how IronPDF determines when a page is ready for conversion:

Network Idle Detection: IronPDF waits until network activity settles, ensuring AJAX calls complete before rendering.
Modern Event Handling: The Chromium engine understands DOMContentLoaded, load, and other standard events that signal page readiness.
Intelligent Resource Loading: External stylesheets, fonts, and scripts load through Chromium's standard resource loading pipeline with proper error handling.
JavaScript Compatibility: ES6+, modern frameworks, and asynchronous patterns execute correctly because IronPDF uses a current rendering engine.
Configurable Wait Conditions: Developers can specify wait-for-element conditions or custom JavaScript readiness checks when needed.

Code Example: Handling Dynamic Content

The following example demonstrates converting content that loads dynamically via JavaScript:

using IronPdf;

public class DynamicContentConverter
{
    public byte[] ConvertDynamicPage(string url)
    {
        var renderer = new ChromePdfRenderer();

        // Enable JavaScript execution
        renderer.RenderingOptions.EnableJavaScript = true;

        // Wait for network to become idle (handles AJAX automatically)
        renderer.RenderingOptions.WaitFor.NetworkIdle();

        // Alternative: wait for specific element to appear
        // renderer.RenderingOptions.WaitFor.HtmlElementById("content-loaded");

        // Render the page - Chromium handles timing automatically
        using (var pdf = renderer.RenderUrlAsPdf(url))
        {
            return pdf.BinaryData;
        }
    }
}

This code handles the exact scenarios that cause wkhtmltopdf to produce blank output. The Chromium engine waits for network activity to complete before capturing the page.

Code Example: Converting AJAX-Heavy Dashboard

For applications that load data through multiple API calls:

using IronPdf;

public class DashboardConverter
{
    public void ConvertDashboard(string dashboardUrl, string outputPath)
    {
        var renderer = new ChromePdfRenderer();

        // JavaScript must be enabled for dynamic content
        renderer.RenderingOptions.EnableJavaScript = true;

        // Wait for network idle with extended timeout for multiple API calls
        renderer.RenderingOptions.WaitFor.NetworkIdle(5000);

        // Set viewport to capture full dashboard
        renderer.RenderingOptions.ViewPortWidth = 1920;
        renderer.RenderingOptions.ViewPortHeight = 1080;

        // Render with appropriate paper size
        renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;
        renderer.RenderingOptions.PaperOrientation = IronPdf.Rendering.PdfPaperOrientation.Landscape;

        using (var pdf = renderer.RenderUrlAsPdf(dashboardUrl))
        {
            pdf.SaveAs(outputPath);
        }
    }
}

Code Example: Handling Authenticated Pages

For pages requiring authentication, IronPDF supports cookie injection:

using IronPdf;
using System.Net;

public class AuthenticatedPageConverter
{
    public byte[] ConvertProtectedPage(string url, string sessionCookie)
    {
        var renderer = new ChromePdfRenderer();

        renderer.RenderingOptions.EnableJavaScript = true;
        renderer.RenderingOptions.WaitFor.NetworkIdle();

        // Set authentication cookie
        renderer.RenderingOptions.CustomCookies = new Dictionary<string, string>
        {
            { "session_id", sessionCookie }
        };

        // Alternatively, use HTTP authentication
        // renderer.RenderingOptions.HttpLoginCredentials = new ChromeHttpLoginCredentials
        // {
        //     NetworkUsername = "username",
        //     NetworkPassword = "password"
        // };

        using (var pdf = renderer.RenderUrlAsPdf(url))
        {
            return pdf.BinaryData;
        }
    }
}

Code Example: Converting Local HTML with External Resources

For HTML files that reference external stylesheets and scripts:

using IronPdf;

public class LocalHtmlConverter
{
    public void ConvertLocalHtml(string htmlFilePath, string outputPath)
    {
        var renderer = new ChromePdfRenderer();

        renderer.RenderingOptions.EnableJavaScript = true;
        renderer.RenderingOptions.WaitFor.NetworkIdle();

        // Set base URL for resolving relative resource paths
        var baseUrl = new Uri(htmlFilePath).GetLeftPart(UriPartial.Path);
        baseUrl = baseUrl.Substring(0, baseUrl.LastIndexOf('/') + 1);

        // Read HTML content
        var htmlContent = System.IO.File.ReadAllText(htmlFilePath);

        // Render with base URL context
        using (var pdf = renderer.RenderHtmlAsPdf(htmlContent, baseUrl))
        {
            pdf.SaveAs(outputPath);
        }
    }
}

API Reference

For more details on handling dynamic content and avoiding blank output:

ChromePdfRenderer - Main rendering class
WaitFor Options - Network idle and element detection
HTML to PDF Tutorial - Getting started with conversions
Handling JavaScript Content - JavaScript execution configuration

Migration Considerations

Licensing

IronPDF is commercial software with per-developer licensing. A free trial allows evaluation. Teams should consider the cost of continued debugging and workarounds with wkhtmltopdf against the cost of a maintained solution.

API Differences

Migration from wkhtmltopdf command-line or wrapper libraries requires code changes:

wkhtmltopdf	IronPDF Equivalent
`--javascript-delay 5000`	`RenderingOptions.WaitFor.NetworkIdle()`
`--window-status ready`	`RenderingOptions.WaitFor.JavaScript("window.ready")`
`--enable-javascript`	`RenderingOptions.EnableJavaScript = true`
`--cookie name value`	`RenderingOptions.CustomCookies["name"] = "value"`
`--username --password`	`RenderingOptions.HttpLoginCredentials`
External binary required	Embedded engine (no external dependencies)

What You Gain

Intelligent page load detection eliminates blank output from timing issues
Modern CSS and JavaScript support renders content correctly
Active development means bugs get fixed
Consistent behavior across platforms without native library management
No need to install and configure external binaries

What to Consider

Commercial licensing cost
Different API patterns require code changes
Larger deployment size due to embedded Chromium
Different rendering engine may produce slightly different visual output

Conclusion

wkhtmltopdf's blank output problem stems from fundamental architectural limitations that cannot be fixed through command-line flags or workarounds. The tool's fixed-delay timing mechanism cannot reliably handle modern dynamic web content, and the project's archival in January 2023 means these issues will never be resolved. For teams experiencing blank PDF output, migration to a solution with intelligent page load detection is the path forward.

Jacob Mellor has spent 25+ years building developer tools, including IronPDF as CTO at Iron Software.

References

outputing empty pdf - Issue #2177{:rel="nofollow"} - Early report of empty PDF output
empty pdf - Issue #2540{:rel="nofollow"} - Discussion of blank output causes
Empty page at end of PDF - Issue #3088{:rel="nofollow"} - Trailing blank page problems
Empty pdf when saving a website to pdf - Issue #3086{:rel="nofollow"} - Website conversion failures
I got an empty PDF document but in browser is normal - Issue #3273{:rel="nofollow"} - Browser vs wkhtmltopdf rendering differences
Blank page at the end of pdf document - Issue #4190{:rel="nofollow"} - Landscape orientation blank page issues
javascript-delay versus window-status - Issue #2616{:rel="nofollow"} - Documentation of timing options interaction
Using --window-status and --javascript-delay never returns - Issue #2490{:rel="nofollow"} - Infinite wait issues
wkhtmltopdf does not work using --javascript-delay with plotly.js - Issue #2721{:rel="nofollow"} - JavaScript framework compatibility
PDF Generated is login screen not the route passed - KnpSnappyBundle Issue #120{:rel="nofollow"} - Authentication redirect issues
Redirection Errors? No page or blank page - Issue #2346{:rel="nofollow"} - Redirect handling problems
wkhtmltopdf is now an abandonware - Doppio Documentation{:rel="nofollow"} - Project status assessment
wkhtmltopdf GitHub Repository{:rel="nofollow"} - Archived January 2, 2023

For IronPDF documentation and tutorials, visit ironpdf.com.

Post-Quantum Cryptography

Christian Alt-Wibbing — Fri, 24 Apr 2026 07:58:50 +0000

Why the Future of Encryption Starts Today

I have been developing software for over 20 years but what is happening right now is something interesting. Something that genuinely makes me sit up and pay attention.

Quantum computers are no longer science fiction. And with .NET 10, Microsoft has built the answer directly into the platform: Post-Quantum Cryptography (PQC). Quantum-safe encryption that holds up even when quantum computers become a reality.

In this article, I will walk you through what I understand what that means step by step even if you are just starting out in software development.

1. Why Is This Even a Topic?

Imagine you send a encrypted data today. Someone copy the data without decrypt it and waits. In ten years, they have a tool that can decrypt it. Then they read your data.

That is exactly the scenario keeping security experts around the world up at night. It even has a name: “Harvest Now, Decrypt Later.” Attackers collect encrypted data today and decrypt it later, once quantum computers are powerful enough.

The data most at risk is anything that needs to stay secret for a long time: financial information, health records, long-term contracts. If you work in finance, this is not an abstract problem — it is your reality.

2. What Exactly Are Qubits?

Before we go further, let me explain what we are dealing with. I am not an expert in that topic but here is what I understood.

Classical Computers: Bits
A classical computer knows only two states: 0 or 1. That is called a bit. Everything a computer does — writing text, playing videos, encrypting data. Everything is built on billions of these tiny 0-or-1 decisions.

Quantum Computers: Qubits
A quantum computer works with qubits. Thanks to a quantum phenomenon called superposition, qubits can be 0 and 1 at the same time as long as you do not measure them. That sounds strange (and I’m not scientific enough to explain that :) ), but the effect is enormous.

Analogy: Think of a maze. A classical computer tries every path one by one. A quantum computer tries all paths simultaneously. For certain problems, that is exponentially faster.

The result: for certain mathematical problems, exactly those that uses RSA, ECDSA, a quantum computer, is exponentially faster than a classical one. Our current encryption would be broken.

3. The New Standards — International and Official

The good news: The American NIST (National Institute of Standards and Technology) finalised the first three post-quantum standards in 2024. And this was not an American solo project. 82 algorithms from 25 countries were submitted and reviewed by cryptographers worldwide.

In parallel, ISO/IEC and ETSI (the European Telecommunications Standards Institute) are working on their own frameworks. The IETF is currently integrating PQC into core protocols like TLS. This is a global process .

Algorithm	FIPS Standard	Purpose	Replaces
ML-KEM	FIPS 203	Key Exchange (Key Encapsulation)	ECDH
ML-DSA	FIPS 204	Digital Signatures	RSA / ECDSA
SLH-DSA	FIPS 205	Digital Signatures (hash-based)	RSA / ECDSA

4. What Does .NET 10 Do with This?

.NET 10 released in November 2025 as a Long-Term Support (LTS) release — brings these algorithms directly into the familiar System.Security.Cryptography namespace.

No external NuGet package, no third-party library. Just there, ready to use.

As a .NET developer, you now find these new classes:
• MLKem
• MLDsa
• SlhDsa

Even X509Certificate2has been extended: certificates can now contain PQC keys. This is important for TLS and PKI infrastructures.

5. The Hybrid Approach — The Best of Both Worlds

I would advise against switching everything over to PQC overnight. In my experience, new developments need time to prove themselves first. The PQC algorithms are mathematically well-founded and approved by NIST – but they have not yet proven themselves to the same level as RSA, which has been in use for decades.

The solution: the hybrid approach. You combine a classical algorithm (e.g. ECDH) plus ML-KEM simultaneously. If one algorithm is broken, the other still protects you. You are secured against both classical and quantum attacks.

Hybrid = classical algorithm + PQC in parallel. Secure against both attack types.

.NET 10 also supports *Composite ML-DSA * which is a combination of a classical and a post-quantum algorithm in a single signature. This is the recommended transition path.

6. What Does This Mean for Your Project?

Let me be honest: if you have services today that do not encrypt data at all, that is more urgent than PQC. Post-quantum only protects encrypted communication. If data is flowing in plain text, the best quantum algorithm in the world will not help.
My recommended order of priority:

Priority	Action	When
1	Enable TLS for all services, Kafka, RabbitMQ	Today
2	New services directly with ML-KEM + AES (Hybrid)	During .NET 10 migration
3	Migrate internal services to PQC	When both sides are under your control
4	Switch certificates to PQC	When CA + infrastructure are ready

7. What About the IdentityServer?

Many projects use Duende IdentityServer for authentication — with JWT tokens signed using RS256 (RSA + SHA-256). That is exactly the algorithm a quantum computer could break.
The goal: add ML-DSA as an additional signing algorithm — alongside RS256, not as a replacement. Why alongside? Because older clients expect RS256 and do not yet understand ML-DSA.

⚠️ Important:
Duende IdentityServer must explicitly support ML-DSA. This is a dependency outside your control. Keep an eye on the Duende roadmap!

8. My Personal Conclusion

After years of software development, I have learned: the biggest security problems do not arise from missing technology but they come from acting too late. PQC is not a “someday” topic. It is a “prepare now” topic.

.NET 10 makes it easy for us: the algorithms are there, they are standardised, they are internationally recognised. The entry point is manageable. And anyone currently migrating to .NET 10 has the perfect opportunity to incorporate PQC at the same time, no extra overhead.

Start with what matters most: encrypt first. Then think about PQC. And then you will be ready for what is coming.

Sources & Further Reading

• Post-Quantum Cryptography in .NET — .NET Blog (Microsoft)
• .NET 10: Post-Quantum Cryptography Comes to .NET — Anthony Giretti
• NIST Releases First 3 Finalized Post-Quantum Encryption Standards
• ML-KEM and ML-DSA Post-Quantum Cryptography in .NET — Strathweb
• Post-Quantum Cryptography — NIST (international adoption)
• What’s new in .NET 10 — Microsoft Learn

What 2 Years as a Developer Actually Feels Like (Not the TikTok Version)

Emma Hall — Fri, 24 Apr 2026 07:22:04 +0000

I've been a software developer for 2 years now and going by the "day in the life" videos on TikTok, you'd think I should feel confident by now.

I don't. Yet.

Most days still involve second guessing my technical decisions, worrying I'm not progressing fast enough, and quietly hoping nobody notices.

The Reality

It's easy to spiral into overthinking and let the imposter syndrome take over.

Is this actually a good way to code this?
Will the next person think “what idiot wrote this”?
Am I too slow? Other developers seem to finish tasks faster than me.
Should I know more than I do at this point?

That constant background noise can get loud. Sometimes it's hard to think about anything other than mistakes I've made.

Are people keeping track of how many bugs I've released to production? Do they think I'm bad at my job?

The paranoid part of my brain says yes.

The pragmatic part knows that every developer creates bugs. Being “good” at this job isn’t about never getting things wrong. It’s about how you deal with it when you do.

I'm still learning, and most of that learning has come from messing things up and figuring out how to fix it. Every bug or mistake is something to look back on and ask what would I do differently next time?

What I'm starting to realise is confidence doesn’t just show up when you hit a certain number of years or tick off a specific goal. It’s something you have to build on purpose.

I'm not going to wake up one random Tuesday and suddenly feel confident in my abilities. If I want that, I have to actually practice it.

What I'm trying

I'm trying to be more vocal.

In meetings, if I have an answer or an idea, I say it - even if I’m not 100% sure, even if my instinct is to stay quiet and wait for someone else to speak first. Half the time, someone ends up saying what I was thinking anyway, so I may as well be the one to say it.

I've started tracking a “Win of the Week”.

I've made a Trello board with a list dedicated to this. Some weeks the wins might be big, like doing well in a performance review. Other weeks might be something smaller, like speaking up in a meeting or suggesting an idea for a feature.

Normally I’d brush those off, thinking they are insignificant and don't deserve recognition. But writing them down makes it harder to ignore or dismiss them. It’s proof that I am making progress, even if it doesn’t always feel like it. And even if they are small steps forward - a small step forward is still closer to the end destination than if I had stayed still the whole time.

I'm also trying to be more intentional with my goals. Breaking things down into smaller milestones that feel more manageable, means I have a roadmap of my journey to the goal that I can tick off on my way. This helps me with staying motivated, and, honestly it feels good to see things moving forward instead of feeling stuck.

Key Takeaways

I need to stop using other people as my benchmark. Someone being better than me at something doesn’t automatically mean I’m bad at it. It usually just means they’ve had more time or experience with it. Instead of letting that spiral, I’m trying to see it as a chance to learn from them.
If nothing changes, nothing changes. I’ve spent a lot of time waiting and hoping to feel more confident, like it would just come with time. And while I am learning more as I go, I wouldn't say that I feel anymore confident than when I knew a fraction of what I do now. Something needs to change, which is what I'm doing now.

So, no, my experience isn't like the polished, aesthetic “day in the life” version you see online. It’s messier, more internal, and a lot more about getting out of your own head than I expected.

But I’m starting to realise that’s probably a normal part of it. And perhaps I'm not the only one having these kinds of realisations.

DEV Community: dotnet

Global Exception Handling in ASP.NET Core — The Complete Guide

Why You Need Global Exception Handling

Approach 1: UseExceptionHandler Middleware

Approach 2: IExceptionHandler (.NET 8+)

Approach 3: Exception Filter (MVC only)

ProblemDetails — RFC 7807

Custom Domain Exceptions

Logging Exceptions

Interview-Ready Summary

How I Built GPU-Accelerated Frosted Glass and Acrylic Blur for .NET MAUI (And Why Every Other Library Gets It Wrong)

Why not just stay on the GPU the whole time?

Two views, that's it

Install

What's supported

Why I actually built this

Why .NET interviews feel harder than they should

Migrating from jsreport to IronPDF: no fuss, no fluff

Architecture difference — this matters first

Why migrate (without drama)

Comparison table

Migration complexity assessment

Effort by feature

Decision matrix

Before you start

Prerequisites

Find jsreport references in your codebase

Remove jsreport client, install IronPDF

Quick start migration (3 steps)

Step 1: License configuration

Step 2: Namespace imports

Step 3: Basic PDF generation

API mapping tables

Namespace mapping

Core class mapping

Document loading methods

Page operations

Merge/split operations

Four complete before/after migrations

1. HTML to PDF

2. Merge PDFs

3. Watermark

4. Password protection

Critical migration notes

Template engine migration

jsreport.Local (embedded mode)

Service removal

Page indexing

Performance considerations

Eliminate HTTP round trip

Renderer reuse in ASP.NET

Async rendering

Azure / cloud deployment

Edge cases worth flagging

Migration checklist

Pre-migration

Code migration

Testing

Post-migration

Conclusion

wkhtmltopdf Memory Leak and High Memory Usage (Issue Fixed)

The Problem

Error Messages and Symptoms

Who Is Affected

Evidence from the Developer Community

Timeline

Community Reports

Root Cause Analysis

Attempted Workarounds

Workaround 1: Disable JavaScript and Images

Workaround 2: Increase Container Memory Limits

Workaround 3: Process Isolation and Restart

Workaround 4: Document Chunking

A Different Approach: IronPDF

Why IronPDF Has Different Memory Characteristics

Code Example

API Reference

Migration Considerations

Licensing

API Differences

Approach 1: `UseExceptionHandler` Middleware

Approach 2: `IExceptionHandler` (.NET 8+)