DEV Community: IronSoftware

From pdforge to IronPDF: what actually changes in your code

IronSoftware — Tue, 28 Apr 2026 15:57:00 +0000

The version pin has been in the .csproj for eleven months. The changelog for the newer version lists three security patches and a breaking API change in the watermarking module — the exact module you use. You've been putting off the assessment, but the project is going through a dependency review this quarter and "pinned to an old version with known CVEs" is going to be a red flag in the audit report.

You have two options: update pdforge and deal with the breaking changes, or swap to a different library. This article covers the second path — migrating from pdforge to IronPDF — so you have concrete code to evaluate before making the call.

Troubleshooting: security patch version pins

The version pin scenario creates a specific audit trail. Here's how to assess it systematically before writing migration code:

Step 1: Understand what changed in the newer version

# If pdforge has a public changelog or GitHub releases:
# Read the changelog for every version between your pin and current

# Check NuGet for version history:
dotnet nuget show package pdforge --source nuget.org

# Alternatively:
# Browse https://www.nuget.org/packages/pdforge

Step 2: Assess the breaking change scope in your codebase

# Find all watermark-related usage (if the breaking change is in watermarking):
rg "Watermark\|stamp\|overlay" --type cs -n -i | grep -i pdforge

# Count total pdforge call sites:
rg "pdforge\|pdForge" --type cs -n -i | wc -l

# If < 20 call sites, the within-library upgrade may be faster than migration
# If > 50, migration and upgrade are comparable effort

Step 3: Make the upgrade vs migrate decision

Factor	Points to upgrade	Points to migrate
Breaking change scope	Only watermark API changed	Multiple APIs changed
Call site count	< 20 affected call sites	> 50 affected call sites
Pinned version age	< 3 months	> 9 months
Missing features	Current features sufficient	Missing PDF/A, signatures, etc.
Maintenance signal	Active, responsive	Slow, unanswered issues
Secondary library count	0	2+ added to supplement

If this analysis points to migration, proceed. If it points to upgrade, do the upgrade instead — don't migrate when an upgrade is the right call.

Why migrate (without drama)

Eight neutral reasons the version pin analysis tips toward migration:

Cascading breaking changes — if you stayed pinned through multiple releases, catching up now means dealing with all accumulated API changes at once.
Security advisory — CVEs in a pinned PDF library with no clear fix timeline are a genuine risk signal.
Secondary library accumulation — if you've added PdfSharp, iTextSharp, or other libraries to fill gaps, consolidation during a forced migration makes sense.
API quality — if the watermarking change reflects a broader pattern of instability in the API surface, that's a long-term maintenance risk.
HTML/CSS rendering gaps — verify whether pdforge's renderer keeps pace with CSS standards. Modern templates may not render correctly.
Maintenance trajectory — a library that frequently introduces breaking changes requires ongoing maintenance overhead.
Feature roadmap — if PDF/A, digital signatures, or other enterprise features are in your backlog, verify whether pdforge's roadmap covers them.
.NET version future-proofing — verify pdforge's .NET 8/9 compatibility as you plan runtime upgrades.

Comparison table

Aspect	pdforge	IronPDF
Focus	Verify — PDF gen + manipulation	HTML-to-PDF + PDF manipulation
Pricing	Verify at pdforge.com	Commercial — verify at ironsoftware.com
API Style	Verify	In-process .NET library
Learning Curve	Verify	Medium
HTML Rendering	Verify rendering engine	Chromium-based
Page Indexing	Verify	0-based
Thread Safety	Verify	Renderer instance reuse
Namespace	Verify	`IronPdf`

Migration complexity assessment

Effort by feature

Feature	pdforge approach	Effort to migrate
HTML string to PDF	Verify	Low
URL to PDF	Verify	Low
HTML file to PDF	Verify	Low
Watermark (breaking change)	Verify — with breaking change	Low (clean API in IronPDF)
Merge PDFs	Verify	Low
Password protection	Verify	Low
Custom margins	Verify	Low
Headers / footers	Verify	Medium
PDF/A compliance	Verify	Low in IronPDF
Digital signatures	Verify	Medium
Async rendering	Verify	Medium

Decision matrix

Scenario	Recommendation
Version pin is primary trigger, small scope	Assess upgrade vs migration; upgrade may be faster
Multiple breaking changes accumulated	Migration effort comparable to upgrade; evaluate fresh
Secondary libraries added to supplement pdforge	Migration consolidates; removes dependency tree
Security CVE requires urgent action	Fastest path first — upgrade if clear, migrate if not

Before you start

Prerequisites

.NET 6+ target
pdforge changelog reviewed for all versions between your pin and current
Count of affected call sites documented

Find pdforge references in your codebase

# Find all pdforge usage
rg -l "pdforge\|pdForge\|PdForge" --type cs -i

# Find using statements
rg "using pdforge\|using PdForge" --type cs -n

# Find watermark-related usage (the breaking-change module)
rg "Watermark\|WatermarkOption\|AddWatermark" --type cs -n | grep -i pdforge

# Find all class instantiation — replace class names after verifying docs
rg "new.*Pdf.*Converter\|new.*PdForge\|new.*pdforge" --type cs -n -i

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

Remove pdforge, install IronPDF

# Remove pdforge — verify exact package name
dotnet remove package pdforge   # replace with actual package name

# Install IronPDF
dotnet add package IronPdf
dotnet restore

Quick start migration (3 steps)

Step 1: License configuration

Before (pdforge — verify license setup):

// pdforge license initialization — verify exact method in documentation
// using pdforge; // verify namespace

// Pattern is illustrative — verify before use:
// pdForgeLicense.SetKey("YOUR_PDFORGE_KEY"); // hypothetical
// or: no license key if open source — verify

After (IronPDF):

using IronPdf;

// Set once at application startup
IronPdf.License.LicenseKey = "YOUR_IRONPDF_LICENSE_KEY";
// License guide: https://ironpdf.com/how-to/license-keys/

Step 2: Namespace imports

Before:

// Verify actual namespaces from pdforge documentation
using pdforge;              // verify
using pdforge.Watermark;    // verify — may be different
using pdforge.Options;      // verify

After:

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

Step 3: Basic HTML-to-PDF

Before (pdforge — verify all API names):

using System;
using System.IO;
// using pdforge; // verify namespace

class BasicConversionExample
{
    static void Main()
    {
        // VERIFY: All class names, constructor signatures, and method names
        // below are placeholders. Consult pdforge documentation.

        // Typical HTML-to-PDF library pattern:
        // pdForgeLicense.SetKey("YOUR_KEY");         // verify
        // var converter = new PdfConverter();         // verify class name
        // var options = new PdfOptions                // verify
        // {
        //     PageSize = "A4",                        // verify property
        //     MarginTop = 10                          // verify type
        // };
        // byte[] pdf = converter.FromHtml(html, options); // verify method

        Console.WriteLine("Replace with verified pdforge API");
    }
}

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/

Troubleshooting: the watermark breaking change specifically

If the watermark API is the breaking change that triggered the version pin, here's the IronPDF equivalent that gives you a clean starting point:

IronPDF watermark API (stable)

using IronPdf;
using IronPdf.Editing;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

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

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

// Image watermark:
// var imageStamper = new ImageStamper("watermark.png");
// imageStamper.Opacity = 20;
// pdf.ApplyStamp(imageStamper);
// Guide: https://ironpdf.com/how-to/stamp-text-image/

Apply to specific pages only

// Watermark only the first page:
pdf.ApplyStamp(textStamper, 0);

// Watermark pages 2–4 (0-based):
for (int i = 1; i <= 3; i++)
    pdf.ApplyStamp(textStamper, i);

Troubleshooting: API surface mapping when pdforge docs are unclear

When migrating from a pinned version, the documentation for your old version and the current version may both be available. Check both:

# If pdforge has versioned docs, find the version for your pin:
# Look for: /docs/v2.x/ or similar

# Check if your installed version has XML documentation:
find ~/.nuget -name "pdforge*.xml" 2>/dev/null

Map each call site systematically before writing migration code:

# Export all pdforge call sites to a file for systematic mapping:
rg "pdforge\|PdForge" --type cs -n > pdforge_call_sites.txt
cat pdforge_call_sites.txt | wc -l
# Now map each line to an IronPDF equivalent before touching code

API mapping tables

Namespace mapping

pdforge	IronPDF	Notes
`pdforge`	`IronPdf`	Core
Watermark namespace	`IronPdf.Editing`	Stamp/watermark
Options namespace	`IronPdf.Rendering`	Render config

Core class mapping

pdforge class	IronPDF class	Description
Converter class	`ChromePdfRenderer`	HTML-to-PDF
Options class	`ChromePdfRenderOptions`	Render config
Watermark class	`TextStamper` / `ImageStamper`	Watermarking
Document class	`PdfDocument`	PDF model

Document loading methods

Operation	pdforge	IronPDF
HTML string	Verify	`renderer.RenderHtmlAsPdf(html)`
URL	Verify	`renderer.RenderUrlAsPdf(url)`
HTML file	Verify	`renderer.RenderHtmlFileAsPdf(path)`
Existing PDF	Verify	`PdfDocument.FromFile(path)`

Page operations

Operation	pdforge	IronPDF
Paper size	Verify	`ChromePdfRenderOptions.PaperSize`
Margins	Verify	`ChromePdfRenderOptions.Margin*`
Orientation	Verify	`ChromePdfRenderOptions.PaperOrientation`
Page count	Verify	`pdf.PageCount`

Merge/split operations

Operation	pdforge	IronPDF
Merge	Verify	`PdfDocument.Merge(pdf1, pdf2)`
Split	Verify	`pdf.CopyPages(startIndex, endIndex)`

Four complete before/after migrations

1. HTML to PDF

Before (pdforge — structural placeholder; verify all names):

using System;
using System.IO;
// using pdforge; // verify namespace

class HtmlToPdfExample
{
    static void Main()
    {
        // VERIFY: All class and method names before implementing
        // Replace every placeholder with verified pdforge API calls

        // Example pattern (not verified):
        // pdForgeLicense.SetKey("YOUR_KEY");          // verify
        // var options = new PdfRenderOptions           // verify class name
        // {
        //     PageSize = PdfPageSize.A4,              // verify enum
        //     MarginTopMm = 10,                       // verify property
        //     MarginBottomMm = 10                     // verify
        // };
        // var generator = new PdfGenerator(options);  // verify
        // byte[] pdf = generator.FromHtml(            // verify method
        //     "<html><body><h1>Invoice</h1></body></html>"
        // );
        // File.WriteAllBytes("invoice.pdf", pdf);

        Console.WriteLine("Replace with verified pdforge API");
    }
}

After (IronPDF):

using IronPdf;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.PaperSize    = IronPdf.Rendering.PdfPaperSize.A4;
renderer.RenderingOptions.MarginTop    = 10;
renderer.RenderingOptions.MarginBottom = 10;
renderer.RenderingOptions.MarginLeft   = 15;
renderer.RenderingOptions.MarginRight  = 15;

var pdf = renderer.RenderHtmlAsPdf(
    "<html><body><h1>Invoice #1234</h1><p>Amount: $500</p></body></html>"
);
pdf.SaveAs("invoice.pdf");
// Rendering options: https://ironpdf.com/how-to/rendering-options/

2. Merge PDFs

Before (pdforge — verify API; secondary library if not native):

using System;
// Verify: does pdforge support merge? If not, PdfSharp pattern:
using PdfSharp.Pdf;
using PdfSharp.Pdf.IO;

class MergePdfsExample
{
    static void Main()
    {
        // VERIFY: pdforge merge API before using this secondary pattern
        using var output = new PdfDocument();

        foreach (string path in new[] { "part1.pdf", "part2.pdf" })
        {
            using var input = PdfReader.Open(path, PdfDocumentOpenMode.Import);
            foreach (PdfPage page in input.Pages)
                output.AddPage(page);
        }

        output.Save("merged.pdf");
        Console.WriteLine("Merged.");
    }
}

After (IronPDF):

using IronPdf;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

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

3. Watermark (the breaking-change module)

Before (pdforge watermark — the version that broke; verify actual API):

using System;
using System.IO;
// using pdforge;
// using pdforge.Watermark; // verify — may have changed in newer version

class WatermarkExample
{
    static void Main()
    {
        // VERIFY: This is the module that has a breaking change
        // Your pinned version uses one API; newer version uses another
        // Verify the API for your specific pinned version

        // Old watermark pattern (hypothetical — verify):
        // var options = new WatermarkOptions        // verify class name
        // {
        //     Text = "DRAFT",                       // verify property
        //     Opacity = 0.3f,                       // verify
        //     Angle = 45                            // verify
        // };
        // pdfDoc.AddWatermark(options);             // verify method name

        Console.WriteLine("Replace with verified pdforge watermark API for your version");
    }
}

After (IronPDF — stable watermark API):

using IronPdf;
using IronPdf.Editing;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

var pdf = PdfDocument.FromFile("input.pdf");
var stamper = new TextStamper
{
    Text = "DRAFT",
    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 (pdforge — verify security API):

using System;
// using pdforge; // verify namespace

class SecurityExample
{
    static void Main()
    {
        // VERIFY: pdforge security API — class names and method signatures
        // Pattern is a placeholder:

        // Hypothetical:
        // var security = new PdfSecurity           // verify class name
        // {
        //     UserPassword  = "readonly",           // verify property name
        //     OwnerPassword = "admin",              // verify
        //     AllowPrinting = true                  // verify
        // };
        // pdfDoc.ApplySecurity(security);           // verify method

        Console.WriteLine("Replace with verified pdforge security API");
    }
}

After (IronPDF):

using IronPdf;
using IronPdf.Security;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

var pdf = PdfDocument.FromFile("input.pdf");
pdf.SecuritySettings.UserPassword  = "readonly";
pdf.SecuritySettings.OwnerPassword = "admin";
pdf.SecuritySettings.AllowUserPrinting = PdfPrintSecurity.FullPrintRights;
pdf.SecuritySettings.AllowUserCopyPasteContent = false;
pdf.SaveAs("secured.pdf");
// Guide: https://ironpdf.com/how-to/pdf-permissions-passwords/

Critical migration notes

Page indexing

IronPDF uses 0-based page indexing. Verify pdforge's convention in the version you're migrating from:

// IronPDF: 0-based
var firstPage = pdf.Pages[0];
var lastPage  = pdf.Pages[pdf.PageCount - 1];

Output model

Verify whether pdforge returns byte[] or a document object. IronPDF returns PdfDocument:

// IronPDF PdfDocument to byte[]:
var pdf = renderer.RenderHtmlAsPdf(html);

using var ms = new MemoryStream();
pdf.Stream.CopyTo(ms);
byte[] pdfBytes = ms.ToArray();
// Memory stream: https://ironpdf.com/how-to/pdf-memory-stream/

Error handling

Replace status-code or null-return error patterns with exception handling:

try
{
    var pdf = renderer.RenderHtmlAsPdf(html);
    pdf.SaveAs("output.pdf");
}
catch (IronPdf.Exceptions.IronPdfException ex)
{
    _logger.LogError(ex, "PDF render failed: {msg}", ex.Message);
    throw;
}

Performance considerations

Renderer reuse

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

foreach (var html in documentQueue)
{
    using var pdf = renderer.RenderHtmlAsPdf(html);
    pdf.SaveAs($"doc_{Guid.NewGuid()}.pdf");
}

Async

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

Edge cases worth flagging

Version pin in CI: Update any PackageReference version constraints in .csproj files — don't just remove the package.
Transitive dependencies: If pdforge pulled in other packages, check whether any are still needed after migration.
Lock file: Run dotnet restore and commit the updated packages.lock.json if using locked restores.

Migration checklist

Pre-migration

[ ] Document pdforge breaking change scope in your codebase
[ ] Count call sites: rg "pdforge" --type cs -n | wc -l
[ ] Make upgrade vs migrate decision (see decision table above)
[ ] Identify secondary libraries (PdfSharp, iTextSharp) added to supplement pdforge
[ ] Verify IronPDF .NET target framework compatibility
[ ] Confirm commercial license requirements internally
[ ] Set up IronPDF trial license in dev environment
[ ] Pull all HTML templates for render comparison

Code migration

[ ] Remove pdforge NuGet package
[ ] Remove secondary libraries (if supplementing pdforge only)
[ ] Add IronPdf NuGet package
[ ] Replace pdforge namespace imports
[ ] Replace license initialization
[ ] Replace HTML-to-PDF calls with ChromePdfRenderer
[ ] Replace watermark operations (the breaking-change module)
[ ] Replace merge, security operations
[ ] Update output handling from byte[] to PdfDocument model
[ ] Add IronPDF license key to config

Testing

[ ] Render each HTML template and visually compare output
[ ] Test watermark specifically — this was the breaking-change area
[ ] Test merge with representative document sets
[ ] Test password protection (correct and wrong credentials)
[ ] Verify no CVE-flagged packages remain in dotnet list package
[ ] Load test concurrent rendering at expected peak
[ ] Regression test all PDF-generating endpoints

Post-migration

[ ] Remove pdforge license key from config
[ ] Remove secondary libraries from project if no longer needed
[ ] Update dependency audit documentation
[ ] Monitor first production week for any render regression

Wrapping Up

The version pin scenario has an underappreciated upside: you're doing a full feature audit at a forced migration point, which often reveals that secondary libraries can be removed and the dependency tree can be simplified. Whether you upgrade or migrate, that audit is worth doing.

What edge cases did you hit that this article didn't cover? Particularly interested in teams where the breaking change was in a module other than watermarking — what was the specific API change, and was the upgrade path clearer than the migration path?

From Kaizen.io to IronPDF: what actually changes in your code

IronSoftware — Tue, 28 Apr 2026 13:57:00 +0000

The version pin in your .csproj has been sitting at 2.x for eight months. A security advisory came through, the fix landed in 3.x, and the upgrade path involves breaking API changes you haven't had time to assess. Meanwhile the rest of the stack has moved to .NET 8 and the old package doesn't play cleanly with the new runtime. You're not looking for a migration out of enthusiasm — you're looking for a path forward.

This article maps the code changes needed to move from Kaizen.io PDF generation to IronPDF. The mapping tables and checklist are useful reference material regardless of which library you end up choosing.

Why migrate (without drama)

Version pinning and upgrade friction are common triggers, but they're rarely the only one. Here are 9 neutral reasons teams evaluate a PDF library switch:

Version lock — security or compatibility fixes land in a version that requires breaking API changes. The cost of staying starts to exceed the cost of switching.
Runtime incompatibility — older libraries built for .NET Framework or early .NET Core may not work correctly on .NET 6/8 targets.
Maintenance signal — slowing commit cadence, unanswered GitHub issues, or no roadmap communication.
NuGet package deprecation — if the package is marked deprecated or abandoned on NuGet, your supply chain tooling will start flagging it.
Deployment constraints — libraries with native binary dependencies become friction in Docker, Azure, or CI/CD environments as those environments evolve.
HTML/CSS fidelity — if the rendering engine doesn't keep pace with CSS standards, templates start to drift visually.
Missing features — PDF/A compliance, digital signatures, merge/split, or watermarking absent from the current library.
API verbosity — accumulated boilerplate from a library that wasn't designed for your primary use case.
Commercial support requirements — teams needing SLA-backed support may need a library with an enterprise support tier.

Comparison table

Aspect	Kaizen.io	IronPDF
Focus	Verify — document/PDF tooling	HTML-to-PDF + full PDF manipulation
Pricing	Verify at kaizen.io	Commercial — verify at ironsoftware.com
API Style	Verify — library vs HTTP client	In-process .NET library
Learning Curve	Verify	Medium
HTML Rendering	Verify rendering engine	Chromium-based
Page Indexing	Verify	0-based
Thread Safety	Verify	Renderer instance reuse — see async docs
Namespace	Verify	`IronPdf`

Migration complexity assessment

Effort by feature

Feature	Kaizen.io approach	Effort to migrate
HTML string to PDF	Verify	Low (if supported)
URL to PDF	Verify	Low
HTML file to PDF	Verify	Low
Merge PDFs	Verify	Low (native in IronPDF)
Watermark	Verify	Low
Password protection	Verify	Low
Custom margins	Verify	Low
Headers / footers	Verify	Medium
Async rendering	Verify	Medium
Digital signatures	Verify	Medium — verify IronPDF signing API
PDF/A compliance	Verify	Low in IronPDF if needed

Decision matrix

Scenario	Recommendation
Version upgrade path blocked, .NET 8 required	Evaluate in-process alternatives; IronPDF or open-source options
Open source requirement	IronPDF is commercial; evaluate PuppeteerSharp, wkhtmltopdf wrappers
Core use case is HTML-to-PDF only, no manipulation	Both may work — verify Kaizen.io's HTML fidelity against your templates
Need merge, watermark, encryption in one library	IronPDF consolidates these; avoids adding secondary libraries

Before you start

Prerequisites

.NET 6+ target framework
NuGet access or offline package cache
Full inventory of Kaizen.io features in active use (critical before removing it)

Find Kaizen.io references in your codebase

# Find all files referencing Kaizen — adjust namespace/class names after verifying docs
rg -l "Kaizen\|kaizen" --type cs -i

# Find using statements
rg "using Kaizen" --type cs -n

# Find class instantiation — replace KaizenClient with actual class name
rg "KaizenClient\|KaizenPdf\|KaizenRenderer" --type cs -n

# Find NuGet package references in project files
grep -r -i "kaizen" **/*.csproj *.csproj 2>/dev/null

Remove Kaizen.io, install IronPDF

# Remove Kaizen package — verify exact package name on NuGet first
dotnet remove package Kaizen.Pdf   # replace with actual package name

# Install IronPDF
dotnet add package IronPdf

# Restore
dotnet restore

On Windows PowerShell via Package Manager Console: Install-Package IronPdf and Uninstall-Package Kaizen.Pdf (replace with actual package name).

Quick start migration (3 steps)

Step 1: License configuration

Before (Kaizen.io — verify license initialization in docs):

// Kaizen.io license setup — verify exact method and class names in official docs
// Pattern below is illustrative; do not use without verification
using Kaizen.Pdf; // verify namespace

// Verify whether Kaizen requires license initialization and how
// KaizenLicense.SetKey("YOUR_KEY"); // hypothetical — verify before use

After (IronPDF):

using IronPdf;

// Set once at application startup
IronPdf.License.LicenseKey = "YOUR_IRONPDF_LICENSE_KEY";
// License guide: https://ironpdf.com/how-to/license-keys/

Step 2: Namespace imports

Before:

// Verify actual namespaces from Kaizen.io documentation
using Kaizen.Pdf;        // verify
using Kaizen.Pdf.Options; // verify — may not exist

After:

using IronPdf;
using IronPdf.Rendering;  // for ChromePdfRenderOptions
using IronPdf.Editing;    // for stamping/watermark
using IronPdf.Security;   // for passwords

Step 3: Basic HTML-to-PDF

Before:

// IMPORTANT: The code below uses placeholder names.
// Verify every class, method, and property name against actual Kaizen.io documentation
// before using this in production.

using System;
// using Kaizen.Pdf; // verify namespace

class BasicConversionExample
{
    static void Main()
    {
        // Verify: class name, constructor, method names
        // var converter = new KaizenPdfConverter(); // hypothetical
        // var result = converter.ConvertFromHtml("<h1>Hello</h1>"); // hypothetical
        // File.WriteAllBytes("output.pdf", result); // hypothetical

        // Replace above with actual Kaizen.io API — verify in docs
        Console.WriteLine("Verify Kaizen.io API before implementing");
    }
}

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

Kaizen.io	IronPDF	Notes
`Kaizen.Pdf`	`IronPdf`	Core namespace
Options namespace	`IronPdf.Rendering`	Render configuration
N/A	`IronPdf.Editing`	Manipulation — stamp, annotate

Core class mapping

Kaizen.io class	IronPDF class	Description
Converter class	`ChromePdfRenderer`	PDF generation entry point
Options/settings class	`ChromePdfRenderOptions`	Render configuration
Document class	`PdfDocument`	Represents a loaded/rendered PDF
N/A	`PdfDocument` static methods	Merge, split, load from file

Document loading methods

Operation	Kaizen.io	IronPDF
HTML string	Verify method name	`renderer.RenderHtmlAsPdf(html)`
URL	Verify method name	`renderer.RenderUrlAsPdf(url)`
HTML file	Verify method name	`renderer.RenderHtmlFileAsPdf(path)`
Existing PDF	Verify method name	`PdfDocument.FromFile(path)`

Page operations

Operation	Kaizen.io	IronPDF
Page count	Verify	`pdf.PageCount`
Paper size	Verify	`ChromePdfRenderOptions.PaperSize`
Margins	Verify	`ChromePdfRenderOptions.Margin*`
Orientation	Verify	`ChromePdfRenderOptions.PaperOrientation`

Merge/split operations

Operation	Kaizen.io	IronPDF
Merge	Verify	`PdfDocument.Merge(pdf1, pdf2)`
Split	Verify	`pdf.CopyPages(startIndex, endIndex)`

Four complete before/after migrations

Note on "Before" blocks: Because Kaizen.io's API cannot be verified from public documentation at the time of writing, the Before blocks show structural patterns common to PDF libraries in this category, with explicit verification reminders. Replace every method and class name with the actual Kaizen.io API before using.

1. HTML to PDF

Before (structural pattern — verify all names against Kaizen.io docs):

using System;
using System.IO;
// using Kaizen.Pdf; // uncomment and verify namespace

class HtmlToPdfExample
{
    static void Main()
    {
        // VERIFY: All class names, method signatures, and option properties
        // below are placeholders. Do not ship without consulting Kaizen.io docs.

        // Step 1: Instantiate converter — verify class name
        // var converter = new KaizenConverter(); // hypothetical

        // Step 2: Configure options — verify option class and properties
        // var options = new KaizenOptions
        // {
        //     PaperSize = "A4",              // verify property name and value type
        //     MarginTop = "10mm",            // verify
        //     MarginBottom = "10mm",         // verify
        // };

        // Step 3: Convert — verify method signature
        // byte[] pdfBytes = converter.HtmlToPdf(
        //     "<html><body><h1>Invoice</h1></body></html>",
        //     options
        // );

        // Step 4: Save output
        // File.WriteAllBytes("invoice.pdf", pdfBytes);
        Console.WriteLine("Replace placeholder code with actual Kaizen.io API");
    }
}

After (IronPDF):

using IronPdf;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

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

var pdf = renderer.RenderHtmlAsPdf(
    "<html><body><h1>Invoice #1234</h1><p>Amount: $500</p></body></html>"
);
pdf.SaveAs("invoice.pdf");
// Full guide: https://ironpdf.com/how-to/html-string-to-pdf/

2. Merge PDFs

Before:

using System;
using System.IO;
// If Kaizen.io doesn't support merge natively, teams typically add PdfSharp or similar

// PdfSharp pattern (common workaround — verify if applicable):
// using PdfSharp.Pdf;
// using PdfSharp.Pdf.IO;

class MergePdfsExample
{
    static void Main()
    {
        // VERIFY: Does Kaizen.io support PDF merge natively?
        // If yes — use their API (verify class/method names)
        // If no — a secondary library is typically added

        // Common PdfSharp workaround pattern:
        // using var output = new PdfDocument();
        // foreach (var path in new[] { "part1.pdf", "part2.pdf" })
        // {
        //     using var input = PdfReader.Open(path, PdfDocumentOpenMode.Import);
        //     foreach (PdfPage page in input.Pages)
        //         output.AddPage(page);
        // }
        // output.Save("merged.pdf");

        Console.WriteLine("Verify Kaizen.io merge API or secondary library before implementing");
    }
}

After (IronPDF native merge):

using IronPdf;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

var pdf1 = PdfDocument.FromFile("part1.pdf");
var pdf2 = PdfDocument.FromFile("part2.pdf");
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("merged.pdf");
// Guide: https://ironpdf.com/how-to/merge-or-split-pdfs/

3. Watermark

Before:

using System;
using System.IO;
// using iTextSharp.text;        // common secondary library
// using iTextSharp.text.pdf;

class WatermarkExample
{
    static void Main()
    {
        // VERIFY: Does Kaizen.io support watermarking natively?
        // If not, iTextSharp PdfStamper pattern is common:

        // using var reader = new PdfReader("input.pdf");
        // using var fs = new FileStream("watermarked.pdf", FileMode.Create);
        // using var stamper = new PdfStamper(reader, fs);
        // var font = BaseFont.CreateFont(BaseFont.HELVETICA_BOLD, BaseFont.CP1252, false);
        // var cb = stamper.GetOverContent(1);
        // cb.BeginText();
        // cb.SetFontAndSize(font, 50);
        // cb.SetColorFill(new BaseColor(200, 200, 200));
        // cb.ShowTextAligned(Element.ALIGN_CENTER, "DRAFT", 300, 400, 45);
        // cb.EndText();

        Console.WriteLine("Verify Kaizen.io watermark API before implementing");
    }
}

After (IronPDF):

using IronPdf;
using IronPdf.Editing;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

var pdf = PdfDocument.FromFile("input.pdf");
var stamper = new TextStamper
{
    Text = "DRAFT",
    FontColor = IronSoftware.Drawing.Color.LightGray,
    FontSize = 50,
    Opacity = 40,
    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:

using System;
using System.IO;
// using iTextSharp.text.pdf; // common secondary library if not native

class SecurityExample
{
    static void Main()
    {
        // VERIFY: Does Kaizen.io support PDF encryption natively?
        // If not, iTextSharp pattern is typical:

        // byte[] userPass = System.Text.Encoding.ASCII.GetBytes("userpass");
        // byte[] ownerPass = System.Text.Encoding.ASCII.GetBytes("ownerpass");
        // using var reader = new PdfReader("input.pdf");
        // using var fs = new FileStream("secured.pdf", FileMode.Create);
        // using var stamper = new PdfStamper(reader, fs, '\0', false);
        // stamper.SetEncryption(userPass, ownerPass,
        //     PdfWriter.ALLOW_PRINTING, PdfWriter.ENCRYPTION_AES_128);

        Console.WriteLine("Verify Kaizen.io security API before implementing");
    }
}

After (IronPDF):

using IronPdf;
using IronPdf.Security;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

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

Critical migration notes

Page indexing

IronPDF uses 0-based page indexing. Verify Kaizen.io's page indexing convention in its documentation, then audit all page index references in your code:

// IronPDF: 0-based
var firstPage = pdf.Pages[0]; // first page
var lastPage  = pdf.Pages[pdf.PageCount - 1]; // last page

Output model difference

Many PDF libraries return byte[] from conversion. IronPDF returns a PdfDocument object. Update call sites that expect raw bytes:

// If your code expected byte[] from Kaizen.io:
// byte[] pdfBytes = converter.Convert(html); // old pattern

// IronPDF returns PdfDocument — save or stream as needed:
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");

// Or to MemoryStream:
// https://ironpdf.com/how-to/pdf-memory-stream/
using var ms = new MemoryStream();
pdf.Stream.CopyTo(ms);
byte[] pdfBytes = ms.ToArray();

Error handling

IronPDF throws exceptions on failure. If Kaizen.io returned status codes or null on error, update your error handling:

try
{
    var pdf = renderer.RenderHtmlAsPdf(html);
    pdf.SaveAs("output.pdf");
}
catch (IronPdf.Exceptions.IronPdfException ex)
{
    // Log render failure
    Console.Error.WriteLine($"Render failed: {ex.Message}");
}

Performance considerations

Renderer reuse

// Instantiate once, reuse for batch work
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;

foreach (var html in templates)
{
    using var pdf = renderer.RenderHtmlAsPdf(html);
    pdf.SaveAs($"output_{Guid.NewGuid()}.pdf");
}

Concurrent rendering

// Separate renderer per thread — don't share across concurrent operations
Parallel.ForEach(htmlBatch, html =>
{
    var renderer = new ChromePdfRenderer();
    using var pdf = renderer.RenderHtmlAsPdf(html);
    pdf.SaveAs($"{Guid.NewGuid()}.pdf");
});
// Parallel examples: https://ironpdf.com/examples/parallel/

Disposal

// PdfDocument implements IDisposable
using var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");
// Auto-disposed at end of block

Edge cases

Cold start: Chromium-based renderers have a startup cost. In serverless or per-request scaling scenarios, the first render will be slower. Pre-warm if latency is critical.
Font availability: System fonts must be present on the render server. Verify font availability in Docker images.
Memory: Profile under production-representative load before sizing containers.

Migration checklist

Pre-migration

[ ] Verify Kaizen.io NuGet package name and exact version in use
[ ] Review Kaizen.io changelog — understand what changed between your pinned version and current
[ ] Decide: upgrade within Kaizen.io vs switch — document the rationale
[ ] Inventory all Kaizen.io API calls in use: rg "Kaizen\|kaizen" --type cs -i
[ ] Identify any secondary libraries added to supplement Kaizen.io (merge, watermark, security)
[ ] Verify IronPDF .NET target framework compatibility
[ ] Confirm commercial license requirements internally
[ ] Set up IronPDF trial license in dev environment

Code migration

[ ] Remove Kaizen.io NuGet package
[ ] Add IronPdf NuGet package
[ ] Replace Kaizen.io using directives with using IronPdf etc.
[ ] Replace license initialization
[ ] Replace HTML-to-PDF calls with ChromePdfRenderer
[ ] Replace URL-to-PDF calls
[ ] Replace merge operations (native in IronPDF — remove secondary library if used only for this)
[ ] Replace watermark operations
[ ] Replace password/security operations
[ ] Update output handling from byte[] to PdfDocument model where needed

Testing

[ ] Render each HTML template and visually compare output
[ ] Verify page count matches expected for multi-page documents
[ ] Test merge with representative document sets
[ ] Test watermark on single-page and multi-page documents
[ ] Test password protection with correct and incorrect credentials
[ ] Test async/concurrent rendering at expected peak load
[ ] Regression test all PDF-generating endpoints

Post-migration

[ ] Remove Kaizen.io license key from config / secrets management
[ ] Remove secondary libraries no longer needed
[ ] Update deployment documentation
[ ] Monitor memory and CPU in first production week

Final Thoughts

The variability in this migration depends almost entirely on how much of Kaizen.io's API surface your code touches and whether there's a secondary library doing the manipulation work. Single-concern codebases (HTML-to-PDF only) migrate in a few hours. Codebases where manipulation features are scattered across multiple libraries take longer to consolidate.

What edge cases did you hit in this migration that the article didn't cover? Particularly interested in teams who had Kaizen.io integrated into background job pipelines or report scheduling systems — those setups have extra steps not covered here.

Migrating from CraftMyPDF to IronPDF: a practical .NET migration guide

IronSoftware — Tue, 28 Apr 2026 12:56:00 +0000

Migrating off a cloud PDF service is architecturally different from migrating between two .NET libraries. You're not swapping a NuGet package — you're moving from an HTTP dependency to a local process, which changes your latency profile, cost model, data residency posture, and offline availability.

This article gives you the checklists and code to move from CraftMyPDF (cloud API) to IronPDF (local .NET library). The migration is worth doing when network latency matters, when data leaving your environment is a compliance concern, or when per-API-call cost adds up at scale. It's less clearly worth it if templates change frequently and you value CraftMyPDF's visual editor.

Work through the checklists in order. The pre-migration phase matters here more than in library-to-library migrations because you're changing the fundamental execution model.

Why Migrate (Without Drama)

CraftMyPDF solves a real problem — PDF generation without running PDF infrastructure. The friction appears when requirements change:

Data residency / compliance — PDF content (customer PII, financial data) leaves your network with every API call. Some compliance frameworks prohibit or complicate this.
Network latency — Each PDF generation round-trips to CraftMyPDF's servers. For low-latency or high-volume scenarios, this adds measurable delay.
API cost at scale — Cloud services price per operation. Above a threshold, local rendering is cheaper. Calculate your current API call volume × rate.
Offline / air-gapped environments — CraftMyPDF requires internet access. Air-gapped servers, offline modes, or edge deployments can't use cloud APIs.
Vendor dependency risk — API changes, service outages, or pricing changes from a third-party affect your application.
Template flexibility — CraftMyPDF templates are managed in their UI. Complex dynamic logic (conditional sections, loops, computed fields) requires their template language rather than full C# control flow.
CI/CD test environment — Integration tests that hit a live cloud API are slower and fragile. Local rendering makes tests hermetic.
Response time SLA — If PDF generation is in a synchronous request path, cloud round-trip adds to your p99 latency.
Custom fonts and assets — Managing font assets in a cloud template system can be less flexible than local filesystem access.
On-premises deployment requirements — Some enterprise environments prohibit cloud service dependencies in production workloads.

Comparison Table

Aspect	CraftMyPDF	IronPDF
Focus	Cloud template PDF generation	Local HTML-to-PDF, edit, merge, security
Pricing	Per-API-call or subscription	Per-developer or royalty-free
API Style	REST/HTTP with JSON template data	.NET method calls
Learning Curve	Simple for template-driven; limited for complex logic	Gradual; HTML/CSS knowledge transfers directly
HTML Rendering	Verify CraftMyPDF renderer	Chromium-based
Page Indexing	N/A (cloud output)	0-based
Thread Safety	N/A (stateless HTTP)	Renderer reusable; verify thread safety docs
Namespace	HttpClient (no local SDK)	`IronPdf`

Migration Complexity Assessment

Effort by Feature

Feature	Effort	Notes
Simple HTML-to-PDF	Low	Replace HTTP call with local renderer
Template-driven PDF (data injection)	Medium	Replace JSON template with HTML + C# string interpolation or Razor
Merge PDFs	Medium	CraftMyPDF may handle this server-side; need local merge code
Watermark	Medium	New capability to implement locally
Password protection	Low	New capability; simple API
Complex conditional templates	High	Rebuild logic in C# / Razor
Batch generation at scale	Medium	Test local throughput vs API throughput
Test environment hermeticity	Low	Tests no longer need network access
Error handling model	Medium	HTTP errors → .NET exceptions

Decision Matrix

Business Scenario	Recommendation
Data residency is a compliance requirement	Local rendering strongly worth evaluating
API cost is significant and growing	Calculate break-even point; local often cheaper at scale
Offline or air-gapped deployment	Cloud API is not viable; local rendering required
Template managed by non-developers	CraftMyPDF's UI is a genuine advantage; evaluate migration cost

Pre-Migration Checklist

Complete every item before writing migration code.

Understand Current Usage

[ ] List all CraftMyPDF API endpoints your app calls (typically create-pdf, create-image, download, others)
[ ] Count monthly API calls — check your CraftMyPDF dashboard
[ ] Identify all templates in CraftMyPDF — screenshot or export their layouts
[ ] Document each template: what data fields does it accept? What's the output format?
[ ] Identify which templates have complex logic (conditionals, loops, computed values)
[ ] Note any custom fonts or image assets uploaded to CraftMyPDF
[ ] Document current average response times for API calls (check APM or logs)

Compliance and Data Review

[ ] Identify what data is sent in API payloads (PII, financial, health data?)
[ ] Confirm data residency requirements with your compliance/security team
[ ] Document current data handling — does CraftMyPDF retain data? Check their privacy policy.
[ ] If data residency is a driver, confirm IronPDF processes all data locally (it does — verify current docs)

Cost Analysis

[ ] Export current monthly API call volume from CraftMyPDF dashboard
[ ] Calculate current monthly API cost
[ ] Estimate IronPDF license cost for your developer count
[ ] Estimate hosting cost if scaling PDF generation (CPU/memory for Chromium renderer)
[ ] Calculate break-even point: (IronPDF license + infra) vs CraftMyPDF API cost

Technical Inventory

[ ] Find all HttpClient calls to CraftMyPDF API: rg "craftmypdf\|craftmypdf\.com" --type cs -l
[ ] Find all template IDs referenced in code: rg "template_id\|templateId" --type cs
[ ] Find all JSON data structures sent to CraftMyPDF (these become your HTML template variables)
[ ] Identify the deployment environment (Windows, Linux, cloud) for IronPDF compatibility check
[ ] Confirm .NET version: dotnet --version

Setup Checklist

Install IronPDF

[ ] Add package: dotnet add package IronPdf
[ ] Restore: dotnet restore
[ ] Set license key in config (never hardcode in source):

  # appsettings.json or environment variable
  # IronPdf__LicenseKey or IRONPDF_LICENSE_KEY

[ ] Configure license in Program.cs / Startup.cs:

  IronPdf.License.LicenseKey = builder.Configuration["IronPdf:LicenseKey"];

[ ] Verify license: Console.WriteLine(IronPdf.License.IsValidLicense);

Linux / Container Setup (if applicable)

[ ] Install native dependencies):

  RUN apt-get update && apt-get install -y \
      libgdiplus libx11-6 libc6 libgtk-3-0 libxcomposite1 libxdamage1 \
      libxrandr2 libgbm1 libxkbcommon0 libasound2

[ ] Test PDF generation in target container before writing full migration

Quick Start Migration (3 Steps)

Step 1 — License Configuration

Before (CraftMyPDF — HTTP call pattern):

// No local license — auth via API key in HTTP headers
private const string CRAFTMYPDF_API_KEY = "YOUR-CRAFTMYPDF-KEY";
private const string CRAFTMYPDF_BASE_URL = "https://api.craftmypdf.com/v1/";

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-KEY", CRAFTMYPDF_API_KEY);

After (IronPDF):

using IronPdf;

// Set once at startup — https://ironpdf.com/how-to/license-keys/
IronPdf.License.LicenseKey = Environment.GetEnvironmentVariable("IRONPDF_LICENSE_KEY");

Step 2 — Remove HTTP Client PDF Generation

Before (CraftMyPDF request pattern):

using System.Net.Http.Json;

// Data model matching CraftMyPDF template fields
var payload = new
{
    template_id = "YOUR-TEMPLATE-ID",
    data = new { name = "Alice", amount = 1200, due = "2025-12-01" }
};

var response = await httpClient.PostAsJsonAsync($"{CRAFTMYPDF_BASE_URL}create-pdf", payload);
response.EnsureSuccessStatusCode();

After (IronPDF):

using IronPdf;

var renderer = new ChromePdfRenderer();
using var pdf = renderer.RenderHtmlAsPdf(GetInvoiceHtml("Alice", 1200, "2025-12-01"));

Step 3 — Template Conversion Pattern

Replace CraftMyPDF JSON templates with C# HTML generation:

// Template method replacing CraftMyPDF template ID
static string GetInvoiceHtml(string name, decimal amount, string due) => $@"
<!DOCTYPE html>
<html>
<head>
    <style>
        body {{ font-family: Arial, sans-serif; padding: 40px; }}
        h1 {{ color: #2563EB; }}
        .amount {{ font-size: 24px; font-weight: bold; }}
    </style>
</head>
<body>
    <h1>Invoice for {System.Net.WebUtility.HtmlEncode(name)}</h1>
    <p class='amount'>Amount: ${amount:F2}</p>
    <p>Due: {due}</p>
</body>
</html>";

For Razor-based applications, use partial views instead of string interpolation.

Code Migration Checklist

[ ] Replace HttpClient CraftMyPDF calls with ChromePdfRenderer.RenderHtmlAsPdf()
[ ] Create HTML template methods for each CraftMyPDF template ID in use
[ ] Transfer custom fonts from CraftMyPDF to local filesystem or embedded resources
[ ] Replace CraftMyPDF image assets with local paths or embedded base64 in HTML
[ ] Implement error handling: HTTP errors become try/catch on IronPDF calls
[ ] Remove CraftMyPDF API key from configuration/secrets
[ ] Remove HttpClient setup code specific to CraftMyPDF
[ ] Replace any CraftMyPDF merge API calls with PdfDocument.Merge()
[ ] Implement local watermarking if CraftMyPDF templates included watermarks
[ ] Implement local password protection if required
[ ] Remove CraftMyPDF SDK/wrapper NuGet package if one was used

Four Complete Before/After Migrations

1. HTML to PDF (API Call → Local Render)

Before (CraftMyPDF API call):

using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

class Program
{
    private static readonly HttpClient _http = new HttpClient();
    private const string API_KEY = "YOUR-CRAFTMYPDF-KEY";
    private const string BASE_URL = "https://api.craftmypdf.com/v1/";

    static async Task Main()
    {
        _http.DefaultRequestHeaders.Add("X-API-KEY", API_KEY);

        // Template ID and data sent to CraftMyPDF cloud
        var payload = new
        {
            template_id = "abc123",  // your template ID
            data = new
            {
                customer_name = "Alice Smith",
                invoice_number = "INV-2071",
                amount = 1200.00,
                due_date = "2025-12-01"
            },
            export_type = "json",
            expiry = 10
        };

        // Round-trip to CraftMyPDF servers
        var response = await _http.PostAsJsonAsync($"{BASE_URL}create-pdf", payload);
        response.EnsureSuccessStatusCode();

        var result = await response.Content.ReadFromJsonAsync<CraftMyPdfResult>();
        // Download the PDF from their CDN
        var pdfBytes = await _http.GetByteArrayAsync(result.file);
        await System.IO.File.WriteAllBytesAsync("invoice.pdf", pdfBytes);
        Console.WriteLine("Invoice downloaded from CraftMyPDF");
    }
}

record CraftMyPdfResult(string file, string status);

After (IronPDF local render):

using System;
using IronPdf;

class Program
{
    // Reuse renderer — don't create per-request
    private static readonly ChromePdfRenderer _renderer = new ChromePdfRenderer();

    static void Main()
    {
        IronPdf.License.LicenseKey = "YOUR-KEY";

        // No network call — renders locally with Chromium
        // https://ironpdf.com/how-to/html-string-to-pdf/
        string html = BuildInvoiceHtml("Alice Smith", "INV-2071", 1200.00m, "2025-12-01");
        using var pdf = _renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("invoice.pdf");
        Console.WriteLine("Invoice generated locally");
    }

    static string BuildInvoiceHtml(string name, string invoiceNum, decimal amount, string due) =>
        $@"<!DOCTYPE html><html><body style='font-family:Arial;padding:40px'>
            <h1>Invoice {System.Net.WebUtility.HtmlEncode(invoiceNum)}</h1>
            <p>Customer: {System.Net.WebUtility.HtmlEncode(name)}</p>
            <p>Amount: ${amount:F2}</p>
            <p>Due: {due}</p>
        </body></html>";
}

2. Merge PDFs

Before (CraftMyPDF — verify if merge is supported via API):

using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

class Program
{
    private static readonly HttpClient _http = new HttpClient();

    static async Task Main()
    {
        _http.DefaultRequestHeaders.Add("X-API-KEY", "YOUR-KEY");

        // CraftMyPDF may not have a direct merge API — verify
        // Typically you generate each PDF separately then merge client-side
        // or use their batch API — verify current API docs at craftmypdf.com

        var pdf1Bytes = await GeneratePdfFromTemplate("template_a", new { section = 1 });
        var pdf2Bytes = await GeneratePdfFromTemplate("template_b", new { section = 2 });

        // Manual merge: save both, then merge with another tool — or:
        // CraftMyPDF doesn't provide a merge endpoint (verify in docs)
        Console.WriteLine("Merge requires additional tooling with CraftMyPDF");
    }

    static async Task<byte[]> GeneratePdfFromTemplate(string templateId, object data)
    {
        var payload = new { template_id = templateId, data, export_type = "json", expiry = 10 };
        var response = await _http.PostAsJsonAsync("https://api.craftmypdf.com/v1/create-pdf", payload);
        response.EnsureSuccessStatusCode();
        var result = await response.Content.ReadFromJsonAsync<CraftMyPdfResult>();
        return await _http.GetByteArrayAsync(result.file);
    }
}

record CraftMyPdfResult(string file, string status);

After (IronPDF):

using System;
using IronPdf;

class Program
{
    static void Main()
    {
        IronPdf.License.LicenseKey = "YOUR-KEY";

        // https://ironpdf.com/how-to/merge-or-split-pdfs/
        var pdf1 = PdfDocument.FromFile("section1.pdf");
        var pdf2 = PdfDocument.FromFile("section2.pdf");

        using var merged = PdfDocument.Merge(pdf1, pdf2);
        merged.SaveAs("merged.pdf");
        Console.WriteLine($"Merged: {merged.PageCount} pages");
    }
}

3. Watermark

Before (CraftMyPDF — template-side watermark):

// With CraftMyPDF, watermarks are typically configured in the template editor
// — not added via API. To add a watermark you edit the template in their UI.
// For dynamic watermarks (e.g., per-customer "DRAFT"), you inject a watermark
// variable into the template data payload:

var payload = new
{
    template_id = "abc123",
    data = new
    {
        customer_name = "Alice",
        watermark_text = "DRAFT"  // template must have a watermark element
    },
    export_type = "json",
    expiry = 10
};
// The template designer in CraftMyPDF UI handles the positioning and opacity

After (IronPDF):

using System;
using IronPdf;
using IronPdf.Editing;

class Program
{
    static void Main()
    {
        IronPdf.License.LicenseKey = "YOUR-KEY";

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

        // Full control over watermark properties — https://ironpdf.com/how-to/stamp-text-image/
        var stamper = new TextStamper
        {
            Text = "DRAFT",
            FontSize = 72,
            Opacity = 30,
            Rotation = 45,
            VerticalAlignment = VerticalAlignment.Middle,
            HorizontalAlignment = HorizontalAlignment.Center
        };

        pdf.ApplyStamp(stamper);
        pdf.SaveAs("watermarked.pdf");
        Console.WriteLine("Watermarked PDF saved");
    }
}

4. Password Protection

Before (CraftMyPDF — check if encryption is supported in API):

// CraftMyPDF password protection support — verify in current API docs
// Some PDF generation SaaS services don't support client-specified encryption
// If CraftMyPDF doesn't support it, you may already be encrypting post-download
// using a separate library — that separate library code becomes your before state

// If currently doing post-download encryption with another library, migrate that:
// var pdfBytes = await DownloadFromCraftMyPdf(...);
// [existing encryption code here]

After (IronPDF):

using System;
using IronPdf;

class Program
{
    static void Main()
    {
        IronPdf.License.LicenseKey = "YOUR-KEY";

        // Generate or load the PDF
        var renderer = new ChromePdfRenderer();
        using var pdf = renderer.RenderHtmlAsPdf("<html><body><p>Confidential</p></body></html>");

        // Encrypt in the same step — https://ironpdf.com/how-to/pdf-permissions-passwords/
        pdf.SecuritySettings.UserPassword = "user123";
        pdf.SecuritySettings.OwnerPassword = "owner456";
        pdf.SecuritySettings.AllowUserPrinting =
            IronPdf.Security.PdfPrintSecurity.FullPrintRights;

        pdf.SaveAs("protected.pdf");
        Console.WriteLine("Encrypted PDF saved");
    }
}

API Mapping Tables

Namespace Mapping

CraftMyPDF (HTTP)	IronPDF	Notes
`HttpClient` + API key header	`IronPdf.License.LicenseKey`	No HTTP client needed
`application/json` POST body	Method parameters	Data becomes HTML template inputs
Download URL from response	`pdf.BinaryData` or `pdf.SaveAs()`	Local output

Core Operation Mapping

CraftMyPDF Operation	IronPDF Equivalent	Description
`POST /create-pdf` with template_id	`renderer.RenderHtmlAsPdf(html)`	Generate PDF
Template UI design	HTML + CSS string or Razor view	Template format
JSON `data` field injection	C# string interpolation or Razor model	Data binding
Download from CDN URL	`pdf.BinaryData` or `pdf.Stream`	PDF retrieval

Document Operations

Operation	CraftMyPDF	IronPDF
Generate from template	API call with template_id + data	`renderer.RenderHtmlAsPdf(html)`
Merge documents	Not natively	`PdfDocument.Merge(pdf1, pdf2)`
Add watermark	Template editor + data injection	`pdf.ApplyStamp(stamper)`
Password protect	Verify API support	`pdf.SecuritySettings.*`

Critical Migration Notes

Error Handling Model Change

Cloud APIs fail with HTTP status codes and JSON error bodies. Local library calls throw .NET exceptions. Update your error handling pattern:

// Before — HTTP error handling
var response = await _http.PostAsJsonAsync(url, payload);
if (!response.IsSuccessStatusCode)
{
    var error = await response.Content.ReadAsStringAsync();
    throw new Exception($"CraftMyPDF API error {(int)response.StatusCode}: {error}");
}

// After — exception handling
try
{
    using var pdf = renderer.RenderHtmlAsPdf(html);
    pdf.SaveAs("output.pdf");
}
catch (Exception ex)
{
    _logger.LogError(ex, "PDF generation failed");
    throw;
}

Template Conversion Strategy

Don't try to migrate all templates at once. Work template-by-template:

Screenshot the CraftMyPDF template output
Write an HTML equivalent
Render with IronPDF
Visual diff against the screenshot
Adjust CSS until output matches
Move to next template

Font Migration

Fonts uploaded to CraftMyPDF need to be available locally:

<!-- Reference local font in HTML template -->
<style>
    @font-face {
        font-family: 'CustomFont';
        src: url('/fonts/custom-font.woff2') format('woff2');
    }
    body { font-family: 'CustomFont', Arial, sans-serif; }
</style>

Or use system fonts / Google Fonts.

Latency Profile Change

CraftMyPDF calls are async HTTP — they fit naturally into async code paths. IronPDF rendering is CPU-bound. The first render after creating a new ChromePdfRenderer has startup overhead. Subsequent renders are faster. Account for this in your p99 latency measurements.

// Use async rendering to avoid blocking threads
using var pdf = await renderer.RenderHtmlAsPdfAsync(html);

See async docs for patterns.

Testing Checklist

[ ] Visual comparison: IronPDF output vs CraftMyPDF output for each template (screenshot comparison)
[ ] Font rendering: custom fonts display correctly
[ ] Image rendering: embedded or referenced images appear correctly
[ ] Page size and margins match original templates
[ ] Multi-page documents paginate correctly (check page breaks)
[ ] Special characters and Unicode render correctly
[ ] Test with production-representative data (not just placeholder data)
[ ] Test in target deployment environment (Windows server, Linux container, etc.)
[ ] Measure latency under concurrent load — verify against current SLA requirements
[ ] Password-protected PDFs open with correct credentials

Post-Migration Checklist

[ ] Remove CraftMyPDF API key from all configuration files and secrets stores
[ ] Remove CraftMyPDF API key from CI/CD environment variables
[ ] Delete or archive CraftMyPDF templates (download PDFs of each as reference)
[ ] Update runbooks documenting PDF generation dependency (remove cloud API dependency)

Conclusion

Moving from a cloud PDF API to a local library is one of the less common migration patterns in .NET, but it comes up whenever data residency, offline requirements, or cost-at-scale push teams to bring generation in-house. The template conversion is the most time-consuming step — budget roughly one working day per complex template for visual regression testing.

The payoff is removing a network dependency from a synchronous code path, which tends to show up clearly in p99 latency numbers once it's gone.

Question for the comments: For teams that moved from cloud PDF APIs to local generation — how did you handle the visual regression testing? Pixel diff tooling, manual review, or something else? And how many template conversion cycles did it take to get acceptable output?

GrabzIt vs IronPDF: the practical breakdown for .NET

IronSoftware — Tue, 28 Apr 2026 11:55:00 +0000

Competitor technical approach/engine: Cloud-based API service requiring internet connectivity; supports .NET Standard 2.0; operates via remote capture servers rather than local rendering (source)
Install footprint: NuGet package 78.24 MB; requires API key/secret; mandatory callback architecture for async processing (source)
IronPDF doc links chosen:
What this tool is for: GrabzIt is a cloud-based screenshot/capture service (HTML→PDF, HTML→image, HTML→video, web scraping), not a local PDF rendering library
No-guess rule applied: GrabzIt API names verified from official sources; IronPDF API names from official documentation only

Imagine deploying a document-generation feature to production, only to discover your PDF service is down because a third-party API endpoint is experiencing load issues. Your users see timeout errors. Your support queue fills up. You check the status page—"investigating."

This is the reality teams face when choosing cloud-dependent PDF solutions. GrabzIt positions itself as a multi-format capture service: HTML to PDF, screenshots, video conversion, and web scraping—all processed on remote servers. For .NET teams building applications that need reliable, on-premises PDF generation with modern HTML/CSS support, the architectural differences between cloud-based services and local rendering libraries like IronPDF often become deal-breakers.

Understanding IronPDF

IronPDF is a .NET library that renders HTML to PDF using an embedded Chromium engine. The rendering happens locally within your application process—no API keys, no network calls, no third-party dependencies for the core rendering. Install the NuGet package, write a few lines of C#, and HTML becomes PDF with the same fidelity you see in Chrome's "Print to PDF" feature.

The library supports .NET Framework 4.6.2+, .NET Core, .NET Standard 2.0, and modern .NET (6, 8, 9, 10). It runs on Windows, Linux, macOS, in Docker containers, serverless functions, and traditional ASP.NET deployments. Learn more in the HTML to PDF guide.

Key Limitations of GrabzIt

Product Status

GrabzIt remains actively maintained with recent releases (Jan 2026 for Python, version 3.6.1 for .NET Standard 2.0). However, it fundamentally operates as a cloud service, not a library that runs in your process.

Missing Capabilities

No offline/local rendering: Every PDF requires an outbound HTTPS call to GrabzIt's capture servers
Mandatory callback architecture: Async processing requires a publicly accessible callback URL that GrabzIt's servers can reach
Limited customization: Header/footer control, page breaks, and CSS print media handling are constrained by the remote API's capabilities
No embedded Chromium: Uses GrabzIt's proprietary browser stack; you cannot control the rendering engine version

Technical Issues

Network latency: Minimum round-trip time for any PDF, even simple ones, depends on internet speed and GrabzIt's server load
Firewall complications: Requires outbound HTTPS to GrabzIt endpoints and inbound access for callbacks in async mode
Synchronous mode blocking: Synchronous GetResult calls block your thread while waiting for remote processing
Rate limits: API calls are metered by plan tier; high-volume scenarios may hit quota limits

Support Status

GrabzIt offers email support and community forums. Response times are generally good based on user reviews, but you're dependent on a third-party service for troubleshooting rendering issues.

Architecture Problems

Single point of failure: If GrabzIt's API is down or slow, your entire PDF pipeline stops
Data privacy concerns: HTML content (which might include PII or proprietary data) is transmitted to and processed on GrabzIt's servers
Deployment complexity: Air-gapped environments, government/healthcare systems with strict data residency rules, or private networks cannot use GrabzIt without complex proxy setups

Feature Comparison Overview

Feature	GrabzIt	IronPDF
Current Status	Active (cloud service)	Active (local library)
HTML Support	Via remote API	Full Chromium engine locally
Rendering Quality	GrabzIt's browser stack	Pixel-perfect Chrome rendering
Installation	78.24 MB NuGet + API key	NuGet package, no external dependencies
Support	Email, forums	24/5 engineer chat, premium SLA
Future Viability	Cloud service dependency	Local library, no external service

Code Comparison: HTML String to PDF

GrabzIt — HTML String to PDF

using GrabzIt;
using System;
using System.IO;
using System.Net;
using System.Threading;

namespace GrabzItExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // Initialize client with API credentials
            var grabzIt = new GrabzItClient("YOUR_APP_KEY", "YOUR_APP_SECRET");

            // Define HTML content
            string htmlContent = "<h1>Invoice #12345</h1><p>Total: $499.00</p>";

            // Configure PDF options
            var options = new PDFOptions
            {
                CustomId = "invoice-12345",
                PageSize = GrabzIt.Enums.PageSize.A4,
                Orientation = GrabzIt.Enums.PageOrientation.Portrait
            };

            // Submit capture request to GrabzIt servers
            grabzIt.HTMLToPDF(htmlContent, options);

            // Wait for remote processing (synchronous mode)
            // This blocks the calling thread
            string filename = null;
            byte[] pdfBytes = null;

            // Poll for result with timeout
            var timeout = DateTime.Now.AddSeconds(60);
            while (DateTime.Now < timeout)
            {
                try
                {
                    var status = grabzIt.GetStatus();
                    if (status != null && status.Cached)
                    {
                        pdfBytes = grabzIt.GetResult(status.ID);
                        filename = status.Filename;
                        break;
                    }
                }
                catch (WebException)
                {
                    // Network error or API unavailable
                    Thread.Sleep(1000);
                    continue;
                }

                Thread.Sleep(500); // Wait before next poll
            }

            if (pdfBytes == null)
            {
                Console.WriteLine("PDF generation timed out or failed");
                return;
            }

            // Save result
            File.WriteAllBytes(filename ?? "output.pdf", pdfBytes);
        }
    }
}

Technical limitations of this approach:

Network dependency: Every PDF requires a working internet connection and reachable GrabzIt API endpoints
Synchronous blocking: The polling loop blocks your thread while waiting for remote processing (typically 2-10 seconds for simple PDFs)
No offline capability: Cannot generate PDFs in air-gapped environments, private networks, or during API outages
Callback complexity: For async mode (not shown), you must expose a publicly accessible HTTP endpoint that GrabzIt can POST results to
Error handling complexity: Network failures, API downtime, and timeout scenarios require extensive retry logic
Data transmission: HTML content is sent over HTTPS to GrabzIt's servers; ensure compliance with data residency requirements

IronPDF — HTML String to PDF

using IronPdf;

namespace IronPdfExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // Instantiate renderer (Chromium engine runs locally)
            var renderer = new ChromePdfRenderer();

            // Define HTML content
            string htmlContent = "<h1>Invoice #12345</h1><p>Total: $499.00</p>";

            // Render to PDF (happens in-process, no network calls)
            var pdf = renderer.RenderHtmlAsPdf(htmlContent);

            // Save result
            pdf.SaveAs("output.pdf");
        }
    }
}

This rendering happens entirely within your process. No API keys, no internet requirements, no polling. The Chromium engine executes locally, giving you Chrome-equivalent rendering fidelity. For more complex scenarios with external assets, see the HTML string to PDF tutorial.

Code Comparison: URL to PDF

GrabzIt — URL to PDF

using GrabzIt;
using System;
using System.IO;
using System.Net;
using System.Threading;

namespace GrabzItUrlToPdf
{
    class Program
    {
        static void Main(string[] args)
        {
            // Initialize client
            var grabzIt = new GrabzItClient("YOUR_APP_KEY", "YOUR_APP_SECRET");

            // Configure capture settings
            var options = new PDFOptions
            {
                BrowserWidth = 1366,
                BrowserHeight = 768,
                Delay = 2000, // Wait 2 seconds for JS to execute
                CustomId = "website-capture"
            };

            // Submit URL to GrabzIt's capture servers
            grabzIt.URLToPDF("https://example.com/report", options);

            // Synchronous wait for result
            byte[] pdfBytes = null;
            var timeout = DateTime.Now.AddSeconds(120); // Longer timeout for URLs

            while (DateTime.Now < timeout)
            {
                try
                {
                    var status = grabzIt.GetStatus();
                    if (status != null && status.Cached)
                    {
                        pdfBytes = grabzIt.GetResult(status.ID);
                        break;
                    }
                }
                catch (WebException ex)
                {
                    Console.WriteLine($"Network error: {ex.Message}");
                    Thread.Sleep(1000);
                    continue;
                }

                Thread.Sleep(1000);
            }

            if (pdfBytes == null)
            {
                Console.WriteLine("URL capture timed out");
                return;
            }

            File.WriteAllBytes("webpage.pdf", pdfBytes);
        }
    }
}

Technical limitations of this approach:

Double network hop: Your server calls GrabzIt's API, which then fetches the URL—adding latency and potential failure points
Public URL requirement: The target URL must be publicly accessible to GrabzIt's servers; internal/localhost URLs won't work without IntraProxy
IntraProxy complexity: For private URLs, you must run GrabzIt's IntraProxy tool, adding another moving part to your infrastructure
Unpredictable timing: Processing time depends on both your network, GrabzIt's server load, and the target website's response time
JavaScript timing issues: The Delay parameter is a static wait; doesn't adapt to actual page load completion
No custom headers/auth: Limited support for capturing authenticated pages or pages requiring specific HTTP headers

IronPDF — URL to PDF

using IronPdf;

namespace IronPdfUrlToPdf
{
    class Program
    {
        static void Main(string[] args)
        {
            // Instantiate renderer
            var renderer = new ChromePdfRenderer();

            // Optional: Configure wait behavior for JavaScript
            renderer.RenderingOptions.WaitFor.RenderDelay = 2000; // milliseconds

            // Render URL to PDF (fetches and renders locally)
            var pdf = renderer.RenderUrlAsPdf("https://example.com/report");

            // Save result
            pdf.SaveAs("webpage.pdf");
        }
    }
}

IronPDF's Chromium engine fetches and renders the URL locally. You can capture localhost, internal network URLs, or authenticated pages without proxies. JavaScript executes in the rendering engine with full modern browser API support.

Code Comparison: HTML File to PDF with Assets

GrabzIt — HTML File to PDF

using GrabzIt;
using System;
using System.IO;
using System.Net;
using System.Threading;

namespace GrabzItFileExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // Initialize client
            var grabzIt = new GrabzItClient("YOUR_APP_KEY", "YOUR_APP_SECRET");

            // Read HTML file from disk
            string htmlContent = File.ReadAllText("invoice.html");

            // Note: External assets (images, CSS) must be:
            // 1. Embedded as base64 in the HTML, or
            // 2. Hosted on a publicly accessible URL, or
            // 3. Uploaded separately to GrabzIt

            var options = new PDFOptions
            {
                CustomId = "invoice-file"
            };

            // Submit to GrabzIt (HTML content is transmitted over network)
            grabzIt.HTMLToPDF(htmlContent, options);

            // Wait for processing
            byte[] pdfBytes = null;
            var timeout = DateTime.Now.AddSeconds(60);

            while (DateTime.Now < timeout)
            {
                try
                {
                    var status = grabzIt.GetStatus();
                    if (status != null && status.Cached)
                    {
                        pdfBytes = grabzIt.GetResult(status.ID);
                        break;
                    }
                }
                catch (WebException)
                {
                    Thread.Sleep(1000);
                    continue;
                }

                Thread.Sleep(500);
            }

            if (pdfBytes == null)
            {
                Console.WriteLine("File conversion timed out");
                return;
            }

            File.WriteAllBytes("invoice.pdf", pdfBytes);
        }
    }
}

Technical limitations of this approach:

Asset handling complexity: Local file references (images, CSS) in your HTML won't resolve on GrabzIt's remote servers
Base64 workaround required: Must embed images as base64 data URIs or host them publicly, increasing HTML size and complexity
No relative path support: Cannot use <img src="./logo.png"> with local files; GrabzIt's servers can't access your file system
Content size limits: Large HTML files with embedded assets may hit API payload limits
Multi-file coordination: If you have separate CSS files or multiple images, you must either inline them all or upload them to a public CDN
No local testing: Cannot test PDF generation offline or in development without internet access

IronPDF — HTML File to PDF

using IronPdf;

namespace IronPdfFileExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // Instantiate renderer
            var renderer = new ChromePdfRenderer();

            // Render HTML file with automatic local asset resolution
            var pdf = renderer.RenderHtmlFileAsPdf("invoice.html");

            // IronPDF automatically resolves relative paths:
            // <img src="logo.png"> loads from same directory as invoice.html
            // <link href="styles.css"> loads local CSS files

            // Save result
            pdf.SaveAs("invoice.pdf");
        }
    }
}

IronPDF resolves local file paths automatically. If your HTML references <img src="images/logo.png">, the library loads it from your file system. No base64 conversion, no CDN uploads, no workarounds. See the HTML file to PDF guide for more details on asset handling.

Code Comparison: Adding Headers and Footers

GrabzIt — Headers and Footers

using GrabzIt;
using System;
using System.IO;
using System.Net;
using System.Threading;

namespace GrabzItHeaderFooter
{
    class Program
    {
        static void Main(string[] args)
        {
            // Initialize client
            var grabzIt = new GrabzItClient("YOUR_APP_KEY", "YOUR_APP_SECRET");

            string htmlContent = "<h1>Report</h1><p>Content here...</p>";

            // Configure header/footer via API options
            // Note: Customization options are limited to what the API exposes
            var options = new PDFOptions
            {
                AddHtmlElement = true, // Enable header/footer
                IncludeBackground = true,
                MarginTop = 10,
                MarginBottom = 10
                // Header/footer content is defined server-side
                // or via predefined templates - limited flexibility
            };

            // For custom headers/footers, you must:
            // 1. Embed them directly in your HTML content, or
            // 2. Use GrabzIt's web interface to define templates
            // Neither approach gives you programmatic, per-PDF control

            grabzIt.HTMLToPDF(htmlContent, options);

            // Wait for result
            byte[] pdfBytes = null;
            var timeout = DateTime.Now.AddSeconds(60);

            while (DateTime.Now < timeout)
            {
                try
                {
                    var status = grabzIt.GetStatus();
                    if (status != null && status.Cached)
                    {
                        pdfBytes = grabzIt.GetResult(status.ID);
                        break;
                    }
                }
                catch (WebException)
                {
                    Thread.Sleep(1000);
                    continue;
                }

                Thread.Sleep(500);
            }

            if (pdfBytes == null)
            {
                Console.WriteLine("PDF with headers timed out");
                return;
            }

            File.WriteAllBytes("report-with-header.pdf", pdfBytes);
        }
    }
}

Technical limitations of this approach:

Limited programmatic control: Cannot dynamically set header/footer content per PDF in code
No HTML header/footer support: Headers and footers are not rendered as separate HTML blocks with full CSS support
Static templates: Must define headers/footers in GrabzIt's web UI, then reference by ID—not flexible for variable content
No page number placeholders: Limited merge fields compared to local rendering libraries
Margin-only approach: Often requires manually embedding header/footer HTML in main content and using margins to position
No per-page variation: Cannot have different headers for first page vs. subsequent pages

IronPDF — Headers and Footers

using IronPdf;

namespace IronPdfHeaderFooter
{
    class Program
    {
        static void Main(string[] args)
        {
            // Instantiate renderer
            var renderer = new ChromePdfRenderer();

            // Configure HTML header with dynamic placeholders
            renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
            {
                MaxHeight = 20, // millimeters
                HtmlFragment = "<div style='text-align:center;'><b>Company Report - {date}</b></div>",
                DrawDividerLine = true
            };

            // Configure HTML footer with page numbers
            renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
            {
                MaxHeight = 15,
                HtmlFragment = "<center><i>Page {page} of {total-pages}</i></center>",
                DrawDividerLine = true
            };

            // Set margins to accommodate headers/footers
            renderer.RenderingOptions.MarginTop = 25;    // mm
            renderer.RenderingOptions.MarginBottom = 20; // mm

            // Render HTML to PDF
            string htmlContent = "<h1>Report</h1><p>Content here...</p>";
            var pdf = renderer.RenderHtmlAsPdf(htmlContent);

            pdf.SaveAs("report-with-header.pdf");
        }
    }
}

IronPDF renders headers and footers as independent HTML fragments with full CSS support. Use placeholders like {page}, {total-pages}, {date}, {time}, {url}, {html-title}, and {pdf-title} for dynamic content. For more advanced scenarios, see the headers and footers tutorial.

API Mapping Reference

GrabzIt Concept	IronPDF Equivalent
`GrabzItClient`	`ChromePdfRenderer`
`HTMLToPDF(html)`	`RenderHtmlAsPdf(html)`
`URLToPDF(url)`	`RenderUrlAsPdf(url)`
`GetResult(id)`	N/A (no async polling needed)
`PDFOptions.PageSize`	`RenderingOptions.PaperSize`
`PDFOptions.Orientation`	`RenderingOptions.PaperOrientation`
`PDFOptions.Delay`	`RenderingOptions.WaitFor.RenderDelay`
`PDFOptions.CustomId`	N/A (no remote tracking needed)
`PDFOptions.MarginTop`	`RenderingOptions.MarginTop`
`IntraProxy`	N/A (local rendering accesses network directly)
Callback URL	N/A (no callback architecture)
API Key/Secret	N/A (no authentication required)
Cloud-based processing	Local Chromium engine

Comprehensive Feature Comparison

Category	Feature	GrabzIt	IronPDF
Status	Active Development	Yes (cloud service)	Yes (local library)
Status	Offline Capability	No	Yes
Status	Network Dependency	Required for all operations	Optional (only for URL fetch)
Support	Response Time	Email/forum (hours to days)	24/5 engineer chat (<1 min median)
Support	Screen Sharing	No	Yes (premium)
Support	Premium SLA	-	Yes (24/7 available)
Content Creation	HTML String to PDF	Yes (via API)	Yes (local)
Content Creation	URL to PDF	Yes (public URLs only)	Yes (any accessible URL)
Content Creation	HTML File to PDF	Yes (content uploaded)	Yes (local files)
Content Creation	Localhost/Private URLs	Requires IntraProxy	Yes (native support)
Content Creation	Modern CSS3/HTML5	Verify against current browser version	Full Chromium support
Content Creation	JavaScript Execution	Yes (with delay parameter)	Yes (full modern JS support)
Content Creation	Custom Fonts	Yes (web fonts)	Yes (web fonts & local fonts)
PDF Operations	HTML Headers/Footers	Limited (manual embedding)	Full support with placeholders
PDF Operations	Page Numbers	Manual implementation	Built-in placeholders
PDF Operations	Watermarks	Manual embedding	`ApplyWatermark` method
PDF Operations	Merge PDFs	No	Yes
PDF Operations	Split PDFs	No	Yes
PDF Operations	Edit Existing PDFs	No	Yes (full editing API)
PDF Operations	Extract Text	No	Yes
PDF Operations	Forms Support	No	Yes (fill, flatten, create)
Security	Encryption	-	Yes (AES-256)
Security	Digital Signatures	No	Yes (X.509 certificates)
Security	Permissions	-	Yes (print, copy, modify)
Security	Data Residency	Processed on GrabzIt servers	Fully local
Known Issues	API Downtime Risk	Yes (single point of failure)	No
Known Issues	Rate Limiting	Yes (plan-based quotas)	No
Known Issues	Callback Architecture Complexity	Yes (requires public endpoints)	No
Known Issues	Asset Path Resolution	Requires public URLs or base64	Automatic local path resolution
Development	NuGet Package	Yes	Yes
Development	.NET Framework Support	.NET Standard 2.0	.NET Framework 4.6.2+
Development	.NET Core/.NET 5+ Support	Yes	Yes (.NET 6, 8, 9, 10)
Development	Cross-Platform	Yes (via cloud API)	Yes (Windows, Linux, macOS)
Development	Docker/Container Support	Yes (API client)	Yes (full runtime)
Development	Azure/AWS Support	Yes	Yes
Development	Async/Await Support	Via callback architecture	Native async methods

Commonly Reported Issues

Based on community discussions and documentation gaps, teams commonly report these GrabzIt challenges:

Public callback URL requirement: For async mode, your application must expose a publicly accessible HTTP endpoint that GrabzIt can POST results to—complex in private networks or serverless environments
Local asset handling: Images, CSS, fonts in HTML files must be publicly hosted or base64-encoded; relative file paths don't work
Synchronous mode blocking: Using GetResult in a polling loop blocks your thread for seconds or minutes, harming application responsiveness
Network error handling: Transient network issues, API throttling, or GrabzIt downtime require extensive retry logic and fallback strategies
Localhost/intranet capture: Requires deploying and maintaining the separate IntraProxy tool to access private URLs
Limited programmatic header/footer control: Headers and footers are defined via web UI templates or manual HTML embedding, not flexible per-PDF code
API quota management: High-volume applications must monitor usage against plan limits and handle quota exhaustion gracefully
Data transmission security: HTML content containing sensitive information is sent over the internet to third-party servers
Deployment complexity: Multi-region deployments require network access to GrabzIt from all regions, potentially increasing latency for global users
Debugging difficulty: When rendering fails, you receive an error from a remote service with limited visibility into what went wrong

Installation Comparison

GrabzIt Installation

# Install NuGet package
dotnet add package GrabzIt --version 3.6.1

# Required: Sign up for API key and secret at https://grabz.it
# Store credentials securely (environment variables recommended)

Namespace imports:

using GrabzIt;
using GrabzIt.Enums;

Additional setup:

Create GrabzIt account and obtain API key/secret
For async mode: Configure publicly accessible callback URL
For private URLs: Download and run IntraProxy tool
Ensure outbound HTTPS allowed to *.grabz.it domains
Plan network architecture around external API dependency

IronPDF Installation

# Install NuGet package (no API keys required)
dotnet add package IronPdf

Namespace imports:

using IronPdf;

Additional setup:

None required for basic usage
Optional: License key for production deployment
Works immediately in offline/air-gapped environments

Conclusion

GrabzIt serves a specific use case: teams that want a cloud service for multi-format capture (screenshots, video conversion, web scraping) and are willing to accept network dependency, callback architecture, and data transmission to third-party servers. For .NET applications that need reliable, local HTML-to-PDF rendering, GrabzIt's cloud-based architecture introduces unavoidable challenges.

Migration becomes mandatory when your requirements include: offline capability, air-gapped deployments, processing sensitive data that cannot leave your infrastructure, capturing localhost/intranet pages without proxy tools, or building high-throughput pipelines where API rate limits and network latency are unacceptable.

IronPDF provides local Chromium-based rendering with no external dependencies, automatic asset path resolution, full header/footer/watermark support, and a comprehensive PDF manipulation API. The library runs wherever .NET runs—Windows, Linux, containers, serverless—with no callback URLs, no API quotas, and no third-party service downtime risk.

What's been your experience with cloud-based vs. local PDF generation in .NET? Have you faced network dependency challenges in production?

For additional guidance, explore editing PDFs in C# and the IronPDF documentation hub.

GdPicture.NET SDK vs IronPDF: a .NET developer honest take

IronSoftware — Tue, 28 Apr 2026 11:54:00 +0000

When evaluating document SDKs for .NET projects, understanding scope boundaries prevents architectural mismatches. GdPicture.NET SDK is a comprehensive document imaging platform covering OCR, barcode reading, TWAIN scanning, image cleanup, format conversion (100+ types), and PDF operations—all in one package. IronPDF is a focused PDF library specializing in HTML-to-PDF conversion and PDF manipulation. The choice hinges on whether your project needs an all-in-one document processing suite or a targeted PDF tool that integrates with existing systems.

A medical records application requiring TWAIN scanner integration, OCR on scanned documents, barcode recognition, TIFF manipulation, and PDF archiving might justify GdPicture's breadth. An invoicing platform converting Razor views to PDFs needs IronPDF's Chromium rendering, not the additional imaging features.

Understanding IronPDF

IronPDF operates with laser focus: convert HTML to PDF using a Chromium rendering engine, then provide essential PDF operations (merging, form filling, text extraction, digital signatures, encryption). The library assumes content starts as HTML—whether from Razor views, React components, or static templates—and renders it into pixel-perfect PDFs. This specialization means simpler APIs, smaller deployment footprint, and faster developer onboarding for HTML-based workflows.

The Chromium engine ensures PDFs match browser rendering, critical when stakeholders review documents in browsers before PDF generation. IronPDF doesn't process images, read barcodes, or drive scanners—it does one thing comprehensively.

Key Limitations of GdPicture.NET SDK

Product Status

Active commercial product with continuous updates. Acquired by Nutrient (PSPDFKit parent company), indicating ongoing investment. Trial version includes watermarks and trial notifications. Requires licensing for production deployment. 12-month maintenance and support included with purchase; renewals required thereafter.

Missing Capabilities

No built-in Chromium-based HTML renderer—HTML-to-PDF conversion uses different engine with varying CSS support. JavaScript execution during conversion limited compared to browser engines. Learning curve for PDF-specific operations steeper due to broad API surface covering many document types.

Technical Issues

API complexity: 3000+ methods across imaging, PDF, OCR, forms, scanning, barcoding. Documentation navigability challenging given scope. HTML conversion quality varies with complex CSS (Flexbox, Grid layouts). Licensing model requires careful planning—features are modular but license covers full SDK.

Support Status

Commercial support with response time based on license tier. Active community forums. Extensive documentation but large surface area makes finding specific features challenging. Support quality generally good but breadth of product means support team must cover many domains.

Architecture Problems

Package organization can be confusing: GdPicture vs GdPicture.API vs DocuVieware. Determining which package to install requires understanding architecture. For PDF-only workflows, carrying 100+ format support, imaging engine, and OCR capabilities adds deployment overhead. Native dependencies for certain features (OCR resources, TWAIN drivers).

Feature Comparison Overview

Aspect	GdPicture.NET SDK	IronPDF
Current Status	Active (Nutrient/PSPDFKit)	Active (Iron Software)
HTML Support	HTML converter (non-Chromium)	Chromium engine (core feature)
Rendering Quality	Multi-engine approach	Browser-grade rendering
Installation	Multiple packages (modular)	Single NuGet (self-contained)
Support	Commercial (tiered)	Commercial with SLA
Future Viability	Continuous updates	Continuous updates

Requirements Checklist: When to Use Each Library

✅ Choose GdPicture.NET SDK when:

[ ] Multi-format document processing: Need to handle TIFF, JPEG, PNG, BMP, DICOM, JBIG2, etc. alongside PDFs
[ ] OCR requirements: Converting scanned documents to searchable PDFs with text extraction
[ ] Barcode operations: Reading/writing barcodes (1D, 2D, QR codes) from documents
[ ] Document scanning: TWAIN/WIA scanner integration for direct capture
[ ] Advanced image processing: Cleanup, deskew, despeckle, rotate, crop operations
[ ] Forms processing: OMR (optical mark recognition) for surveys, answer sheets
[ ] Document imaging DMS: Building comprehensive document management systems
[ ] Format conversion pipelines: Converting between dozens of document/image formats
[ ] Compression requirements: Advanced TIFF/PDF compression, MRC (mixed raster content)
[ ] Annotation workflows: Comprehensive markup and collaboration features
[ ] Print management: Advanced printing with job control and spooling
[ ] Compliance needs: PDF/A validation and conversion across versions
[ ] Legacy format support: Need to process older formats (PCX, TARGA, XPM, etc.)

✅ Choose IronPDF when:

[ ] HTML-to-PDF primary use case: Converting web pages, Razor views, or HTML templates
[ ] Modern CSS layouts: Need accurate rendering of Flexbox, Grid, CSS3 features
[ ] JavaScript execution: Dynamic content that requires JS during PDF generation
[ ] Web font support: Google Fonts, custom fonts via CSS @font-face
[ ] Simplified API: Team prefers focused, easy-to-learn PDF-specific interface
[ ] Rapid development: Tight deadlines benefit from streamlined HTML-to-PDF workflow
[ ] Browser-quality rendering: Output must match what users see in Chrome/Edge
[ ] PDF-only requirements: Don't need imaging, scanning, OCR, or multi-format support
[ ] Docker/cloud deployment: Simpler containerization without imaging dependencies
[ ] Integration with existing HTML: Already generating HTML for web; reuse for PDFs
[ ] Form generation from HTML: Convert HTML forms to interactive PDF fields
[ ] Smaller deployment footprint: Don't want 100+ format support overhead
[ ] Modern .NET stack: Targeting .NET 5+ with latest framework features

Code Comparison: Document Conversion Workflow

GdPicture.NET SDK — Multi-Format to PDF

// Conceptual example based on GdPicture documentation
// Verify exact API in official docs
using GdPicture14;
using System;

namespace GdPictureConversionExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // GdPicture handles many formats
            // License activation required (verify in docs)

            // Example: TIFF to PDF conversion
            using (var gdPdfDoc = new GdPicturePDF())
            {
                // Load TIFF image
                using (var imaging = new GdPictureImaging())
                {
                    int imageId = imaging.CreateGdPictureImageFromFile("scan.tiff");

                    if (imageId != 0)
                    {
                        // Add image to PDF
                        // Verify exact method signature in GdPicture docs
                        gdPdfDoc.NewPDF();
                        // API for adding image varies - check documentation

                        // Save PDF
                        gdPdfDoc.SaveToFile("output.pdf");

                        imaging.ReleaseGdPictureImage(imageId);
                    }
                }
            }

            // Example: HTML to PDF (verify HTML converter API)
            // GdPicture includes HTML converter but may require
            // different approach than browser-based engines

            Console.WriteLine("Refer to GdPicture.NET documentation for exact API");
        }
    }
}

Checklist of considerations:

[ ] ✅ Handles 100+ document/image formats
[ ] ✅ Direct TIFF/scanning workflow support
[ ] ✅ Comprehensive imaging operations
[ ] ⚠️ Complex API with many classes/methods
[ ] ⚠️ HTML conversion not primary strength
[ ] ⚠️ Requires understanding GdPicture object model
[ ] ⚠️ Resource management via manual image ID release

IronPDF — HTML to PDF Conversion

using IronPdf;
using System;

namespace IronPdfConversionExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // HTML to PDF (primary use case)
            var htmlContent = @"
                <html>
                <head>
                    <style>
                        body { font-family: Arial; margin: 40px; }
                        .header { background: #f0f0f0; padding: 20px; }
                    </style>
                </head>
                <body>
                    <div class='header'>
                        <h1>Invoice #12345</h1>
                    </div>
                    <p>Thank you for your purchase.</p>
                </body>
                </html>";

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

            // For multi-format conversion, use external tools
            // IronPDF focuses on PDF operations, not image formats
        }
    }
}

Checklist of considerations:

[ ] ✅ Simple HTML-to-PDF API
[ ] ✅ Browser-grade CSS rendering
[ ] ✅ JavaScript execution support
[ ] ✅ Focused feature set, easy to learn
[ ] ⚠️ PDF-only (no TIFF, imaging, scanning)
[ ] ⚠️ Requires HTML as input format
[ ] ✅ Auto resource management via Dispose

For HTML conversion workflows, see IronPDF's HTML to PDF guide.

Code Comparison: OCR and Text Extraction

GdPicture.NET SDK — OCR on Scanned Documents

// Conceptual OCR example (verify API in GdPicture docs)
using GdPicture14;
using System;

namespace GdPictureOcrExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // GdPicture includes powerful OCR engine
            // Requires GdPicture.Resources package for language data

            using (var imaging = new GdPictureImaging())
            using (var ocr = new GdPictureOCR())
            {
                // Load scanned image
                int imageId = imaging.CreateGdPictureImageFromFile("scanned_doc.png");

                if (imageId != 0)
                {
                    // Configure OCR
                    // Verify exact API - GdPicture supports multiple OCR engines

                    // Perform OCR
                    // API varies - check documentation for current version

                    // Extract text
                    // string extractedText = ...

                    // Create searchable PDF from scanned image
                    // GdPicture can create PDF/A compliant searchable PDFs

                    imaging.ReleaseGdPictureImage(imageId);

                    Console.WriteLine("Check GdPictureOCR documentation for API");
                }
            }
        }
    }
}

Feature checklist:

[ ] ✅ Full OCR engine included
[ ] ✅ Multiple language support
[ ] ✅ Searchable PDF creation
[ ] ✅ PDF/A compliance
[ ] ✅ Image preprocessing (deskew, cleanup)
[ ] ⚠️ Requires GdPicture.Resources package
[ ] ⚠️ Learning curve for OCR API

IronPDF — Text Extraction from PDFs

using IronPdf;
using System;

namespace IronPdfTextExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // Load existing PDF
            var pdf = PdfDocument.FromFile("document.pdf");

            // Extract all text
            string allText = pdf.ExtractAllText();
            Console.WriteLine(allText);

            // Extract text from specific page
            string pageText = pdf.ExtractTextFromPage(0); // Page 0

            pdf.Dispose();

            // Note: IronPDF extracts text from existing PDFs
            // For OCR on images, use separate library like IronOCR
        }
    }
}

Feature checklist:

[ ] ✅ Simple text extraction API
[ ] ✅ Page-specific extraction
[ ] ⚠️ No OCR on images/scans
[ ] ⚠️ PDF-only (not image formats)
[ ] ✅ Works with digital PDFs
[ ] 💡 For OCR: use IronOCR (separate library)

Code Comparison: Form Processing

GdPicture.NET SDK — Comprehensive Forms

// Conceptual forms example (verify API)
using GdPicture14;
using System;

namespace GdPictureFormsExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // GdPicture supports multiple form technologies:
            // - PDF AcroForms
            // - OMR (optical mark recognition)
            // - Template-based form processing

            using (var pdfDoc = new GdPicturePDF())
            {
                pdfDoc.LoadFromFile("form_template.pdf");

                // Fill form fields
                // Verify exact API for form field manipulation

                // OMR example: analyze checkbox marks on scanned forms
                // GdPicture includes OMR engine for survey processing

                pdfDoc.SaveToFile("filled_form.pdf");
            }

            Console.WriteLine("See GdPicture forms documentation");
        }
    }
}

Forms capability checklist:

[ ] ✅ AcroForm support
[ ] ✅ OMR for scanned forms
[ ] ✅ Template-based processing
[ ] ✅ Barcode integration
[ ] ✅ Digital signatures
[ ] ⚠️ Complex API for advanced features

IronPDF — HTML-Based Form Creation

using IronPdf;
using System;

namespace IronPdfFormsExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create form from HTML
            var formHtml = @"
                <html>
                <body>
                    <h2>Registration Form</h2>
                    <form>
                        <label>Name:</label>
                        <input type='text' name='fullName' /><br/>
                        <label>Email:</label>
                        <input type='email' name='email' /><br/>
                        <label>Subscribe:</label>
                        <input type='checkbox' name='subscribe' />
                    </form>
                </body>
                </html>";

            var renderer = new ChromePdfRenderer();
            renderer.RenderingOptions.CreatePdfFormsFromHtml = true;

            var pdf = renderer.RenderHtmlAsPdf(formHtml);
            pdf.SaveAs("registration_form.pdf");
            pdf.Dispose();

            // Fill existing form
            var existingPdf = PdfDocument.FromFile("form_template.pdf");
            existingPdf.Form.SetFieldValue("fieldName", "value");
            existingPdf.SaveAs("filled.pdf");
            existingPdf.Dispose();
        }
    }
}

Forms capability checklist:

[ ] ✅ HTML-to-form conversion
[ ] ✅ AcroForm filling
[ ] ✅ Simple API
[ ] ⚠️ No OMR for scanned forms
[ ] ⚠️ No template matching
[ ] ✅ Digital signatures supported

API Mapping Reference

Operation	GdPicture.NET SDK	IronPDF	Notes
Load PDF	`GdPicturePDF.LoadFromFile()`	`PdfDocument.FromFile()`	Different classes
Create PDF	`GdPicturePDF.NewPDF()`	`ChromePdfRenderer.RenderHtmlAsPdf()`	Different approaches
HTML to PDF	HTML converter API	Core Chromium engine	GdPicture: separate; IronPDF: primary
Image to PDF	`GdPictureImaging` + PDF	Not built-in	GdPicture strength
OCR	`GdPictureOCR`	Use IronOCR (separate)	Different product scopes
Extract text	PDF text extraction API	`ExtractAllText()`	Both support
Form filling	Form API	`Form.SetFieldValue()`	Both support
Merge PDFs	Verify GdPicture API	`PdfDocument.Merge()`	Both support
Barcode	`GdPictureBarcode`	Not included	GdPicture feature
TWAIN scanning	`GdPictureTWAIN`	Not included	GdPicture feature
Annotations	Comprehensive API	Basic support	GdPicture stronger
Digital signatures	Both support	Both support	Both support

Comprehensive Feature Comparison

Feature	GdPicture.NET SDK	IronPDF
Status
Active Development	Yes (Nutrient)	Yes (Iron Software)
Licensing	Commercial	Commercial
Support
Commercial Support	Tiered	Included
Documentation	Extensive	Focused
Content Creation
HTML to PDF	Converter (non-Chromium)	Chromium engine
Image to PDF	Full support (100+ formats)	Not primary feature
Programmatic PDF	Low-level API	HTML-based
Imaging Features
Image Processing	Full suite	Not included
OCR	Built-in	Separate product (IronOCR)
Barcode	Read/write	Separate product
TWAIN Scanning	Yes	No
Format Conversion	100+ formats	PDF focus
PDF Operations
PDF Viewing	UI components	No
PDF Editing	Comprehensive	Standard operations
Annotations	Full suite	Basic
Forms	AcroForm + OMR	AcroForm
Signatures	Yes	Yes
Merge/Split	Yes	Yes
Document Management
Compression	Advanced (MRC, etc.)	Standard
PDF/A	Full support	Basic
Printing	Advanced control	Not primary focus
Development
.NET Framework	Yes	4.6.2+
.NET Core/5+	Yes	Yes
Platforms	Windows, Linux, macOS	Windows, Linux, macOS

Deployment Checklist

GdPicture.NET SDK Deployment:

[ ] Choose package: GdPicture.API (core) vs GdPicture (with viewers)
[ ] Install GdPicture.Resources if using OCR
[ ] Configure license key in application
[ ] Test on target platform (Windows/Linux/macOS)
[ ] For Docker: ensure adequate memory for imaging operations
[ ] Check native dependencies (none for core, but platform-specific builds)
[ ] Review modular licensing if not using all features
[ ] Plan for 12-month maintenance renewal

IronPDF Deployment:

[ ] Install IronPdf NuGet package
[ ] Set license key in configuration or code
[ ] Test HTML rendering with representative content
[ ] For Docker: standard .NET images work
[ ] Verify Chromium binaries included (auto-selected by platform)
[ ] No additional packages unless needing OCR (IronOCR)
[ ] Configure header/footer templates if needed
[ ] Test on all target platforms

Installation Comparison

GdPicture.NET SDK

# Core API (cross-platform)
dotnet add package GdPicture.API

# Or full package with viewers (Windows only)
dotnet add package GdPicture

# Add OCR resources if needed
dotnet add package GdPicture.Resources

using GdPicture14;

// Configure licensing
// Verify license setup in GdPicture documentation

IronPDF

dotnet add package IronPdf

using IronPdf;

// Optional: Configure license
// IronPdf.License.LicenseKey = "YOUR-KEY";

Conclusion

GdPicture.NET SDK and IronPDF serve different architectural needs. GdPicture targets comprehensive document management systems requiring multi-format processing, OCR, scanning, barcoding, and advanced imaging—use cases common in healthcare, legal, or government sectors where document workflows span capture, processing, storage, and retrieval.

IronPDF specializes in the modern web application pattern: generate HTML via Razor, React, or templates, then render to PDF with browser-quality fidelity. Teams already producing HTML for web UIs reuse those skills, assets, and layouts for PDF generation without learning imaging APIs or format conversion pipelines.

Migration scenarios: if GdPicture's breadth goes unused (you're only doing HTML-to-PDF), IronPDF's focused API reduces complexity and deployment size. Conversely, if your PDF workflow is one component of broader document imaging needs, GdPicture consolidates multiple tools into one licensed SDK.

Does your project need document imaging capabilities beyond PDF generation, or is PDF the isolated requirement?

Review IronPDF's HTML-to-PDF workflow: HTML to PDF conversion tutorial
Explore IronPDF's PDF operations: C# PDF generation guide

BitMiracle Docotic.PDF vs IronPDF: side by side for .NET teams in 2026

IronSoftware — Tue, 28 Apr 2026 10:53:00 +0000

A development team evaluates BitMiracle Docotic.PDF for a document generation project. The documentation looks comprehensive, the API clean, and the GitHub samples plentiful. They install the core package and start building. Three hours in, they discover they need HTML-to-PDF conversion. The documentation mentions an HtmlToPdf add-on, so they install it. Then they hit the critical discovery: Docotic.PDF requires a license key to function—even in development. Without a valid license, every operation returns an error. The free 31-day trial requires providing contact information to receive a key via email.

This checklist discovery—core library ✓, add-on package ✓, license configuration ✗—surfaces a pattern with Docotic.PDF: comprehensive feature list, modular architecture, but operational complexity in the details.

Understanding IronPDF

IronPDF consolidates HTML-to-PDF conversion in a single package with optional trial licensing. Where Docotic.PDF separates core PDF manipulation from HTML rendering via add-ons, IronPDF integrates both. The architectural choice affects both simplicity and specialization: IronPDF focuses deeply on HTML rendering quality, Docotic.PDF offers broader PDF manipulation features with HTML as one input method among many.

The ChromePdfRenderer class works without configuration for development and testing, adding a watermark until licensed. Docotic.PDF won't execute any PDF operations without a valid license key, including trial keys that must be requested.

Key Limitations of Docotic.PDF

Product Status: ✓ Active (v9.8 August 2025). ✓ Consistent releases. ✗ Documentation scattered across website, NuGet, GitHub. ✗ HTML-to-PDF examples minimal compared to PDF manipulation examples. ✓ .NET 8 support added recently.

Missing Capabilities: ✓ HTML-to-PDF via Chromium add-on. ✗ Add-on requires separate package installation. ✗ License key required for all operations (including dev/test). ✗ No built-in async variants for HTML operations. ✗ Header/footer HTML templating less documented than text-based headers. ✗ URL authentication options not clearly documented.

Technical Issues: ✗ License validation errors if key not set correctly—no PDF operations work. ✗ HtmlToPdf add-on initialization not obvious from core documentation. ✗ Async patterns for HTML operations unclear—may require manual Task wrapping. ✗ Error messages generic when license issues occur. ✗ Trial license requires email request—not instant. ✗ System.Drawing.Common dependency in Gdi add-on not recommended for Linux/macOS per Microsoft docs.

Support Status: ✓ Free and paid licenses available. ✓ GitHub repository with samples. ✓ Responsive to issues (based on GitHub activity). ✗ HTML-to-PDF specific guidance sparse. ✗ No clear migration guides from other libraries. ✓ Active forum presence by maintainers.

Architecture Problems: ✗ Modular design requires understanding which add-on provides which feature. ✗ HtmlToPdf add-on separate from core—two packages to manage. ✗ License key must be set before any operations—no graceful degradation for trial. ✗ PDF manipulation features excellent but not needed for HTML-to-PDF workflows. ✓ 100% managed code (no native dependencies) is architectural strength. ✗ Async support for HTML rendering unclear from documentation.

License Requirement Checklist:

✗ Cannot create PDFs without license key
✗ Cannot read PDFs without license key
✗ Trial license requires email request (not instant)
✗ License key valid 31 days for trial
✗ Must set BitMiracle.Docotic.LicenseManager.AddLicenseData(key) before any operation
✗ Production requires commercial license purchase
✓ Free licenses available for eligible projects

Feature Comparison Overview

Feature	Docotic.PDF	IronPDF
Current Status	Active	Active
HTML Support	Chromium add-on (separate package)	Chromium core
Rendering Quality	Pixel-perfect (Chromium)	Pixel-perfect (Chromium)
Installation	2 NuGet packages + license	1 NuGet package
License Required	✗ Yes (even for trial)	✓ Optional (watermark only)
Future Viability	PDF manipulation focus	HTML-to-PDF focus

Code Comparison Checklist

Docotic.PDF — Installation Checklist

// ✗ STEP 1: Install core package
// Install-Package BitMiracle.Docotic.Pdf

// ✗ STEP 2: Install HTML add-on
// Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf

// ✗ STEP 3: Get license key
// Visit https://bitmiracle.com/pdf-library/
// Fill form, wait for email with trial key

// ✗ STEP 4: Configure license BEFORE any operations
using BitMiracle.Docotic;
using BitMiracle.Docotic.Pdf;
using BitMiracle.Docotic.Pdf.HtmlToPdf;

namespace DococticExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // CRITICAL: Must set license before any PDF operation
            // Without this, all operations fail
            LicenseManager.AddLicenseData("YOUR-LICENSE-KEY-HERE");

            // Verify license loaded
            if (!LicenseManager.IsLicenseValid)
            {
                Console.WriteLine("ERROR: License not valid");
                Console.WriteLine("Request trial: https://bitmiracle.com/pdf-library/");
                return;
            }

            // ✓ Now PDF operations will work
            // See code examples below
        }
    }
}

Installation checklist:

✗ Install core package
✗ Install HtmlToPdf add-on package
✗ Request trial license (wait for email)
✗ Add license key to code
✗ Verify license before operations
✓ Ready to use

IronPDF — Installation Checklist

// ✓ STEP 1: Install package
// Install-Package IronPdf

// ✓ STEP 2: Start coding (license optional)
using IronPdf;

namespace IronPdfExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // Optional: Add license to remove watermark
            // IronPdf.License.LicenseKey = "YOUR-KEY";

            // Works immediately with watermark
            var renderer = new ChromePdfRenderer();
            var pdf = renderer.RenderHtmlAsPdf("<h1>Hello</h1>");
            pdf.SaveAs("output.pdf");
        }
    }
}

Installation checklist:

✓ Install package
✓ Start coding immediately
✓ License optional (adds watermark if unlicensed)

Docotic.PDF — Basic HTML to PDF Checklist

using System;
using BitMiracle.Docotic;
using BitMiracle.Docotic.Pdf;
using BitMiracle.Docotic.Pdf.HtmlToPdf;

namespace DococticHtmlExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // ✗ REQUIRED: Set license first
            LicenseManager.AddLicenseData("YOUR-LICENSE-KEY");

            // ✗ STEP 1: Create HtmlToPdf converter
            using (var converter = new HtmlToPdfConverter())
            {
                // ✗ STEP 2: Configure options
                var options = new PdfConversionOptions
                {
                    PageWidth = 210,  // mm (A4)
                    PageHeight = 297, // mm (A4)
                    MarginLeft = 10,
                    MarginRight = 10,
                    MarginTop = 10,
                    MarginBottom = 10
                };

                // ✗ STEP 3: HTML string
                string html = @"
                    <html>
                    <head>
                        <style>
                            body { font-family: Arial; margin: 20px; }
                            h1 { color: #333; }
                        </style>
                    </head>
                    <body>
                        <h1>Hello from Docotic.PDF</h1>
                        <p>Sample content with <strong>formatting</strong>.</p>
                    </body>
                    </html>";

                // ✗ STEP 4: Convert HTML to PDF
                using (var pdf = converter.Convert(html, options))
                {
                    // ✗ STEP 5: Save PDF
                    pdf.Save("output.pdf");

                    Console.WriteLine("✓ PDF created successfully");
                }
            }
        }
    }
}

Code checklist:

✗ Set license key
✗ Create HtmlToPdfConverter
✗ Configure PdfConversionOptions
✗ Call Convert method
✗ Save result
✓ Clean using statements for disposal

IronPDF — Basic HTML to PDF Checklist

using System;
using IronPdf;

namespace IronPdfHtmlExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // ✓ STEP 1: Create renderer
            var renderer = new ChromePdfRenderer();

            // ✓ STEP 2: Render HTML
            string html = @"
                <html>
                <head>
                    <style>
                        body { font-family: Arial; margin: 20px; }
                        h1 { color: #333; }
                    </style>
                </head>
                <body>
                    <h1>Hello from IronPDF</h1>
                    <p>Sample content with <strong>formatting</strong>.</p>
                </body>
                </html>";

            var pdf = renderer.RenderHtmlAsPdf(html);

            // ✓ STEP 3: Save
            pdf.SaveAs("output.pdf");
        }
    }
}

Code checklist:

✓ Create renderer
✓ Render HTML
✓ Save PDF
✓ Done

For HTML string details, see the HTML string to PDF guide.

Docotic.PDF — URL to PDF Checklist

using System;
using BitMiracle.Docotic;
using BitMiracle.Docotic.Pdf;
using BitMiracle.Docotic.Pdf.HtmlToPdf;

namespace DococticUrlExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // ✗ Set license
            LicenseManager.AddLicenseData("YOUR-LICENSE-KEY");

            // ✗ Create converter
            using (var converter = new HtmlToPdfConverter())
            {
                // ✗ Configure options
                var options = new PdfConversionOptions();

                // ✗ OPTIONAL: Configure delay for JavaScript
                // Verify exact property name in docs for your version
                // options.JavaScriptDelayMilliseconds = 1000; // (verify in docs)

                // ✗ URL to convert
                string url = "https://example.com";

                // ✗ Convert URL
                // Note: Authentication/headers configuration unclear from docs
                using (var pdf = converter.ConvertUrl(url, options))
                {
                    // ✗ Save
                    pdf.Save("url_output.pdf");

                    Console.WriteLine("✓ URL converted");
                }
            }
        }
    }
}

URL rendering checklist:

✗ License key set
✗ HtmlToPdfConverter created
✗ URL passed to ConvertUrl method
✗ JavaScript delay configured (if needed—verify API)
✗ Authentication options (unclear from docs—verify)
✓ Result saved

IronPDF — URL to PDF Checklist

using System;
using IronPdf;

namespace IronPdfUrlExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // ✓ Create renderer
            var renderer = new ChromePdfRenderer();

            // ✓ Configure timeout
            renderer.RenderingOptions.Timeout = 120;

            // ✓ Render URL
            var pdf = renderer.RenderUrlAsPdf("https://example.com");

            // ✓ Save
            pdf.SaveAs("url_output.pdf");
        }
    }
}

URL rendering checklist:

✓ Create renderer
✓ Configure options
✓ Render URL
✓ Save PDF

For URL rendering with authentication, see the URL to PDF documentation.

Docotic.PDF — HTML File Checklist

using System;
using System.IO;
using BitMiracle.Docotic;
using BitMiracle.Docotic.Pdf;
using BitMiracle.Docotic.Pdf.HtmlToPdf;

namespace DococticFileExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // ✗ License key
            LicenseManager.AddLicenseData("YOUR-LICENSE-KEY");

            // ✗ Create HTML file
            string htmlFile = "template.html";
            string html = @"
                <html>
                <head>
                    <link rel='stylesheet' href='styles/main.css'>
                </head>
                <body>
                    <img src='images/logo.png'>
                    <h1>HTML File</h1>
                </body>
                </html>";
            File.WriteAllText(htmlFile, html);

            // ✗ Create converter
            using (var converter = new HtmlToPdfConverter())
            {
                // ✗ Configure base path for assets
                var options = new PdfConversionOptions();
                // Base path for relative URLs
                // Exact property name - verify in docs
                // options.BasePath = Path.GetDirectoryName(htmlFile);

                // ✗ Read HTML content
                string htmlContent = File.ReadAllText(htmlFile);

                // ✗ Convert
                using (var pdf = converter.Convert(htmlContent, options))
                {
                    // ✗ Save
                    pdf.Save("file_output.pdf");
                }
            }
        }
    }
}

File rendering checklist:

✗ License key set
✗ HTML file created/exists
✗ Base path configured for assets
✗ HTML content read
✗ Converter created
✗ Convert called
✓ PDF saved

IronPDF — HTML File Checklist

using System;
using IronPdf;

namespace IronPdfFileExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // ✓ Create renderer
            var renderer = new ChromePdfRenderer();

            // ✓ Render file (auto-resolves assets)
            var pdf = renderer.RenderHtmlFileAsPdf("template.html");

            // ✓ Save
            pdf.SaveAs("file_output.pdf");
        }
    }
}

File rendering checklist:

✓ Create renderer
✓ Render file
✓ Assets auto-resolved
✓ Save PDF

For file rendering, see the HTML file to PDF guide.

Docotic.PDF — Async Operations Checklist

using System;
using System.Threading.Tasks;
using BitMiracle.Docotic;
using BitMiracle.Docotic.Pdf;
using BitMiracle.Docotic.Pdf.HtmlToPdf;

namespace DococticAsyncExample
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // ✗ License key
            LicenseManager.AddLicenseData("YOUR-LICENSE-KEY");

            // ✗ Async support unclear from docs
            // May need to wrap synchronous calls
            await Task.Run(() =>
            {
                using (var converter = new HtmlToPdfConverter())
                {
                    var options = new PdfConversionOptions();

                    using (var pdf = converter.Convert("<h1>Async</h1>", options))
                    {
                        pdf.Save("async_output.pdf");
                    }
                }
            });

            // ✗ OR check if ConvertAsync exists (verify in docs)
            // using (var converter = new HtmlToPdfConverter())
            // {
            //     var options = new PdfConversionOptions();
            //     using (var pdf = await converter.ConvertAsync("<h1>Async</h1>", options))
            //     {
            //         pdf.Save("async_output.pdf");
            //     }
            // }
        }
    }
}

Async checklist:

✗ License key set
✗ Check if native async methods exist
✗ May require Task.Run wrapping
✗ Async patterns not clearly documented

IronPDF — Async Operations Checklist

using System;
using System.Threading.Tasks;
using IronPdf;

namespace IronPdfAsyncExample
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // ✓ Create renderer
            var renderer = new ChromePdfRenderer();

            // ✓ Native async support
            var pdf = await renderer.RenderHtmlAsPdfAsync("<h1>Async</h1>");

            // ✓ Async save
            await pdf.SaveAsAsync("async_output.pdf");
        }
    }
}

Async checklist:

✓ Native async methods
✓ Full async/await support
✓ No manual Task wrapping needed

API Mapping Reference

Docotic.PDF Operation	IronPDF Equivalent
`LicenseManager.AddLicenseData(key)`	`License.LicenseKey = key` (optional)
`new HtmlToPdfConverter()`	`new ChromePdfRenderer()`
`new PdfConversionOptions()`	`renderer.RenderingOptions`
`converter.Convert(html, options)`	`renderer.RenderHtmlAsPdf(html)`
`converter.ConvertUrl(url, options)`	`renderer.RenderUrlAsPdf(url)`
`pdf.Save(path)`	`pdf.SaveAs(path)`
`options.PageWidth/PageHeight`	`renderer.RenderingOptions.PaperSize`
`options.Margin*`	`renderer.RenderingOptions.Margin*`
Check docs for ConvertAsync	`renderer.RenderHtmlAsPdfAsync(html)`
Manual base path config	Auto-detected

Comprehensive Feature Comparison

Category	Feature	Docotic.PDF	IronPDF
Status	Active Development	✓ Yes	✓ Yes
	Product Focus	PDF manipulation	HTML-to-PDF
	HTML Module	✗ Separate add-on	✓ Core
Support	Commercial Support	✓ Available	✓ Included
	Free Licenses	✓ For eligible projects	✓ For dev/test
	Documentation	✗ Scattered	✓ Unified
	Code Examples	✓ GitHub samples	✓ Extensive
Content Creation	HTML5 Support	✓ Chromium	✓ Chromium
	CSS3 Support	✓ Complete	✓ Complete
	JavaScript	✓ Full	✓ Full
	Modern Frameworks	✓ Supported	✓ Supported
	Responsive Design	✓ Supported	✓ Supported
	Web Fonts	✓ Automatic	✓ Automatic
PDF Operations	HTML to PDF	✓ Via add-on	✓ Native
	URL to PDF	✓ Via add-on	✓ Native
	Text Extraction	✓ Excellent	✓ Good
	PDF Editing	✓ Comprehensive	✗ Limited
	Form Fields	✓ Excellent	✓ Good
Architecture	Native Dependencies	✓ None (managed)	✓ None (managed)
	Package Count	✗ 2 (core + addon)	✓ 1
	License Requirement	✗ Always	✓ Optional
	Async Support	✗ Unclear	✓ Full
Installation	Complexity	✗ Moderate	✓ Simple
	License Setup	✗ Required first	✓ Optional
	Trial Access	✗ Email request	✓ Instant
Development	Learning Curve	✗ Moderate	✓ Shallow
	API Clarity	✓ Clean	✓ Clear
	Error Messages	✓ Good	✓ Detailed

Setup Checklist Comparison

Docotic.PDF Setup Checklist

✗ Install core package (BitMiracle.Docotic.Pdf)
✗ Install HTML add-on (BitMiracle.Docotic.Pdf.HtmlToPdf)
✗ Visit website to request trial license
✗ Wait for email with license key
✗ Add license key to code with LicenseManager
✗ Verify license loads correctly
✓ Begin development

Time to first PDF: 30+ minutes (waiting for trial license email)

IronPDF Setup Checklist

✓ Install package (IronPdf)
✓ Begin development
✓ Add license key later to remove watermark (optional)

Time to first PDF: 2 minutes

License Management Checklist

Docotic.PDF License

✗ Required for all operations (even read/write)
✗ Trial: 31 days after email request
✗ Must be set before any PDF operation
✗ License validation errors block all functionality
✓ Free licenses available for eligible projects
✓ Royalty-free commercial licenses

IronPDF License

✓ Optional for development (adds watermark)
✓ Trial: 30 days instant access
✓ Full functionality during trial
✓ Watermark-only restriction when unlicensed
✓ Set license anytime to remove watermark
✓ Royalty-free commercial licenses

Common Issues Checklist

Docotic.PDF Common Issues:

✗ "License not valid" - forgot to set license before operations
✗ Trial license request delayed - email spam folder
✗ Two packages needed - core + HtmlToPdf add-on
✗ Async patterns unclear - check docs for version
✗ Base path for assets - verify property name in docs

IronPDF Common Issues:

✓ Watermark appears - add license key to remove
✓ All other operations work without license

Installation Comparison

Docotic.PDF:

# Step 1: Install core
dotnet add package BitMiracle.Docotic.Pdf

# Step 2: Install HTML add-on
dotnet add package BitMiracle.Docotic.Pdf.HtmlToPdf

# Step 3: Request trial license
# Visit: https://bitmiracle.com/pdf-library/
# Fill form, wait for email

# Step 4: Add license to code

using BitMiracle.Docotic;
using BitMiracle.Docotic.Pdf;
using BitMiracle.Docotic.Pdf.HtmlToPdf;

// Required before any operation
LicenseManager.AddLicenseData("YOUR-KEY");

IronPDF:

# Step 1: Install
dotnet add package IronPdf

# Done - start coding

using IronPdf;
using IronPdf.Rendering;

// Optional - add later to remove watermark
// IronPdf.License.LicenseKey = "YOUR-KEY";

Conclusion

BitMiracle Docotic.PDF provides a comprehensive PDF manipulation library with excellent text extraction, form handling, and editing capabilities. The HtmlToPdf add-on uses Chromium for pixel-perfect rendering. Teams needing extensive PDF manipulation features alongside HTML-to-PDF conversion may find Docotic.PDF's modular architecture matches their requirements. The 100% managed code with no native dependencies is an architectural strength.

The operational checklist surfaces where complexity emerges: two packages to install, trial license requiring email request, license key mandatory before any operations (including development), and async support patterns requiring documentation verification. For teams where PDF manipulation is primary and HTML rendering secondary, working through this checklist may be justified.

Migration consideration centers on workflow focus. If your codebase shows more HTML-to-PDF operations than PDF manipulation (text extraction, form filling, page editing), the two-package architecture and license-first requirement may add friction. Production deployments benefit from instant trial access for testing, single-package installation for CI/CD, and clear async patterns for web applications.

IronPDF's single-package installation with optional licensing eliminates the checklist complexity. The ChromePdfRenderer provides immediate HTML-to-PDF functionality without license configuration, adding only a watermark until licensed. For comprehensive HTML-to-PDF examples, review the HTML to PDF tutorial, and see the ChromePdfRenderer API documentation for configuration details.

What's your experience managing multi-package dependencies and trial license workflows in .NET projects?

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:

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.