DEV Community: dotnet

Migrating from ComPDFKit to IronPDF: From Install to Ship

IronSoftware — Fri, 05 Jun 2026 17:22:39 +0000

Performance numbers are the first thing people reach for when justifying a library migration to management. They're also the easiest to misrepresent. A benchmark that doesn't match your workload is worse than no benchmark at all.

This article takes a benchmark-aware approach to migrating from ComPDFKit to IronPDF. That means: showing you how to measure what actually matters in your use case, providing before/after code for the operations most teams care about, and flagging where the libraries differ in architecture in ways that will affect throughput under real load. No synthetic numbers that don't apply to your environment.

You'll leave with working migration code, an API mapping table, and a repeatable benchmark harness you can run against your own workloads, because the only relevant performance number is the one measured with your data.

Why Migrate

Teams using ComPDFKit on .NET typically adopted it for PDF viewing, annotation, or interactive document scenarios. Server-side batch generation and HTML-to-PDF are where friction tends to appear:

HTML-to-PDF workloads. ComPDFKit's .NET SDK does not include a native HTML/CSS rendering engine. The vendor's documented path for HTML conversion is a separate cloud Conversion API. If browser-quality HTML rendering is a core requirement, an in-process Chromium renderer is a structurally different fit.
Server-side batch generation. Libraries optimized for interactive viewers have different performance characteristics at scale than batch generators. Measure your workload specifically.
Cross-platform server deployment. ComPDFKit ships SDKs for Windows, Linux, and macOS, but cross-platform server scenarios still benefit from confirming the deployment story matches your target environment.
NuGet package management. Native binary distribution outside of NuGet adds CI/CD pipeline complexity. IronPDF's runtime binaries are pulled through NuGet.
API surface for common operations. Merge, watermark, and encrypt require more setup steps in a viewer-focused SDK than in a generation-focused one.
.NET version compatibility. IronPDF supports .NET Framework 4.6.2+, .NET Core 3.1+, and .NET 5/6/7/8/9. Confirm your ComPDFKit package matches your target framework.
Memory footprint under load. Viewer-optimized libraries sometimes carry rendering state that adds overhead in stateless server contexts.
License model alignment. Confirm ComPDFKit licensing terms cover server/SaaS use against the vendor's current pricing page.
Async/parallel generation. IronPDF exposes RenderHtmlAsPdfAsync and supports parallel rendering through renderer reuse; confirm the equivalent guidance for ComPDFKit's CPDFDocument lifecycle.
Azure/cloud deployment. IronPDF documents Azure App Service, AWS Lambda, and Docker deployment paths.

Comparison Table

Aspect	ComPDFKit	IronPDF
Focus	PDF viewer, annotation, forms, editing	HTML-to-PDF, edit, merge, security
Pricing	Per-app or per-platform	Per-developer or royalty-free
API Style	SDK-style, C++ influenced, verbose	High-level renderer + document model
Learning Curve	Steep for server-side; designed for UI integration	Gradual for HTML; renderer-first mental model
HTML Rendering	No native HTML/CSS engine in the .NET SDK	Chromium-based
Page Indexing	0-based	0-based
Memory Cleanup	Manual `Release()` calls	Automatic (GC)
Namespace	`ComPDFKit.PDFDocument`, `ComPDFKit.PDFPage`, etc.	`IronPdf`

Migration Complexity Assessment

Effort by Feature

Feature	Effort	Notes
HTML string to PDF	Low to Medium	New capability vs ComPDFKit's manual layout path
HTML file to PDF	Low to Medium	Same
Merge PDFs	Medium	API model differs
Split PDFs	Medium	`CopyPages` ranges in IronPDF
Watermark	Medium	`CPDFWatermark` vs IronPDF `ApplyWatermark` HTML
Password protection	Low to Medium	Both support; property names differ
Annotation migration	High	ComPDFKit annotation model is rich; test parity
Form field editing	Medium	IronPDF exposes `pdf.Form.SetFieldValue`
Server-side batch	Medium	Architecture change; test throughput
Async / parallel	Medium	IronPDF supports `Async` variants and `Parallel.ForEach` patterns

Decision Matrix

Business Scenario	Recommendation
Interactive PDF viewer/editor application	Evaluate carefully. ComPDFKit is designed for this; IronPDF is not a UI viewer
Server-side HTML-to-PDF batch generation	IronPDF's Chromium renderer is a better fit
API-driven PDF operations (merge, stamp, encrypt)	Both work; IronPDF API is more concise for these ops
Mixed viewer + server generation	May need both libraries. Evaluate consolidation cost

Before You Start: Set Up a Measurement Baseline

Before removing ComPDFKit, capture timing data for your most frequent operations. This gives you apples-to-apples comparison after migration.

using System;
using System.Diagnostics;

// Benchmark harness -- run against your actual workload before migration
class PdfBenchmark
{
    static void Main()
    {
        int iterations = 50;
        var sw = Stopwatch.StartNew();

        for (int i = 0; i < iterations; i++)
        {
            // Run your most common ComPDFKit operation here
            // Example: ConvertHtmlToPdf("sample.html", $"out_{i}.pdf")
        }

        sw.Stop();
        double avgMs = (double)sw.ElapsedMilliseconds / iterations;
        Console.WriteLine($"ComPDFKit average: {avgMs:F1} ms per operation ({iterations} iterations)");
        Console.WriteLine($"Total: {sw.ElapsedMilliseconds} ms");
    }
}

Run this benchmark. Record the numbers. Then run the equivalent IronPDF benchmark after migration. The delta in your environment is the only number that matters.

Find ComPDFKit references in your codebase:

# Find all ComPDFKit imports
rg "using ComPDFKit" --type cs -l

# Find SDK initialization patterns
rg "CPDFSDKVerifier|LicenseVerify" --type cs

# Find document operations
rg "CPDFDocument|CPDFPage|CPDFAnnotation" --type cs

Install IronPDF:

# Add IronPDF (keep ComPDFKit while running parallel benchmarks)
dotnet add package IronPdf
dotnet restore

Quick Start Migration (3 Steps)

Step 1: License Configuration

Before (ComPDFKit):

using ComPDFKit.PDFDocument;

class Program
{
    static void Main()
    {
        // ComPDFKit license verification -- must run before document operations
        CPDFSDKVerifier.LicenseVerify(
            "YOUR-LICENSE-KEY", "YOUR-LICENSE-KEY",
            "YOUR-LICENSE-KEY", "YOUR-LICENSE-KEY");
    }
}

After (IronPDF):

using IronPdf;

// https://ironpdf.com/how-to/license-keys/
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

Step 2: Namespace Imports

Before (ComPDFKit):

using ComPDFKit.PDFDocument;
using ComPDFKit.PDFPage;
using ComPDFKit.PDFAnnotation;
using ComPDFKit.Import;

After:

using IronPdf;

Step 3: Basic HTML-to-PDF

Before (ComPDFKit):

// ComPDFKit's .NET SDK has no native HTML/CSS renderer. To approximate
// HTML output you would either lay out text and images manually via the
// page editor, or call ComPDFKit's separate cloud Conversion API
// (https://api.compdf.com/api-libraries) as a different SKU.

using ComPDFKit.PDFDocument;

class Program
{
    static void Main()
    {
        var document = CPDFDocument.CreateDocument();
        document.InsertPage(0, 595, 842, string.Empty);
        // Manual page editor operations would go here to place text/images.
        document.WriteToFilePath("output.pdf");
        document.Release();
    }
}

After (IronPDF):

using System;
using IronPdf;

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

        var renderer = new ChromePdfRenderer();
        using var pdf = renderer.RenderHtmlAsPdf(
            "<html><body><h1>Hello</h1></body></html>"
        );
        pdf.SaveAs("output.pdf");
        Console.WriteLine("Done");
    }
}

API Mapping Tables

Namespace Mapping

ComPDFKit	IronPDF	Notes
`ComPDFKit.PDFDocument`	`IronPdf`	Core document operations
`ComPDFKit.PDFPage`	`IronPdf`	Page-level operations
`ComPDFKit.PDFAnnotation`	`IronPdf`	Annotations
`ComPDFKit.PDFWatermark`	`IronPdf`	Watermarks
`ComPDFKit.Import`	`IronPdf`	Import/conversion

Core Class Mapping

ComPDFKit	IronPDF Class	Description
`CPDFDocument`	`PdfDocument`	PDF document object
`CPDFPage`	`PdfPage`	Page reference
`CPDFSDKVerifier`	`IronPdf.License`	SDK/license initialization
`CPDFWatermark`	`ApplyWatermark(html)`	Watermark application
Manual layout / cloud Conversion API	`ChromePdfRenderer`	HTML-to-PDF rendering

Document Loading Methods

Operation	ComPDFKit	IronPDF
Load from file	`CPDFDocument.InitWithFilePath(path)`	`PdfDocument.FromFile(path)`
Load from stream	`CPDFDocument.InitWithStream(stream)`	`PdfDocument.FromStream(stream)`
Load from bytes	Via stream	`PdfDocument.FromBinaryData(bytes)`
Create from HTML	Not natively supported	`renderer.RenderHtmlAsPdf(html)`
Save to file	`document.WriteToFilePath(path)`	`pdf.SaveAs(path)`
Save to bytes	Via stream	`pdf.BinaryData`

Page Operations

Operation	ComPDFKit	IronPDF
Page count	`document.PageCount`	`pdf.PageCount`
Get page	`document.PageAtIndex(n)`	`pdf.Pages[n]` (0-based)
Remove page	`document.RemovePage(n)`	`pdf.RemovePages(n)`
Insert page	`document.InsertPage(i, w, h, "")`	Via merge / `CopyPages`
Rotate page	`page.SetRotation(angle)`	`pdf.Pages[i].Rotation = ...`
Extract pages	`document.ExtractPages(range)`	`pdf.CopyPages(start, end)`

Merge/Split

Operation	ComPDFKit	IronPDF
Merge PDFs	`doc1.ImportPagesAtIndex(doc2, range, index)`	`PdfDocument.Merge(pdf1, pdf2)`
Extract pages	`document.ExtractPages(range)`	`pdf.CopyPages(start, end)`

Four Complete Before/After Migrations

1. HTML to PDF

Before (ComPDFKit):

using System;
using ComPDFKit.PDFDocument;

// ComPDFKit's .NET SDK does not provide HTML/CSS rendering. Two practical
// options: lay out text and images manually with the page editor, or use
// the separate cloud Conversion API at https://api.compdf.com/api-libraries.

class Program
{
    static void Main()
    {
        // License verification -- must precede document operations
        CPDFSDKVerifier.LicenseVerify(
            "YOUR-LICENSE-KEY", "YOUR-LICENSE-KEY",
            "YOUR-LICENSE-KEY", "YOUR-LICENSE-KEY");

        var document = CPDFDocument.CreateDocument();
        document.InsertPage(0, 595, 842, string.Empty); // blank A4 page

        // Manual editor-based text placement would happen here.
        // For HTML input, ComPDFKit recommends their cloud Conversion API.

        document.WriteToFilePath("output.pdf");
        document.Release();
    }
}

After (IronPDF):

using System;
using IronPdf;

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

        // Chromium-based rendering -- handles modern CSS
        // https://ironpdf.com/how-to/html-string-to-pdf/
        var renderer = new ChromePdfRenderer();

        string html = @"<html>
            <body style='font-family:Arial; padding:40px'>
                <h1 style='color:#1D4ED8'>Invoice #3810</h1>
                <table border='1' style='width:100%'>
                    <tr><th>Item</th><th>Amount</th></tr>
                    <tr><td>Service A</td><td>$800</td></tr>
                    <tr><td>Service B</td><td>$400</td></tr>
                </table>
            </body>
        </html>";

        using var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("invoice.pdf");
        Console.WriteLine("Saved invoice.pdf");
    }
}

2. Merge PDFs

Before (ComPDFKit):

using System;
using ComPDFKit.PDFDocument;
using ComPDFKit.Import;

class Program
{
    static void Main()
    {
        var document1 = CPDFDocument.InitWithFilePath("part1.pdf");
        var document2 = CPDFDocument.InitWithFilePath("part2.pdf");

        // Append all pages from document2 to the end of document1
        string range = $"0-{document2.PageCount - 1}";
        document1.ImportPagesAtIndex(document2, range, document1.PageCount);

        document1.WriteToFilePath("merged.pdf");
        document1.Release();
        document2.Release();
    }
}

After (IronPDF):

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

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

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

        using var merged = PdfDocument.Merge(new List<PdfDocument> { pdf1, pdf2, pdf3 });
        merged.SaveAs("merged.pdf");
        Console.WriteLine($"Merged {merged.PageCount} pages to merged.pdf");
    }
}

3. Watermark

Before (ComPDFKit):

using System;
using ComPDFKit.PDFDocument;
using ComPDFKit.PDFWatermark;

class Program
{
    static void Main()
    {
        var document = CPDFDocument.InitWithFilePath("input.pdf");

        // CPDFDocument.InitWatermark returns a CPDFWatermark, which is then
        // configured and committed with CreateWatermark().
        CPDFWatermark watermark = document.InitWatermark(
            C_Watermark_Type.WATERMARK_TYPE_TEXT);
        watermark.SetText("CONFIDENTIAL");
        watermark.SetFontName("Helvetica");
        watermark.SetFontSize(48);
        watermark.SetTextRGBColor(255, 0, 0);
        watermark.SetRotation(45);
        watermark.SetOpacity(76); // 0..255 (76 ~ 30%)
        watermark.SetVertalign(C_Watermark_Vertalign.WATERMARK_VERTALIGN_CENTER);
        watermark.SetHorizalign(C_Watermark_Horizalign.WATERMARK_HORIZALIGN_CENTER);
        watermark.SetPages($"0-{document.PageCount - 1}");
        watermark.SetFront(true);
        watermark.CreateWatermark();

        document.WriteToFilePath("watermarked.pdf");
        document.Release();
    }
}

After (IronPDF):

using System;
using IronPdf;
using IronPdf.Editing;

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

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

        // https://ironpdf.com/how-to/watermark/
        pdf.ApplyWatermark(
            "<h1 style='color:rgba(255,0,0,0.3);'>CONFIDENTIAL</h1>",
            rotation: 45,
            verticalAlignment: VerticalAlignment.Middle,
            horizontalAlignment: HorizontalAlignment.Center);

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

4. Password Protection

Before (ComPDFKit):

using System;
using ComPDFKit.PDFDocument;

class Program
{
    static void Main()
    {
        var document = CPDFDocument.InitWithFilePath("input.pdf");

        // CPDFPermissionsInfo configures the permission bitmask; Encrypt()
        // applies both passwords and permissions in a single call.
        var permission = new CPDFPermissionsInfo
        {
            AllowsCopying = true,
            AllowsPrinting = true,
            AllowsDocumentChanges = false
        };

        document.Encrypt("user123", "owner456", permission);
        document.WriteToFilePath("protected.pdf");
        document.Release();
    }
}

After (IronPDF):

using System;
using IronPdf;

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

        // https://ironpdf.com/how-to/pdf-permissions-passwords/
        using var pdf = PdfDocument.FromFile("input.pdf");

        pdf.SecuritySettings.UserPassword = "user123";
        pdf.SecuritySettings.OwnerPassword = "owner456";
        pdf.SecuritySettings.AllowUserPrinting =
            IronPdf.Security.PdfPrintSecurity.FullPrintRights;

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

Benchmark Harness: Measure Before You Decide

Run this after migration and compare against your ComPDFKit baseline numbers:

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

class IronPdfBenchmark
{
    // Reuse renderer -- important for fair throughput measurement
    private static readonly ChromePdfRenderer _renderer = new ChromePdfRenderer();

    static async Task Main()
    {
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        int iterations = 50;

        // Sequential benchmark
        Console.WriteLine($"Sequential HTML-to-PDF ({iterations} iterations)...");
        var sw = Stopwatch.StartNew();
        for (int i = 0; i < iterations; i++)
        {
            using var pdf = await _renderer.RenderHtmlAsPdfAsync(GetHtml(i));
            // Don't save to disk -- measures render time only
        }
        sw.Stop();
        double seqAvg = (double)sw.ElapsedMilliseconds / iterations;
        Console.WriteLine($"Sequential avg: {seqAvg:F1} ms/render");

        // Parallel benchmark
        Console.WriteLine($"\nParallel HTML-to-PDF ({iterations} iterations, 4-way)...");
        sw.Restart();
        var tasks = new List<Task>();
        // https://ironpdf.com/examples/parallel/
        for (int i = 0; i < iterations; i++)
        {
            int j = i;
            tasks.Add(Task.Run(async () =>
            {
                using var pdf = await _renderer.RenderHtmlAsPdfAsync(GetHtml(j));
            }));
            if (tasks.Count >= 4)
            {
                await Task.WhenAll(tasks);
                tasks.Clear();
            }
        }
        if (tasks.Count > 0) await Task.WhenAll(tasks);
        sw.Stop();
        double parAvg = (double)sw.ElapsedMilliseconds / iterations;
        Console.WriteLine($"Parallel avg: {parAvg:F1} ms/render effective");
    }

    static string GetHtml(int i) => $@"<html>
        <body style='font-family:Arial'>
            <h1>Document #{i}</h1>
            <p>Generated at {DateTime.Now:O}</p>
        </body>
    </html>";
}

Compare seqAvg and parAvg against your ComPDFKit baseline measurements.

Critical Migration Notes

SDK Initialization vs License Key

ComPDFKit uses an SDK initialization step (CPDFSDKVerifier.LicenseVerify(...)) that must run before any document operation. IronPDF's license is a static string set once. The initialization model is simpler but the pattern in web applications differs:

// Startup.cs / Program.cs -- set once, early
IronPdf.License.LicenseKey = Environment.GetEnvironmentVariable("IRONPDF_KEY");

Don't set the license key inside hot paths or per-request code.

Manual Memory Cleanup

ComPDFKit requires document.Release() for every CPDFDocument instance (and Release() on CPDFPage / CPDFTextPage handles you walk). Missing one leaks the underlying native object. IronPDF objects are managed; using is optional but works with PdfDocument. Remove every Release() call when migrating.

Page Indexing

Both libraries use 0-based page indexing, so loops that walk pages from 0 to PageCount - 1 carry over unchanged. The difference is access shape: document.PageAtIndex(n) in ComPDFKit becomes pdf.Pages[n] in IronPDF.

Annotation Round-Trips

If your application creates annotations and expects them to survive PDF round-trips (save, reload, verify), test annotation persistence with IronPDF before committing to the migration. Annotation formats are standardized in PDF, but library implementations differ in which annotation types and properties they preserve.

Performance Considerations

Chromium Renderer Process

IronPDF spawns a Chromium renderer process. This process startup is the largest latency contributor for the first render. Reusing ChromePdfRenderer across requests amortizes this cost. In a web application, register it as a singleton.

Memory Under Load

Run a memory profile under your target concurrent load. The Chromium renderer's memory behavior under concurrent requests is different from an in-process renderer. Test at your expected peak concurrency, not just sequentially.

Disk vs Memory Output

If your downstream process consumes the PDF as bytes (upload to S3, email attachment), avoid writing to disk:

using var pdf = renderer.RenderHtmlAsPdf(html);
byte[] bytes = pdf.BinaryData; // No disk write

// Or stream directly
using var stream = new MemoryStream();
pdf.Stream.CopyTo(stream);

See memory stream docs for patterns.

Async Parallel Workloads

See async rendering docs and parallel examples for patterns that scale under load. The benchmark harness above gives you a starting measurement point.

Migration Checklist

Pre-Migration

[ ] Run benchmark harness against ComPDFKit. Record baseline numbers
[ ] Run rg "ComPDFKit|CPDFDocument" --type cs -l to find affected files
[ ] Identify all CPDFSDKVerifier.LicenseVerify(...) and Release() calls
[ ] Check annotation usage. Test IronPDF annotation parity
[ ] Check form field editing. IronPDF exposes pdf.Form.SetFieldValue
[ ] Confirm .NET target version compatibility with IronPDF
[ ] Test IronPDF in parallel with ComPDFKit before removing ComPDFKit
[ ] Identify any 32-bit / platform-specific project configurations

Code Migration

[ ] Add IronPdf NuGet package
[ ] Replace CPDFSDKVerifier.LicenseVerify(...) with IronPdf.License.LicenseKey = "..."
[ ] Remove all .Release() calls on CPDFDocument, CPDFPage, CPDFTextPage
[ ] Replace using ComPDFKit.* with using IronPdf
[ ] Replace CPDFDocument.InitWithFilePath() with PdfDocument.FromFile()
[ ] Replace WriteToFilePath() with SaveAs()
[ ] Replace manual layout / cloud Conversion calls with ChromePdfRenderer.RenderHtmlAsPdf()
[ ] Replace ImportPagesAtIndex merges with PdfDocument.Merge()
[ ] Replace InitWatermark + CPDFWatermark with pdf.ApplyWatermark(html)
[ ] Replace document.Encrypt(...) with SecuritySettings properties
[ ] Replace document.RemovePage(i) with pdf.RemovePages(i)

Testing

[ ] Run IronPDF benchmark harness. Compare to ComPDFKit baseline
[ ] Visual comparison: HTML-to-PDF output quality and CSS rendering
[ ] Memory profile under target peak concurrency
[ ] Annotation round-trip verification (create, save, reload)
[ ] Password protection opens with correct credentials
[ ] Merge page count and order verification
[ ] Linux/cloud deployment test if applicable

Post-Migration

[ ] Remove ComPDFKit NuGet packages (ComPDFKit.NetCore / ComPDFKit.NetFramework) and any native SDK files from build
[ ] Update CI/CD build agent configuration
[ ] Update IronPDF benchmark comparison doc for future reference
[ ] Update internal documentation

That's the Migration

The migration from ComPDFKit to IronPDF is most straightforward when your use case is server-side generation, specifically HTML-to-PDF, merge, stamp, and encrypt. The rougher edges are annotation workflows and any code that depended on ComPDFKit's native rendering pipeline directly.

The benchmark harness matters here more than in most migrations because the performance characteristics of a Chromium-backed renderer versus a native PDF SDK are architecturally different. Don't assume. Measure.

Question for the comments: What's the largest throughput you've achieved with a .NET PDF renderer in production, and how did you get there? Renderer pooling, async batching, pre-warmed processes? Curious about real-world approaches.

The free trial is on NuGet if you want to test before committing.

BitMiracle Docotic.Pdf to IronPDF: The Honest Walkthrough

IronSoftware — Fri, 05 Jun 2026 17:22:05 +0000

Docotic.Pdf is a genuinely well-engineered library. The API is clean, the NuGet package is lean, and it handles PDF parsing and programmatic construction reliably across platforms. The migration decision rarely comes from Docotic.Pdf breaking. It comes from how its HTML-to-PDF story is packaged.

The most common trigger: someone adds a feature that requires rendering a complex HTML template to PDF. Docotic.Pdf supports HTML rendering, but only via the separate BitMiracle.Docotic.Pdf.HtmlToPdf add-on, which exposes an async-only HtmlConverter that downloads its own Chromium on first use. Teams that started on Docotic for parsing or programmatic construction often end up dragging the add-on into the dependency tree just to render one invoice template, and once that's in, the licensing and packaging story starts looking like a candidate for consolidation onto a single renderer-first library.

This article covers the troubleshooting patterns and API mapping for migrating from BitMiracle Docotic.Pdf to IronPDF. The migration is relatively low-drama because both are managed .NET libraries with no COM dependencies. The complexity concentrates in two places: the different mental model (Docotic's document construction plus a separate add-on for HTML vs IronPDF's unified renderer + document model), and any text extraction or annotation code that relies on Docotic's parse-side API.

Why Migrate

Neutral triggers teams run into:

HTML-to-PDF requires an add-on. Docotic.Pdf's HTML rendering lives in the separate BitMiracle.Docotic.Pdf.HtmlToPdf package. That add-on uses an async-only HtmlConverter and downloads its own Chromium on first use, so the dependency tree grows when you need HTML support.
CSS rendering fidelity. Programmatic document construction in Docotic doesn't match what a designer produces in HTML/CSS. IronPDF's Chromium renderer closes this gap for HTML-based workflows without a separate add-on.
Template maintenance burden. Programmatic PDF construction (positioning text objects, drawing borders) requires developer changes for every layout update. HTML templates can be maintained by non-developers.
Font handling complexity. Docotic requires explicit font loading and glyph management on the canvas side. IronPDF's Chromium renderer handles font resolution as a browser would.
Deployment simplicity. Both are managed .NET, but IronPDF's all-in-one approach (render + edit + security) reduces the number of libraries and add-on packages in the dependency tree.
Async / parallel patterns. Both libraries support concurrent use; evaluate under your specific load patterns.
API surface for new developers. ChromePdfRenderer.RenderHtmlAsPdf(html) is a shorter onboarding path than document construction for HTML-heavy workloads.
PDF/A output workflow. Both support PDF/A; test against your target compliance profile to compare output.
License changes. Evaluate current Docotic.Pdf pricing at bitmiracle.com for your usage scenario, including any per-add-on costs.
Consolidation. Teams combining parsing (Docotic) and rendering (HtmlToPdf add-on or something else) sometimes consolidate to one library.

Comparison Table

Aspect	BitMiracle Docotic.Pdf	IronPDF
Focus	Parse, edit, construct, extract; HTML via add-on	HTML-to-PDF, edit, merge, security
Pricing	Free with watermark; commercial license	Per-developer or royalty-free
API Style	Document object model, explicit construction	High-level renderer + document model
Learning Curve	Gradual for parsing; steep for programmatic layout	Gradual for HTML; moderate for parse ops
HTML Rendering	Via `BitMiracle.Docotic.Pdf.HtmlToPdf` add-on (Chromium)	Chromium-based, built-in
Page Indexing	0-based	0-based
Thread Safety	Reuse `HtmlConverter`; audit concurrent document access	Renderer reusable; see IronPDF parallel examples
Namespace	`BitMiracle.Docotic.Pdf` (HtmlConverter lives here too)	`IronPdf`

Migration Complexity Assessment

Effort by Feature

Feature	Effort	Notes
HTML string to PDF	Low	Both support it; IronPDF is built-in, Docotic uses the HtmlToPdf add-on
HTML file to PDF	Low	Same
Merge PDFs	Low	Both support; Docotic uses `Append(path)`, IronPDF uses `PdfDocument.Merge`
Split/extract pages	Medium	Docotic copies pages page-by-page; IronPDF uses `CopyPages`
Text watermark	Medium	Docotic drawing model vs IronPDF stamper
Image watermark	Medium	Coordinate model differs
Password protection	Low	Both support owner/user passwords
Text extraction	Medium-High	Docotic's text model is detailed (per-word bounds); audit IronPDF parity
Annotation handling	High	Docotic annotations API is rich; audit IronPDF coverage
Form field editing	Medium	Both have form APIs; method signatures differ
PDF/A output	Medium	Test against your validator

Decision Matrix

Business Scenario	Recommendation
Primarily programmatic PDF construction, no HTML	Evaluate whether Docotic's model serves you; migration cost may exceed benefit
HTML templates requiring browser-quality CSS	IronPDF's built-in Chromium renderer removes the add-on requirement
Heavy text extraction and parse workflows	Audit IronPDF's extraction API against your Docotic usage before committing
Mixed HTML + parse requirements	IronPDF can handle both; test extraction output quality

Before You Start

Prerequisites:

.NET Framework 4.6.2+, .NET Core 3.1+, or .NET 5/6/7/8/9 (IronPDF supports the full modern range)
IronPDF license key (license setup)
Baseline PDF outputs captured for visual regression

Find all Docotic.Pdf references:

# Find all files with Docotic imports
rg "using BitMiracle" --type cs -l

# Find all PdfDocument usages (Docotic's main class)
rg "PdfDocument" --type cs

# Find text extraction calls
rg "GetText|GetWords|TextData" --type cs

# Find annotation references
rg "Annotations|PdfAnnotation" --type cs

# Find drawing / graphics operations
rg "PdfCanvas|DrawString|DrawLine|HtmlConverter" --type cs

Remove Docotic, add IronPDF:

dotnet remove package BitMiracle.Docotic.Pdf
dotnet remove package BitMiracle.Docotic.Pdf.HtmlToPdf
dotnet add package IronPdf
dotnet restore

PowerShell: Uninstall-Package BitMiracle.Docotic.Pdf (plus the HtmlToPdf add-on if installed) then Install-Package IronPdf.

Quick Start Migration (3 Steps)

Step 1: License Configuration

Before (Docotic.Pdf):

using BitMiracle.Docotic.Pdf;

// Docotic uses a license string set before any API call
PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");

After (IronPDF):

using IronPdf;

// https://ironpdf.com/how-to/license-keys/
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

Step 2: Namespace Imports

Before:

using BitMiracle.Docotic.Pdf;
// HtmlConverter (from the HtmlToPdf add-on) also lives in BitMiracle.Docotic.Pdf

After:

using IronPdf;

Step 3: Basic PDF Operation

Before (Docotic, opening a PDF and extracting text):

using BitMiracle.Docotic.Pdf;

PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");
using var doc = new PdfDocument("input.pdf");
string text = doc.GetText();
Console.WriteLine(text);

After (IronPDF):

using IronPdf;

IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
using var pdf = PdfDocument.FromFile("input.pdf");
// https://ironpdf.com/how-to/extract-text-and-images/
string text = pdf.ExtractAllText();
Console.WriteLine(text);

API Mapping Tables

Namespace Mapping

Docotic.Pdf	IronPDF	Notes
`BitMiracle.Docotic.Pdf`	`IronPdf`	Core namespace
`BitMiracle.Docotic.Pdf` (HtmlConverter from HtmlToPdf add-on)	`IronPdf` (`ChromePdfRenderer`)	HTML rendering is built into IronPDF
`BitMiracle.Docotic.Pdf.Layout`	`IronPdf`	Layout via HTML/CSS in IronPDF

Core Class Mapping

Docotic.Pdf Class	IronPDF Class	Description
`PdfDocument`	`PdfDocument`	Same name; different API
`PdfPage`	`PdfPage`	Page object
`HtmlConverter`	`ChromePdfRenderer`	HTML-to-PDF entry point
`PdfCanvas`	No direct equivalent	IronPDF uses HTML/CSS or stamper model for drawing
`PdfInfo.SetLicenseKey()`	`IronPdf.License.LicenseKey`	License setup

Document Loading Methods

Operation	Docotic.Pdf	IronPDF
Load from file	`new PdfDocument("file.pdf")`	`PdfDocument.FromFile("file.pdf")`
Load from stream	`PdfDocument.Load(stream)`	`PdfDocument.FromStream(stream)`
Create from HTML	`await converter.CreatePdfFromStringAsync(html)` (add-on)	`renderer.RenderHtmlAsPdf(html)`
Load from bytes	`PdfDocument.Load(byteArray)`	`PdfDocument.FromBinaryData(byteArray)`

Page Operations

Operation	Docotic.Pdf	IronPDF
Page count	`doc.PageCount`	`pdf.PageCount`
Get page	`doc.Pages[n]` (0-based)	`pdf.Pages[n]` (0-based)
Remove page	`doc.RemovePage(n)`	`pdf.RemovePages(n)`
Page size	`page.Width`, `page.Height`	`pdf.Pages[n].Width`, `pdf.Pages[n].Height`

Merge/Split

Operation	Docotic.Pdf	IronPDF
Merge PDFs	`pdf1.Append("file2.pdf")` (path / Stream / byte[])	`PdfDocument.Merge(pdf1, pdf2)`
Extract pages	Copy pages page-by-page into a new `PdfDocument`	`pdf.CopyPages(start, end)` or `pdf.CopyPages(indices)`

Four Complete Before/After Migrations

1. HTML to PDF

Before (Docotic with the HtmlToPdf add-on):

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

class Program
{
    static async Task Main()
    {
        PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");

        // HtmlConverter is async-only and downloads Chromium on first use
        using var converter = await HtmlConverter.CreateAsync();

        var options = new HtmlConversionOptions();
        options.Page.SetSize(PdfPaperSize.A4);
        options.Page.MarginTop = 20;
        options.Page.MarginBottom = 20;

        string html = @"<html>
            <body style='font-family:Arial; padding:40px'>
                <h1 style='color:#2563EB'>Invoice #2071</h1>
                <p>Amount: <strong>$1,200.00</strong></p>
                <p>Due: 2025-12-01</p>
            </body>
        </html>";

        using var pdf = await converter.CreatePdfFromStringAsync(html, options);
        pdf.Save("invoice.pdf");
        Console.WriteLine("Saved invoice.pdf");
    }
}

After (IronPDF, built-in renderer, no add-on):

using System;
using IronPdf;

class Program
{
    static void Main()
    {
        // https://ironpdf.com/how-to/html-string-to-pdf/
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;
        renderer.RenderingOptions.MarginTop = 20;
        renderer.RenderingOptions.MarginBottom = 20;

        // HTML template — can be maintained separately from code
        string html = @"<html>
            <body style='font-family:Arial; padding:40px'>
                <h1 style='color:#2563EB'>Invoice #2071</h1>
                <p>Amount: <strong>$1,200.00</strong></p>
                <p>Due: 2025-12-01</p>
            </body>
        </html>";

        using var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("invoice.pdf");
        Console.WriteLine("Saved invoice.pdf");
    }
}

2. Merge PDFs

Before (Docotic.Pdf):

using System;
using BitMiracle.Docotic.Pdf;

class Program
{
    static void Main()
    {
        PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");

        // PdfDocument.Append accepts a file path, Stream, or byte[] --
        // not another PdfDocument instance.
        using var pdf1 = new PdfDocument("part1.pdf");
        pdf1.Append("part2.pdf");
        pdf1.Append("part3.pdf");
        pdf1.Save("merged.pdf");

        Console.WriteLine("Merged to merged.pdf");
    }
}

After (IronPDF):

using System;
using IronPdf;

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

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

        using var merged = PdfDocument.Merge(pdf1, pdf2, pdf3);
        merged.SaveAs("merged.pdf");
        Console.WriteLine("Merged to merged.pdf");
    }
}

3. Watermark

Before (Docotic.Pdf):

using System;
using BitMiracle.Docotic.Pdf;

class Program
{
    static void Main()
    {
        PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");

        using var doc = new PdfDocument("input.pdf");

        foreach (var page in doc.Pages)
        {
            var canvas = page.Canvas;

            // Save/restore graphics state around the watermark
            canvas.SaveState();
            canvas.SetTransparency(0.3); // 30% opacity

            canvas.FontSize = 48;
            canvas.FillColor = new PdfRgbColor(200, 0, 0);

            // Rotate around the page center, then draw the watermark text
            canvas.Rotate(45, page.Width / 2, page.Height / 2);
            canvas.DrawString(page.Width / 4, page.Height / 2, "CONFIDENTIAL");

            canvas.RestoreState();
        }

        doc.Save("watermarked.pdf");
        Console.WriteLine("Watermarked PDF saved");
    }
}

After (IronPDF):

using System;
using IronPdf;
using IronPdf.Editing;

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

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

        // https://ironpdf.com/how-to/stamp-text-image/
        var stamper = new TextStamper
        {
            Text = "CONFIDENTIAL",
            FontSize = 48,
            Opacity = 40,
            Rotation = 45,
            VerticalAlignment = VerticalAlignment.Middle,
            HorizontalAlignment = HorizontalAlignment.Center
        };

        // Applies to all pages by default
        pdf.ApplyStamp(stamper);
        pdf.SaveAs("watermarked.pdf");
        Console.WriteLine("Watermarked PDF saved");
    }
}

4. Password Protection

Before (Docotic.Pdf):

using System;
using BitMiracle.Docotic.Pdf;

class Program
{
    static void Main()
    {
        PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");

        using var doc = new PdfDocument("input.pdf");

        // Docotic exposes encryption through a single Encrypt() call
        var permissions = PdfPermissions.Printing |
                          PdfPermissions.ContentExtraction;

        doc.Encrypt(
            ownerPassword: "owner456",
            userPassword: "user123",
            permissions: permissions,
            encryptionAlgorithm: PdfEncryptionAlgorithm.Aes256
        );

        doc.Save("protected.pdf");
        Console.WriteLine("Password protected PDF saved");
    }
}

After (IronPDF):

using System;
using IronPdf;

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

        // https://ironpdf.com/how-to/pdf-permissions-passwords/
        using var pdf = PdfDocument.FromFile("input.pdf");

        pdf.SecuritySettings.UserPassword = "user123";
        pdf.SecuritySettings.OwnerPassword = "owner456";
        pdf.SecuritySettings.AllowUserPrinting =
            IronPdf.Security.PdfPrintSecurity.FullPrintRights;
        pdf.SecuritySettings.AllowUserCopyPasteContent = true;

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

Critical Migration Notes

Text Extraction Differences

Docotic.Pdf has a detailed text model. It exposes per-word bounds via page.GetWords(), with chunk.Bounds.Left and chunk.Bounds.Top for positional data. IronPDF's text extraction returns the text content with less detail on positional data. If your code depends on character- or word-level positioning (e.g., table detection, column parsing), test IronPDF's output carefully before committing.

// Docotic -- detailed word data with bounds
using var doc = new PdfDocument("input.pdf");
foreach (var page in doc.Pages)
{
    foreach (var word in page.GetWords())
    {
        Console.WriteLine($"{word.Text} at ({word.Bounds.Left}, {word.Bounds.Top})");
    }
}

// IronPDF -- text content
// https://ironpdf.com/how-to/extract-text-and-images/
using var pdf = PdfDocument.FromFile("input.pdf");
string allText = pdf.ExtractAllText();
for (int i = 0; i < pdf.PageCount; i++)
{
    string pageText = pdf.ExtractTextFromPage(i);
    Console.WriteLine($"--- Page {i + 1} ---\n{pageText}");
}

If you need positional data after migration, review the current IronPDF text extraction API at https://ironpdf.com/how-to/extract-text-and-images/.

Annotation API Differences

Docotic.Pdf's annotation model is explicit. You create PdfAnnotation objects on page.Annotations with coordinates and properties. IronPDF has annotation support, but the API shape differs. Teams with heavy annotation workflows should test annotation round-trips (create, save, reload, verify) before migrating.

See IronPDF annotations docs for current API.

Page Indexing

Both Docotic.Pdf and IronPDF use 0-based page indexing. This makes the page index migration simpler than moving from 1-based libraries, but still audit all page index references. Off-by-one errors are silent.

Canvas vs Stamper

Docotic's PdfCanvas is a drawing context. You position everything with coordinates and explicit graphics state. IronPDF's stamper model is alignment-based with offsets. If you have precise coordinate requirements for stamps or overlays, check the stamper's IsStampedOnAllPages, HorizontalOffset, and VerticalOffset properties. For highly precise positioning, IronPDF's HTML-stamp approach (stamping a rendered HTML element) often gives finer control than the basic stamper API.

Performance Considerations

Native Dependencies

Docotic.Pdf core is fully managed and has no native interop requirements. Docotic's HtmlToPdf add-on downloads its own Chromium and brings the same browser-process model that IronPDF uses. IronPDF's Chromium renderer requires the standard Linux system libraries (libnss3, libatk-bridge2.0-0, libdrm2, etc.) on Linux deployments. If your existing Docotic workload is parse-only with no HtmlToPdf add-on, the Linux dependency footprint will grow after the migration.

Renderer Reuse

If you're adding HTML-to-PDF as a new capability during this migration, reuse ChromePdfRenderer:

// Register in DI container as singleton in ASP.NET Core
services.AddSingleton<ChromePdfRenderer>();

// Or reuse at class level
private static readonly ChromePdfRenderer _renderer = new ChromePdfRenderer();

Memory Patterns

Docotic.Pdf documents are IDisposable. IronPDF PdfDocument is also IDisposable. The migration shouldn't change disposal discipline if your existing code uses using consistently. Audit for any PdfDocument instances created without using or explicit .Dispose() calls.

Parallel Workloads

If you generate PDFs in parallel, review IronPDF's concurrent rendering behavior at parallel examples. The Chromium renderer process is separate from the managed layer — concurrent requests share the renderer process differently than Docotic's in-process drawing API.

Migration Checklist

Pre-Migration

[ ] Run rg "using BitMiracle" --type cs -l to find all affected files
[ ] Capture baseline PDF outputs for visual regression comparison
[ ] Identify all PdfCanvas drawing operations (will need refactoring to HTML or stamper)
[ ] Note whether the HtmlToPdf add-on (HtmlConverter) is in use. That code maps to ChromePdfRenderer
[ ] Inventory annotation-heavy code. Audit IronPDF annotation API parity
[ ] Check form field editing usage. Audit IronPDF form API
[ ] Note any character-level or per-word text extraction dependencies (page.GetWords())
[ ] Confirm target .NET version supports IronPDF (4.6.2+, Core 3.1+, .NET 5/6/7/8/9)
[ ] Test IronPDF output in parallel with Docotic before removing Docotic

Code Migration

[ ] Replace BitMiracle.Docotic.Pdf (and .HtmlToPdf add-on) NuGet with IronPdf
[ ] Replace PdfInfo.SetLicenseKey() with IronPdf.License.LicenseKey = "..."
[ ] Replace using BitMiracle.Docotic.Pdf with using IronPdf
[ ] Replace new PdfDocument("file.pdf") with PdfDocument.FromFile("file.pdf")
[ ] Replace HtmlConverter.CreateAsync() + CreatePdfFromStringAsync with new ChromePdfRenderer().RenderHtmlAsPdf(...)
[ ] Replace programmatic layout with HTML templates where feasible
[ ] Replace PdfCanvas drawing with TextStamper, ImageStamper, or HTML
[ ] Replace Docotic merge (pdf1.Append("file.pdf")) with PdfDocument.Merge(pdf1, pdf2, ...)
[ ] Replace doc.Encrypt(...) with pdf.SecuritySettings properties
[ ] Replace doc.GetText() / page.GetText() with pdf.ExtractAllText() / pdf.ExtractTextFromPage(i)
[ ] Update annotation handling to IronPDF API. Audit coverage

Testing

[ ] Visual comparison: programmatic layouts vs HTML-rendered equivalents
[ ] Text extraction output. Compare per-word data if positional data is needed
[ ] Annotation round-trip: create, save, reload, verify
[ ] Password protection: open with user password, confirm owner restrictions
[ ] Merge page count and order verification
[ ] Test on Linux if target environment. Verify Chromium system library requirements
[ ] Load test concurrent rendering if parallel workloads exist

Post-Migration

[ ] Remove BitMiracle.Docotic.Pdf and BitMiracle.Docotic.Pdf.HtmlToPdf from all project files
[ ] Update Docker images for Linux deployment with IronPDF Chromium dependencies
[ ] Update internal documentation on PDF generation approach
[ ] Archive Docotic license for audit purposes

One Last Thing

The Docotic.Pdf to IronPDF migration is generally straightforward for the common operations: loading, merging, and password protection. The complexity concentrates in annotation workflows and text extraction. If either is central to your use case, run a spike against the IronPDF API before committing to the migration path.

The real win for most teams isn't the API swap. It's collapsing the parse library plus the HtmlToPdf add-on plus the licensing for both into a single package that renders HTML like a browser. That removes the programmatic layout code no one wants to maintain, and it removes the add-on coordination that nobody enjoys auditing either.

Question for the comments: For teams that moved from a parse-focused PDF library (Docotic, iText, etc.) to a renderer-first library. How did you handle the text extraction use cases that didn't port cleanly? Did you keep the parse library alongside the renderer, or find a different approach?

The free trial is on NuGet if you want to test before committing.

Moving from Aspose.PDF to IronPDF: What Changes

IronSoftware — Fri, 05 Jun 2026 17:21:14 +0000

The migration story rarely starts with a decision meeting.

It starts with a build pipeline failing at 2 AM, or a sprint retrospective where someone says "the PDF rendering is wrong again on Linux," or a licensing renewal email that lands in the wrong inbox at the wrong budget quarter. Teams don't abandon libraries they chose deliberately. They eventually reach a point where the cost of staying exceeds the cost of switching.

This article walks through what a migration from Aspose.PDF to IronPDF actually looks like in C# code. You'll leave with working before/after snippets, a full API mapping table, and a printable migration checklist. You don't have to adopt IronPDF at the end. The migration patterns, grep commands, and checklist apply to any PDF library transition.

Why Migrate

Both Aspose.PDF and IronPDF are serious libraries with active maintenance. This isn't about one being broken. It's about the specific friction teams run into depending on their use case and deployment context.

Neutral migration triggers teams commonly cite:

HTML rendering fidelity. Aspose.PDF uses a proprietary HTML renderer, not a browser engine. Teams running complex CSS (Flexbox, Grid, custom fonts, @page rules) often encounter layout drift that requires workarounds. IronPDF uses an embedded Chromium renderer.
Linux/container deployment complexity. Aspose.PDF on Linux requires additional configuration. IronPDF also requires native dependencies on Linux; neither is zero-effort, but the dependency surface differs.
API verbosity. Aspose.PDF's document construction API is explicit and detailed. That's a feature if you need fine-grained control, a friction point if you're mostly converting HTML to PDF.
License model changes. Both vendors have updated licensing in recent years. If your renewal timing is off, it creates a forcing function.
Namespace sprawl. Aspose.PDF has many sub-namespaces. Teams with large codebases find using statements accumulate quickly.
async/await surface. Async PDF generation in Aspose requires some care around how operations are structured. IronPDF exposes first-class RenderHtmlAsPdfAsync methods for non-blocking conversion.
NuGet package size. Aspose.PDF is a large package. In size-constrained environments (Lambda, small containers) this matters.
Team familiarity. A new hire familiar with Chromium-based rendering tools has a shorter ramp on IronPDF's mental model.
PDF/A and compliance workflows. Both support PDF/A; the specific versions and validation behavior differ. Test against your target compliance profile.
Support response patterns. Teams with strict SLA requirements on library support evaluate vendor responsiveness differently.

Comparison Table

Aspect	Aspose.PDF	IronPDF
Focus	Parse, render, edit, forms, reporting	HTML-to-PDF, edit, merge, security
Pricing	Per-developer or site license	Per-developer or royalty-free
API Style	Explicit document object model	High-level renderer + document model
Learning Curve	Steep for HTML; gradual for doc construction	Gradual for HTML; steeper for low-level ops
HTML Rendering	Proprietary renderer	Chromium-based
Page Indexing	1-based	0-based
Thread Safety	Per-document instance	Renderer is reusable
Namespace	`Aspose.Pdf`	`IronPdf`

Migration Complexity Assessment

Effort by Feature

Feature	Effort	Notes
HTML string to PDF	Low	Direct API swap; test CSS output
HTML file to PDF	Low	Path handling differs slightly
Merge PDFs	Low	Both have single-call merge
Split PDFs	Medium	Page selection API differs
Watermark (text)	Medium	Stamping model differs
Watermark (image)	Medium	Coordinate systems differ. Re-check positioning
Password protection	Low	Both support owner/user passwords
Form field manipulation	High	Aspose forms API is richer; common cases map cleanly
PDF/A compliance	Medium-High	Test output against your validator
Digital signatures	High	Both expose signing APIs; signature placement differs
Text extraction	Medium	Both support; output formatting may differ

Decision Matrix

Business Scenario	Recommendation
Primarily HTML-to-PDF, modern CSS, containerized	IronPDF likely reduces CSS workarounds
Heavy programmatic doc construction (tables, graphs)	Evaluate both; Aspose's doc model is mature
Strict PDF/A-2b or PDF/A-3 compliance required	Test both against your validator before committing
Mixed team, some devs unfamiliar with PDF APIs	IronPDF's surface is smaller to learn for common tasks

Before You Start

Prerequisites:

.NET Framework 4.6.2+, .NET Core 3.1+, or .NET 5/6/7/8/9 (IronPDF supports these)
NuGet access or offline package feed
An IronPDF license key (trial available; see license setup docs)
A test suite or manual test cases covering your current PDF outputs

Find all Aspose.PDF references in your codebase:

# Find all using statements
rg "using Aspose" --type cs -l

# Find all Aspose type references
rg "Aspose\.Pdf" --type cs

# Find all Document instantiations (Aspose pattern)
rg "new Document\(" --type cs

# Find license-setting calls
rg "Aspose.*License" --type cs

Remove Aspose, install IronPDF:

# Remove Aspose.PDF
dotnet remove package Aspose.PDF

# Install IronPDF
dotnet add package IronPdf

# Restore
dotnet restore

PowerShell (Package Manager Console): Uninstall-Package Aspose.PDF then Install-Package IronPdf.

Quick Start Migration (3 Steps)

Step 1: License Configuration

Before (Aspose):

using Aspose.Pdf;

// Aspose license is set via a file or stream
var license = new License();
license.SetLicense("Aspose.PDF.lic"); // path to your license file

After (IronPDF):

using IronPdf;

// Set license key before any IronPDF calls
// See: https://ironpdf.com/how-to/license-keys/
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

Step 2: Namespace Imports

Before:

using Aspose.Pdf;
using Aspose.Pdf.Text;
using Aspose.Pdf.Facades;

After:

using IronPdf;

Most common operations live in the root IronPdf namespace.

Step 3: Basic HTML-to-PDF Conversion

Before (Aspose):

using Aspose.Pdf;

// Aspose HTML load options control rendering behavior
var options = new HtmlLoadOptions();
using var doc = new Document("<html><body><h1>Hello</h1></body></html>", options);
doc.Save("output.pdf");

After (IronPDF):

using IronPdf;

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

See the HTML string to PDF docs for rendering options.

API Mapping Tables

Namespace Mapping

Aspose.PDF	IronPDF	Notes
`Aspose.Pdf`	`IronPdf`	Core namespace
`Aspose.Pdf.Text`	`IronPdf`	Text ops on same PdfDocument
`Aspose.Pdf.Facades`	`IronPdf`	Facades pattern not used in IronPDF

Core Class Mapping

Aspose.PDF Class	IronPDF Class	Description
`Document`	`PdfDocument`	Represents a loaded/generated PDF
`HtmlLoadOptions`	`ChromePdfRenderOptions`	Controls HTML rendering behavior
`Page`	`PdfPage`	Single page reference
`License`	`IronPdf.License`	Static license configuration

Document Loading Methods

Operation	Aspose.PDF	IronPDF
Load from file	`new Document("file.pdf")`	`PdfDocument.FromFile("file.pdf")`
Load from stream	`new Document(stream)`	`PdfDocument.FromStream(stream)`
HTML string	`new Document(html, new HtmlLoadOptions())`	`renderer.RenderHtmlAsPdf(html)`
HTML file	`new Document(htmlPath, new HtmlLoadOptions())`	`renderer.RenderHtmlFileAsPdf(path)`

Page Operations

Operation	Aspose.PDF	IronPDF
Page count	`doc.Pages.Count`	`pdf.PageCount`
Get page	`doc.Pages[1]` (1-based)	`pdf.Pages[0]` (0-based)
Delete page	`doc.Pages.Delete(1)`	`pdf.RemovePages(0)`
Rotate page	`page.Rotate = Rotation.on90`	See IronPDF rendering options docs

Merge/Split Operations

Operation	Aspose.PDF	IronPDF
Merge PDFs	`Document.Concatenate(file1, file2, output)`	`PdfDocument.Merge(pdf1, pdf2)`
Extract pages	Page copy via loop	`pdf.CopyPages(start, end)`

Four Complete Before/After Migrations

1. HTML to PDF

Before (Aspose.PDF):

using System;
using Aspose.Pdf;

class Program
{
    static void Main()
    {
        // Set license before any Aspose call
        var license = new License();
        license.SetLicense("Aspose.PDF.lic");

        // Aspose uses HtmlLoadOptions to control rendering
        var options = new HtmlLoadOptions
        {
            // BasePath needed if HTML references external assets
            BasePath = "https://example.com/"
        };

        string html = @"<html>
            <body style='font-family:Arial'>
                <h1 style='color:#2563EB'>Invoice #1042</h1>
                <p>Due: 2025-12-01</p>
            </body>
        </html>";

        // Aspose loads HTML as if it were a file via stream
        byte[] bytes = System.Text.Encoding.UTF8.GetBytes(html);
        using var stream = new System.IO.MemoryStream(bytes);
        using var doc = new Document(stream, options);
        doc.Save("invoice.pdf");

        Console.WriteLine("Saved invoice.pdf");
    }
}

After (IronPDF):

using System;
using IronPdf;

class Program
{
    static void Main()
    {
        // License setup — https://ironpdf.com/how-to/license-keys/
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        var renderer = new ChromePdfRenderer();

        // Chromium renders HTML — CSS, Flexbox, custom fonts work as in browser
        string html = @"<html>
            <body style='font-family:Arial'>
                <h1 style='color:#2563EB'>Invoice #1042</h1>
                <p>Due: 2025-12-01</p>
            </body>
        </html>";

        using var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("invoice.pdf");
        Console.WriteLine("Saved invoice.pdf");
    }
}

2. Merge PDFs

Before (Aspose.PDF):

using System;
using Aspose.Pdf;
using Aspose.Pdf.Facades;

class Program
{
    static void Main()
    {
        var license = new License();
        license.SetLicense("Aspose.PDF.lic");

        // PdfFileEditor is used for merge operations in Aspose.Pdf.Facades
        var editor = new PdfFileEditor();

        string[] inputFiles = { "part1.pdf", "part2.pdf", "part3.pdf" };
        string outputFile = "merged.pdf";

        // Concatenate writes directly to disk
        bool success = editor.Concatenate(inputFiles, outputFile);

        if (!success)
            Console.WriteLine("Merge failed. Check Aspose logs.");
        else
            Console.WriteLine("Merged to merged.pdf");
    }
}

After (IronPDF):

using System;
using IronPdf;

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

        // Load each PDF — https://ironpdf.com/how-to/merge-or-split-pdfs/
        var pdf1 = PdfDocument.FromFile("part1.pdf");
        var pdf2 = PdfDocument.FromFile("part2.pdf");
        var pdf3 = PdfDocument.FromFile("part3.pdf");

        // Static merge returns a new PdfDocument
        using var merged = PdfDocument.Merge(pdf1, pdf2, pdf3);
        merged.SaveAs("merged.pdf");
        Console.WriteLine("Merged to merged.pdf");
    }
}

3. Watermark

Before (Aspose.PDF):

using System;
using Aspose.Pdf;
using Aspose.Pdf.Text;

class Program
{
    static void Main()
    {
        var license = new License();
        license.SetLicense("Aspose.PDF.lic");

        using var doc = new Document("input.pdf");

        // Aspose stamps each page individually via TextStamp
        var stamp = new TextStamp("CONFIDENTIAL")
        {
            Opacity = 0.4,
            RotateAngle = 45,
            HorizontalAlignment = HorizontalAlignment.Center,
            VerticalAlignment = VerticalAlignment.Center,
            TextState = new TextState
            {
                FontSize = 48,
                ForegroundColor = Color.Red
            }
        };

        // Apply to every page (Aspose pages are 1-based)
        foreach (Page page in doc.Pages)
            page.AddStamp(stamp);

        doc.Save("watermarked.pdf");
        Console.WriteLine("Watermarked output saved");
    }
}

After (IronPDF):

using System;
using IronPdf;
using IronPdf.Editing;

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

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

        // TextStamper — https://ironpdf.com/how-to/stamp-text-image/
        var stamper = new TextStamper
        {
            Text = "CONFIDENTIAL",
            FontSize = 48,
            Opacity = 40,
            Rotation = 45,
            VerticalAlignment = VerticalAlignment.Middle,
            HorizontalAlignment = HorizontalAlignment.Center
        };

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

4. Password Protection

Before (Aspose.PDF):

using System;
using Aspose.Pdf;
using Aspose.Pdf.Facades;

class Program
{
    static void Main()
    {
        var license = new License();
        license.SetLicense("Aspose.PDF.lic");

        // PdfFileSecurity handles encryption in Aspose.Pdf.Facades
        var security = new PdfFileSecurity();
        security.BindPdf("input.pdf");

        // DocumentPrivilege controls permissions
        var privilege = DocumentPrivilege.AllowAll;
        privilege.Printing = PrintingPermissions.PrintingQuality;

        // EncryptFile: userPassword, ownerPassword, privileges, keySize
        security.EncryptFile("user123", "owner456", privilege, KeySize.x128);
        security.Save("protected.pdf");
        Console.WriteLine("Encrypted to protected.pdf");
    }
}

After (IronPDF):

using System;
using IronPdf;
using IronPdf.Security;

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

        // https://ironpdf.com/how-to/pdf-permissions-passwords/
        using var pdf = PdfDocument.FromFile("input.pdf");

        pdf.SecuritySettings.UserPassword = "user123";
        pdf.SecuritySettings.OwnerPassword = "owner456";

        // Set permissions
        pdf.SecuritySettings.AllowUserPrinting = IronPdf.Security.PdfPrintSecurity.FullPrintRights;

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

Critical Migration Notes

Page Indexing

Aspose.PDF pages are 1-based. doc.Pages[1] is the first page. IronPDF pages are 0-based. pdf.Pages[0] is the first page. This is the most common off-by-one bug in migrations. Audit every page-index reference.

// Aspose (1-based)
var firstPage = doc.Pages[1];  // correct
var firstPage = doc.Pages[0];  // throws or returns null

// IronPDF (0-based)
var firstPage = pdf.Pages[0];  // correct

Exception Model

Aspose.PDF returns status codes or throws PdfException. IronPDF throws typed exceptions. Wrap your PDF calls during migration and log the exception type before wiring up production error handling.

try
{
    using var pdf = PdfDocument.FromFile("input.pdf");
}
catch (IronPdf.Exceptions.IronPdfNativeException ex)
{
    // Native renderer error
    Console.WriteLine($"Render error: {ex.Message}");
}
catch (Exception ex)
{
    Console.WriteLine($"General error: {ex.Message}");
}

Unit Conversion

Aspose.PDF uses points (1 inch = 72 points) for coordinates and dimensions by default. IronPDF's ChromePdfRenderOptions margins are expressed in millimeters. Audit any numeric coordinate or margin you carry over from Aspose code.

// IronPDF margin example — values are in millimeters
var options = new ChromePdfRenderOptions
{
    MarginTop = 25,    // 25 mm
    MarginBottom = 25
};

Performance Considerations

Renderer Reuse

The ChromePdfRenderer instance in IronPDF wraps a Chromium process. Creating one per request is expensive. Reuse it:

// Shared at class/service level — not per-request
private static readonly ChromePdfRenderer _renderer = new ChromePdfRenderer();

public PdfDocument RenderInvoice(string html)
{
    return _renderer.RenderHtmlAsPdf(html);
}

See parallel rendering examples for concurrent workloads.

Disposal Patterns

PdfDocument implements IDisposable. Always dispose or use using:

// Correct
using var pdf = PdfDocument.FromFile("input.pdf");
// pdf is disposed at end of block

// Avoid — holds native resources
var pdf = PdfDocument.FromFile("input.pdf");
// never disposed

Edge Cases to Flag

Large HTML pages with lazy-loaded images. The Chromium renderer needs JavaScript to settle. Use RenderingOptions.WaitFor.RenderDelay(ms) or related wait settings.
Fonts on Linux. If output fonts look wrong in containers, the system font set may be incomplete. Install fontconfig and common fonts in your Docker image.
Memory usage under load. Aspose's renderer and IronPDF's Chromium process have different memory profiles. Load-test before assuming parity.

Migration Checklist

Pre-Migration

[ ] Inventory all files using Aspose.Pdf namespaces (rg "using Aspose" --type cs -l)
[ ] Capture baseline PDF outputs (screenshots or hash) for visual regression
[ ] Document all Aspose.PDF version currently in use
[ ] Identify any Aspose.Pdf.Facades usage (more involved to migrate)
[ ] Check for PDF/A compliance requirements and test validator
[ ] Review license keys and environments (dev, staging, prod)
[ ] Identify async/concurrent rendering patterns in current code
[ ] Confirm Linux/container system dependencies for IronPDF

Code Migration

[ ] Replace Aspose.PDF NuGet with IronPdf
[ ] Replace License.SetLicense(file) with IronPdf.License.LicenseKey = "..."
[ ] Replace using Aspose.Pdf with using IronPdf
[ ] Replace new Document(html, new HtmlLoadOptions()) with renderer.RenderHtmlAsPdf(html)
[ ] Replace doc.Pages[n] (1-based) with pdf.Pages[n-1] (0-based)
[ ] Replace PdfFileEditor.Concatenate() with PdfDocument.Merge()
[ ] Replace TextStamp stamping loop with pdf.ApplyStamp(stamper)
[ ] Replace PdfFileSecurity.EncryptFile() with SecuritySettings properties
[ ] Replace all doc.Save(path) with pdf.SaveAs(path)
[ ] Review and update any catch (PdfException) to IronPDF exception types

Testing

[ ] Visual comparison of HTML-to-PDF output (fonts, layout, colors)
[ ] Test with complex CSS: Flexbox, Grid, @page rules
[ ] Verify watermark position on multi-page documents
[ ] Confirm merged PDFs have correct page count and order
[ ] Verify password protection opens with correct credentials
[ ] Test on target deployment OS (Windows and Linux if applicable)
[ ] Confirm no page-indexing off-by-one regressions

Post-Migration

[ ] Remove Aspose.PDF NuGet and license files from repo
[ ] Update CI/CD to install IronPDF system deps (Linux)
[ ] Update internal documentation and runbooks
[ ] Archive Aspose license files (for audit trail, not active use)

Next Steps

Migration between two actively-maintained PDF libraries is not a weekend project, but it's also not a multi-month ordeal for most codebases. The hardest parts are usually (1) complex form fields, (2) PDF/A compliance validation, and (3) visual regression testing on CSS-heavy HTML.

The checklist above won't catch every edge case in your specific codebase, but it'll surface 90% of the issues before they reach staging.

Question for the comments: If you've migrated between any two PDF libraries in .NET, not just these two, and what was the migration step that took the longest and why? Was it the API mapping, the visual regression testing, or something else entirely?

The free trial is on NuGet if you want to test before committing.

Migrating from Api2pdf to IronPDF: Less Setup, Same Output

IronSoftware — Fri, 05 Jun 2026 17:20:27 +0000

You refreshed the dashboard and the number was right there: 214,000 API calls this month. Your application generates a PDF for every order confirmation, every shipping label, and every monthly statement. Each one is an HTTP POST to v2.api2pdf.com, a wait for the response, a download of the generated file from a temporary URL, and a prayer that the 24-hour auto-delete does not fire before your async job picks it up.

Api2pdf solves a real problem: it is genuinely hard to run wkhtmltopdf or headless Chrome on a managed hosting platform. But at 214,000 calls per month, you are paying for network latency, external service availability, and temporary file management that you would not need if the PDF engine ran inside your own process.

This guide covers the migration from Api2pdf's REST API to IronPDF's in-process .NET library. This is not an API-to-API migration. It is an execution model change from SaaS to library. Eighty percent of this content helps you evaluate any in-process alternative. The remaining twenty percent is IronPDF-specific.

Why Migrate

Api2pdf removes the pain of hosting Chrome or wkhtmltopdf yourself. Here is why teams outgrow it:

Latency per render. Every PDF is an HTTP round-trip: POST HTML, wait for render, download file URL. For high-volume applications, this adds 1 to 5 seconds per PDF that an in-process library eliminates.
Temporary file URLs. Api2pdf returns a URL to the generated file, not the file itself. Your application must download the PDF before the 24-hour expiry. This introduces a race condition and a failure mode that does not exist with in-process generation.
External dependency for a core function. If Api2pdf's service goes down, your PDF generation stops. If your internet connection degrades, your PDF generation slows. For applications where PDFs are on the critical path (invoices, contracts, compliance docs), this is a risk.
Data leaves your network. Your HTML, which may contain customer names, addresses, and financial data, is sent to Api2pdf's servers for rendering. For regulated industries (healthcare, finance, legal), this data transit may require additional compliance review.
Per-call cost at scale. Api2pdf's usage-based pricing is economical for low volume. At hundreds of thousands of calls per month, a one-time library license may be cheaper.
No offline capability. If your application needs to generate PDFs in disconnected environments (on-premise deployments, air-gapped networks), a REST API is not an option.
Limited post-processing. Api2pdf handles generation and merge well, but more advanced manipulation (watermarking, page-level security settings, form filling) requires additional API calls or is not supported.
wkhtmltopdf deprecation risk. Api2pdf offers wkhtmltopdf as a rendering option. wkhtmltopdf is based on a deprecated version of WebKit and has not received updates. Chrome is the better option, but not all Api2pdf integrations use it.
File size and timeout limits. Cloud APIs have practical limits on request payload size and processing time. Very large or complex HTML documents may timeout.
Debugging opacity. When a render fails or produces unexpected output, you cannot inspect the rendering engine's state. With an in-process library, you can step through with a debugger.

Comparison Table

Aspect	Api2pdf (REST API)	IronPDF (.NET library)
Focus	Cloud PDF generation via REST	In-process PDF generation + manipulation
Pricing	Usage-based per API call	Per-developer, perpetual license
API Style	HTTP REST + client SDK	Native .NET API, no network calls
Learning Curve	Low, simple HTTP calls	Low, simple .NET API calls
HTML Rendering	Headless Chrome or wkhtmltopdf (remote)	Chrome engine (in-process)
Page Indexing	N/A (service handles internally)	0-based
Thread Safety	N/A (stateless API)	`ChromePdfRenderer` stateless, safe to share
Namespace	`Api2Pdf`	`IronPdf`

Migration Complexity Assessment

Effort by Feature

Feature	Complexity	Notes
HTML to PDF (Chrome)	Low	Direct replacement; IronPDF runs Chrome in-process
URL to PDF	Low	`RenderUrlAsPdf` replaces the Chrome URL endpoint
HTML to PDF (wkhtmltopdf)	Low	Replace with IronPDF Chrome renderer, better output quality
Merge	Low	`PdfDocument.Merge()` replaces the PdfSharp merge endpoint
Office to PDF (LibreOffice)	High / N/A	No direct IronPDF equivalent. Use LibreOffice headless locally or a separate service
Password protection	Low	IronPDF `SecuritySettings` replaces the password endpoint
Bookmarks	Medium	IronPDF exposes bookmark APIs on `PdfDocument`
Barcode generation	N/A	Not a PDF feature. Use a dedicated barcode library (e.g., IronBarcode, ZXing.NET)
File deletion (security)	N/A	Not needed. Files never leave your server
Thumbnail generation	Medium	Use `pdf.RasterizeToImageFiles(...)` or `pdf.ToBitmap()`
HTML to DOCX/XLSX	N/A	Not an IronPDF feature. Use a dedicated library

Decision Matrix

Scenario	Recommendation
High-volume HTML-to-PDF with latency concerns	Migrate. In-process rendering eliminates network overhead
Regulated industry with data residency requirements	Migrate. HTML never leaves your infrastructure
Low-volume, diverse format conversion (Office, email, images)	Stay or partial migrate. Keep Api2pdf for Office conversion, use IronPDF for HTML-to-PDF
Air-gapped or on-premise deployment	Migrate. Api2pdf requires internet

Before You Start

Checklist: Pre-Migration Readiness

[ ] Count your monthly Api2pdf API calls (check your dashboard)

[ ] Categorize calls by endpoint: Chrome HTML, Chrome URL, wkhtmltopdf, LibreOffice, merge, password

[ ] Identify any LibreOffice (Office to PDF) calls. These need a separate solution

[ ] Check if your HTML contains sensitive data sent to Api2pdf's servers

[ ] Verify your deployment supports running IronPDF (needs .NET 6+ or Framework 4.6.2+)

[ ] Obtain an IronPDF trial key from ironpdf.com/get-started/license-keys/

Find Api2pdf References

# Find all Api2pdf client usage
rg -l "Api2Pdf|api2pdf|ChromeHtmlToPdfRequest|WkhtmlHtmlToPdfRequest" --glob "*.cs"

# Count API call sites
rg -c "\.Chrome\.|\.Wkhtml\.|\.PdfSharp\.|\.LibreOffice\." --glob "*.cs"

# Find configuration (API keys)
rg "Api2Pdf|api2pdf" --glob "*.json" --glob "*.config" --glob "*.cs"

In PowerShell: Get-ChildItem -Recurse -Filter *.cs | Select-String "Api2Pdf|api2pdf".

Swap Dependencies

# Remove Api2pdf
dotnet remove package Api2Pdf

# Install IronPDF
dotnet add package IronPdf

Quick Start Migration (3 Steps)

Step 1: License Configuration

Before (Api2pdf):

// Api2pdf — API key passed to constructor
using Api2Pdf;
using System;

class Program
{
    static void Main()
    {
        // API key from portal.api2pdf.com
        var a2pClient = new Api2Pdf("your-api2pdf-api-key");

        // Every call after this hits the internet
        Console.WriteLine("Api2pdf client ready.");
    }
}

After (IronPDF):

using IronPdf;

class Program
{
    static void Main()
    {
        // License key — no internet required for rendering
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        Console.WriteLine($"IronPDF licensed: {License.IsLicensed}");
        // Everything runs locally from here
    }
}

Step 2: Namespace Imports

Before:

using Api2Pdf;

After:

using IronPdf;
using IronPdf.Editing;    // watermarks, headers, footers
using IronPdf.Rendering;  // render options

Step 3: Basic HTML-to-PDF

Before (Api2pdf, ~15 lines):

using Api2Pdf;
using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var a2pClient = new Api2Pdf("your-api-key");

        var request = new ChromeHtmlToPdfRequest
        {
            Html = "<h1>Invoice #1042</h1><p>Amount: $5,200.00</p>"
        };

        var result = await a2pClient.Chrome.HtmlToPdfAsync(request);

        if (result.Success)
        {
            // Result is a URL — you must download the file
            Console.WriteLine("PDF available at: " + result.FileUrl);

            // Download before the 24-hour expiry
            using var http = new HttpClient();
            var pdfBytes = await http.GetByteArrayAsync(result.FileUrl);
            File.WriteAllBytes("invoice.pdf", pdfBytes);
            Console.WriteLine("Downloaded and saved.");
        }
        else
        {
            Console.WriteLine("Error: " + result.Error);
        }
    }
}

After (IronPDF, 8 lines):

using IronPdf;

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

        var renderer = new ChromePdfRenderer();

        var pdf = renderer.RenderHtmlAsPdf(
            "<h1>Invoice #1042</h1><p>Amount: $5,200.00</p>");

        pdf.SaveAs("invoice.pdf");
        Console.WriteLine("Saved locally. No download needed.");
    }
}

Checklist: What You Just Eliminated

[x] HTTP round-trip to external API

[x] Temporary file URL with 24-hour expiry

[x] HttpClient.GetByteArrayAsync download step

[x] Internet connectivity requirement for rendering

[x] API key management and rotation

[x] External service availability dependency

API Mapping Tables

Namespace Mapping

Api2pdf Namespace	IronPDF Namespace	Purpose
`Api2Pdf`	`IronPdf`	Core client/renderer
`Api2Pdf.Models`	`IronPdf.Rendering`	Request options / render settings
N/A	`IronPdf.Editing`	Watermarks, headers, footers

Core Class Mapping

Api2pdf Class	IronPDF Class	Description
`Api2Pdf` (client)	`ChromePdfRenderer`	The entry point for PDF generation
`ChromeHtmlToPdfRequest`	`ChromePdfRenderOptions`	Render configuration
`Api2PdfResult`	`PdfDocument`	The generated PDF (URL vs. in-memory object)
`a2pClient.PdfSharp`	`PdfDocument` static methods	Merge and manipulation

Document Loading Methods

Operation	Api2pdf	IronPDF
HTML to PDF	`a2pClient.Chrome.HtmlToPdf(request)` → URL	`renderer.RenderHtmlAsPdf(html)` → `PdfDocument`
URL to PDF	`a2pClient.Chrome.UrlToPdf(request)` → URL	`renderer.RenderUrlAsPdf(url)` → `PdfDocument`
File to download	`result.SaveFile("path")`	`pdf.SaveAs("path")`
Merge	`a2pClient.PdfSharp.MergePdfs(...)` → URL	`PdfDocument.Merge(pdf1, pdf2)` → `PdfDocument`

Page Operations

Operation	Api2pdf	IronPDF
Get page count	N/A (not exposed via API)	`pdf.PageCount`
Access specific page	N/A	`pdf.Pages[index]` (0-based)
Add watermark	Not directly supported	`pdf.ApplyWatermark(html)`
Set password	`a2pClient.PdfSharp.SetPassword(new PdfPasswordRequest { ... })`	`pdf.SecuritySettings.UserPassword = "..."`

Merge / Split Operations

Operation	Api2pdf	IronPDF
Merge PDFs	`a2pClient.PdfSharp.MergePdfs(new PdfMergeRequest { Urls = ... })` → URL	`PdfDocument.Merge(pdf1, pdf2)`
Split / extract	Not directly supported	`pdf.CopyPages(start, end)`

Four Complete Before/After Migrations

1. HTML to PDF

Before (Api2pdf):

using Api2Pdf;
using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;

class HtmlToPdfApi2pdf
{
    static async Task Main()
    {
        var a2p = new Api2Pdf("your-api-key");

        var request = new ChromeHtmlToPdfRequest
        {
            Html = @"<html><head><style>
                body { font-family: Arial; }
                .header { background: #0d47a1; color: white; padding: 20px; }
                table { width: 100%; border-collapse: collapse; margin: 20px 0; }
                td, th { padding: 8px; border: 1px solid #ddd; }
            </style></head><body>
                <div class='header'><h1>Statement</h1></div>
                <table>
                    <tr><th>Date</th><th>Description</th><th>Amount</th></tr>
                    <tr><td>2025-01-15</td><td>Service fee</td><td>$250.00</td></tr>
                    <tr><td>2025-01-20</td><td>Subscription</td><td>$99.00</td></tr>
                </table>
            </body></html>"
        };

        var result = await a2p.Chrome.HtmlToPdfAsync(request);

        if (!result.Success)
        {
            Console.WriteLine("API error: " + result.Error);
            return;
        }

        // Must download from temporary URL
        using var http = new HttpClient();
        var bytes = await http.GetByteArrayAsync(result.FileUrl);
        File.WriteAllBytes("statement.pdf", bytes);
        Console.WriteLine("Downloaded statement.pdf");
    }
}

After (IronPDF):

using IronPdf;

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

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

        var pdf = renderer.RenderHtmlAsPdf(@"<html><head><style>
                body { font-family: Arial; }
                .header { background: #0d47a1; color: white; padding: 20px; }
                table { width: 100%; border-collapse: collapse; margin: 20px 0; }
                td, th { padding: 8px; border: 1px solid #ddd; }
            </style></head><body>
                <div class='header'><h1>Statement</h1></div>
                <table>
                    <tr><th>Date</th><th>Description</th><th>Amount</th></tr>
                    <tr><td>2025-01-15</td><td>Service fee</td><td>$250.00</td></tr>
                    <tr><td>2025-01-20</td><td>Subscription</td><td>$99.00</td></tr>
                </table>
            </body></html>");

        pdf.SaveAs("statement.pdf");
        Console.WriteLine("Saved locally. No download step.");
    }
}

No HTTP client. No temporary URL. No download race condition. See IronPDF HTML-to-PDF tutorial.

2. Merge PDFs

Before (Api2pdf):

using Api2Pdf;
using System;
using System.IO;
using System.Net.Http;
using System.Collections.Generic;
using System.Threading.Tasks;

class MergeApi2pdf
{
    static async Task Main()
    {
        var a2p = new Api2Pdf("your-api-key");

        // Api2pdf merge requires URLs to existing PDFs
        var pdfUrls = new List<string>
        {
            "https://your-server.com/files/part1.pdf",
            "https://your-server.com/files/part2.pdf"
        };

        var result = await a2p.PdfSharp.MergePdfsAsync(new PdfMergeRequest { Urls = pdfUrls });

        if (!result.Success)
        {
            Console.WriteLine("Merge error: " + result.Error);
            return;
        }

        // Download the merged result
        using var http = new HttpClient();
        var bytes = await http.GetByteArrayAsync(result.FileUrl);
        File.WriteAllBytes("merged.pdf", bytes);
        Console.WriteLine("Merged and downloaded.");
    }
}

After (IronPDF):

using IronPdf;

class MergeIronPdf
{
    static void Main()
    {
        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");
        Console.WriteLine("Merged locally.");
    }
}

Checklist: Merge Migration

[x] No need to host PDFs at public URLs for merge input

[x] No download step after merge

[x] Merge works with local files, byte arrays, or in-memory PdfDocuments

[x] No 24-hour expiry on the merged result

See IronPDF merge documentation.

3. Watermark

Before (Api2pdf, not directly supported):

// Api2pdf does not have a native watermark endpoint.
// Common workaround: generate the watermark as HTML overlay,
// or use a separate library after downloading the PDF.
// This is a gap in the Api2pdf feature set.

// You would need to:
// 1. Generate PDF via Api2pdf
// 2. Download the PDF
// 3. Use a local library (PdfSharp, iText, etc.) to add watermark
// 4. Save the result

Console.WriteLine("Watermarking requires a second tool with Api2pdf.");

After (IronPDF):

using IronPdf;

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

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

        pdf.ApplyWatermark(
            "<h1 style='color:rgba(0,0,0,0.15);font-size:60px;'>DRAFT</h1>",
            rotation: 45
        );

        pdf.SaveAs("watermarked.pdf");
        Console.WriteLine("Watermarked locally.");
    }
}

IronPDF handles watermarking natively. No second library needed.

4. Password Protection

Before (Api2pdf):

using Api2Pdf;
using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;

class PasswordApi2pdf
{
    static async Task Main()
    {
        var a2p = new Api2Pdf("your-api-key");

        // Api2pdf password endpoint requires a URL to an existing PDF
        var result = await a2p.PdfSharp.SetPasswordAsync(new PdfPasswordRequest
        {
            Url = "https://your-server.com/files/input.pdf",
            UserPassword = "user456",
            OwnerPassword = "owner123"
        });

        if (!result.Success)
        {
            Console.WriteLine("Password error: " + result.Error);
            return;
        }

        using var http = new HttpClient();
        var bytes = await http.GetByteArrayAsync(result.FileUrl);
        File.WriteAllBytes("protected.pdf", bytes);
        Console.WriteLine("Password-protected and downloaded.");
    }
}

After (IronPDF):

using IronPdf;

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

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

        pdf.SecuritySettings.OwnerPassword = "owner123";
        pdf.SecuritySettings.UserPassword = "user456";
        pdf.SecuritySettings.AllowUserPrinting = IronPdf.Security.PdfPrintSecurity.NoPrint;
        pdf.SecuritySettings.AllowUserCopyPasteContent = false;

        pdf.SaveAs("protected.pdf");
        Console.WriteLine("Protected locally.");
    }
}

IronPDF gives you specific permission settings, not just a single password. Your PDF file never leaves your server. See IronPDF security documentation.

Critical Migration Notes

The Execution Model Change: SaaS to Library

This is not a typical API-to-API migration. You are changing the execution model:

Concern	Api2pdf (SaaS)	IronPDF (Library)
Where rendering happens	Api2pdf's AWS/GCP servers	Your server / container
Data transit	HTML sent over internet	HTML stays in-process
Availability	Depends on Api2pdf uptime	Depends on your uptime
Latency	Network round-trip + render time	Render time only
File lifecycle	24-hour temp URL	Your filesystem / memory

Async Patterns

Api2pdf calls are inherently async (HTTP). IronPDF rendering is synchronous by default but offers async variants:

// IronPDF async rendering
var pdf = await renderer.RenderHtmlAsPdfAsync(html);

Error Handling Shift

Api2pdf returns result.Success / result.Error on every call. IronPDF throws exceptions. Update your error handling:

// Api2pdf pattern
if (!result.Success) { log(result.Error); return; }

// IronPDF pattern
try { var pdf = renderer.RenderHtmlAsPdf(html); }
catch (Exception ex) { log(ex.Message); return; }

File Management

With Api2pdf, you downloaded PDFs from temporary URLs. With IronPDF, you have PdfDocument objects in memory. You choose when and where to persist them. Remove any download-and-cleanup logic from your codebase.

Performance Considerations

Latency Reduction

The most significant performance gain is eliminating the network round-trip. A rough benchmark:

Api2pdf: ~1,500–4,000ms per render (network + remote render + download)
IronPDF in-process: ~200–1,000ms per render (render only, depends on HTML complexity)

These are illustrative ranges, not benchmarks. Your actual numbers depend on network conditions, HTML complexity, and server resources.

Renderer Reuse

private static readonly ChromePdfRenderer _renderer = new ChromePdfRenderer();

Disposal

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

Edge Cases Worth Flagging

LibreOffice replacement: If you use Api2pdf's LibreOffice endpoint for Office-to-PDF conversion, IronPDF does not replace this. Run LibreOffice headless locally (libreoffice --headless --convert-to pdf input.docx) or use a dedicated service. Alternatively, the IronWord library from Iron Software handles DOCX-to-PDF within .NET.
wkhtmltopdf rendering differences: If your existing Api2pdf integration uses wkhtmltopdf (not Chrome), switching to IronPDF's Chrome engine may produce different output for the same HTML. Test your templates and adjust CSS if needed. Chrome's rendering is more modern and accurate.
Barcode generation: Api2pdf offers barcode/QR code generation. IronPDF does not. Use a dedicated library like ZXing.NET or IronBarcode, and embed the generated barcode image in your HTML before rendering.

Migration Checklist

Pre-Migration (8 items)

[ ] Export your Api2pdf usage data: call count, endpoints used, average render time
[ ] Categorize calls: Chrome HTML, Chrome URL, wkhtmltopdf, LibreOffice, merge, password
[ ] Identify LibreOffice calls that need a separate replacement
[ ] Check for wkhtmltopdf-specific HTML that may render differently in Chrome
[ ] Verify your deployment environment supports IronPDF (.NET 6+ or Framework 4.6.2+)
[ ] Obtain an IronPDF trial key from ironpdf.com/get-started/license-keys/
[ ] Create migration branch
[ ] Audit your HTML templates for sensitive data currently sent to Api2pdf servers

Code Migration (10 items)

[ ] Remove Api2Pdf NuGet package
[ ] Add IronPdf NuGet package
[ ] Replace new Api2Pdf("key") with IronPdf.License.LicenseKey = "..."
[ ] Replace a2pClient.Chrome.HtmlToPdf() with renderer.RenderHtmlAsPdf()
[ ] Replace a2pClient.Chrome.UrlToPdf() with renderer.RenderUrlAsPdf()
[ ] Replace a2pClient.PdfSharp.MergePdfs() with PdfDocument.Merge()
[ ] Replace a2pClient.PdfSharp.SetPassword() with SecuritySettings properties
[ ] Remove all HttpClient.GetByteArrayAsync(result.FileUrl) download code
[ ] Remove any temporary-file cleanup logic tied to the 24-hour URL lifecycle
[ ] Replace result.Success checks with try/catch exception handling

Testing (7 items)

[ ] Compare PDF output visually for your top 10 templates (Chrome engine may differ slightly from Api2pdf's Chrome version)
[ ] Test any wkhtmltopdf-specific HTML in IronPDF's Chrome engine. Adjust CSS as needed
[ ] Verify password-protected PDFs open correctly in Adobe Reader
[ ] Test merge with 3+ documents
[ ] Benchmark render time: in-process vs. Api2pdf round-trip
[ ] Test in your production deployment environment (Docker, Azure, etc.)
[ ] Verify no sensitive data is being sent externally after migration

Post-Migration (4 items)

[ ] Cancel or downgrade your Api2pdf subscription
[ ] Remove Api2pdf API key from secrets/configuration management
[ ] Remove download-and-cleanup background jobs
[ ] Monitor production render times and error rates for two weeks

Before You Ship

Worth knowing even without IronPDF: if you are evaluating in-process alternatives and want to stay open-source, Puppeteer Sharp is a .NET port of Puppeteer that drives headless Chrome locally. It requires managing a Chrome installation but produces the same quality output as Api2pdf's Chrome endpoint. Playwright for .NET is another option with broader browser support.

Here is my question: if you are currently running Api2pdf at high volume, what is your download-and-cleanup strategy? Do you download synchronously in the request, run a background job, or use webhooks? I am curious how teams handle the temporary URL lifecycle in production. It is the part of the Api2pdf model that introduces the most operational complexity.

The free trial is on NuGet if you want to test before committing.

mistune vs Markdig: Rendering 10,000 Markdown Documents

Milliseconds.dev — Fri, 05 Jun 2026 14:30:03 +0000

Overview

Markdown rendering shows up in documentation systems, static site generators, API responses for rich text, and content management pipelines. mistune is consistently benchmarked as Python's fastest Markdown parser — it uses a regex-based scanner with minimal Python object overhead. Markdig is .NET's most popular Markdown library, built on a character-scanner architecture with extension points for CommonMark compliance.

Both produce equivalent HTML for standard Markdown input. The benchmark isolates pure rendering throughput: no I/O, no template engine, just Markdown string in → HTML string out.

Benchmark Setup

10,000 documents from a Wikipedia plain-text dump, converted to Markdown format:

Mix of headings, paragraphs, bold/italic, inline code, fenced code blocks, lists, and links
Average document: ~2,500 characters
Total input: ~25 MB of Markdown text

Tested at 1,000 / 5,000 / 10,000 documents.

Results

Documents	Python (mistune)	.NET (Markdig)	Speedup
1,000	~0.9 s	~130 ms	6.9×
5,000	~4.4 s	~480 ms	9.2×
10,000	~8.8 s	~800 ms	11×

Why Markdig Is Faster

Pipeline reuse. Markdig requires building a MarkdownPipeline once — it's thread-safe and reused across all documents. mistune's create_markdown() is designed to be called once per style, but the underlying renderer still allocates Python objects per document during parsing.

Character-at-a-time scanning in native code. Markdig's block parser and inline parser each process characters through a JIT-compiled state machine. Python's regex engine (even the fast PCRE-style one in mistune) adds interpreter overhead per match object created.

No intermediate AST allocation. Markdig's pipeline streams tokens directly from the scanner into the HTML writer without building a full AST in memory. mistune builds a list of (type, content) tuples as an intermediate representation.

Key Code

// Pipeline built once, reused for all 10,000 documents
// Python equivalent: md = mistune.create_markdown()
private readonly MarkdownPipeline _pipeline =
    new MarkdownPipelineBuilder().Build();

public string Render(string markdown) =>
    Markdown.ToHtml(markdown, _pipeline);

# mistune — create once, call per document
md = mistune.create_markdown()
for doc in documents:
    html = md(doc)

The interface is nearly identical. The difference is what happens inside: Markdown.ToHtml dispatches to JIT-compiled C# scanning code, while md(doc) dispatches through Python's regex engine and object system.

Diagrams

mistune's time grows linearly with document count. Markdig's growth is also linear but with a slope roughly 11× smaller. At 10,000 documents: 8.8 seconds vs 800 milliseconds.

Throughput matters for pipeline systems: a documentation site generating 100,000 pages at build time takes 88 seconds with mistune, 8 seconds with Markdig.

JWT Authentication in ASP.NET Core: Common Mistakes (And How to Avoid Them)

alinabi19 — Fri, 05 Jun 2026 14:05:11 +0000

If you've worked on ASP.NET Core APIs long enough, you've probably experienced this situation.

Everything works perfectly on your machine.

Users log in successfully. JWT tokens are generated. Protected endpoints return data exactly as expected.

Then you deploy to production.

Suddenly:

Users start receiving 401 Unauthorized
Tokens work in Postman but fail from the frontend
Authentication randomly breaks after deployment
Security reviewers flag vulnerabilities in your implementation
Users get logged out unexpectedly because tokens expire

And now you're staring at authentication configuration wondering what went wrong.

I've seen this happen more times than I'd like to admit.

The tricky thing about JWT authentication is that it's deceptively simple. Most tutorials show how to make it work, but very few explain how to make it secure and production-ready.

Developers often copy authentication code from blog posts, Stack Overflow answers, or older projects without fully understanding the implications.

Unfortunately, small mistakes in authentication systems can create major security risks.

In this article, we'll walk through the most common JWT authentication mistakes in ASP.NET Core, why they happen, and how to avoid them when building secure APIs.

What is JWT Authentication in ASP.NET Core?

JWT stands for JSON Web Token.

It's a compact token format commonly used for securing APIs.

The basic flow looks like this:

User Login
    ↓
Generate JWT
    ↓
Client Stores Token
    ↓
Client Sends Token
    ↓
API Validates Token
    ↓
Access Protected Resources

Unlike traditional session-based authentication, the server doesn't need to store session state.

The token itself contains claims that identify the user.

A typical JWT contains:

Header
Payload (claims)
Signature

The signature allows the API to verify the token hasn't been tampered with.

It's also important to understand the difference between authentication and authorization.

Authentication

Who are you?

Authorization

What are you allowed to do?

Authentication identifies the user.

Authorization determines what that user can access.

Why JWT Authentication Goes Wrong So Often

JWT authentication seems straightforward at first.

You install a package.

Copy some configuration.

Generate a token.

Done.

Except not really.

The problems usually appear later.

Common reasons include:

Tutorials skipping security details
Different behavior between development and production
Misconfigured validation settings
Missing HTTPS enforcement
Incorrect middleware ordering

Authentication failures are also notoriously difficult to debug because the framework intentionally hides many security details.

You often get nothing more than:

401 Unauthorized

Which isn't exactly helpful.

Common Mistake #1: Using Weak or Hardcoded Secret Keys

This is one of the most common security issues.

Bad example:

var key = "MySecretKey123";

Problems:

Predictable
Too short
Hardcoded in source control

If an attacker obtains your signing key, they can generate valid JWT tokens for any user.

Better Approach

Store secrets securely.

Example:

{
  "Jwt": {
    "Key": "StoredSecurelyOutsideSourceControl"
  }
}

Retrieve from configuration:

var secretKey = builder.Configuration["Jwt:Key"];

For production systems use:

Environment Variables
Azure Key Vault
AWS Secrets Manager
HashiCorp Vault

Use a strong cryptographically secure key.

A minimum of 256 bits is a good starting point.

Common Mistake #2: Not Validating Token Lifetime Properly

JWTs should expire.

Unfortunately, some APIs effectively allow tokens to live forever.

Bad configuration:

ValidateLifetime = false

This means expired tokens remain valid.

That's a serious security problem.

Correct Configuration

ValidateLifetime = true

Example:

TokenValidationParameters = new TokenValidationParameters
{
    ValidateLifetime = true,
    ClockSkew = TimeSpan.FromMinutes(2)
};

Why Clock Skew Matters

Servers and clients rarely have perfectly synchronized clocks.

A small clock skew prevents legitimate users from being rejected because of a few seconds difference.

Avoid large values.

Five minutes used to be common.

Today, one to two minutes is typically enough.

Common Mistake #3: Disabling Important Validation Checks

I've seen this during debugging:

ValidateIssuer = false;
ValidateAudience = false;
ValidateLifetime = false;

Developers disable checks to make things work.

Then forget to re-enable them.

Recommended Validation Settings

TokenValidationParameters = new TokenValidationParameters
{
    ValidateIssuer = true,
    ValidateAudience = true,
    ValidateLifetime = true,
    ValidateIssuerSigningKey = true,

    ValidIssuer = configuration["Jwt:Issuer"],
    ValidAudience = configuration["Jwt:Audience"]
};

These checks exist for a reason.

Disabling them reduces security significantly.

Common Mistake #4: Storing Sensitive Data Inside JWT Tokens

Many developers misunderstand JWTs.

JWT payloads are:

Encoded
Not:

Encrypted

Anyone holding the token can decode it.

For example, this data is a bad idea:

{
  "password": "MyPassword123",
  "creditCard": "4111111111111111"
}

Never store:

Passwords
Financial information
Personal identifiers
Sensitive business data

What Should Go Into Claims?

Keep claims minimal.

Good examples:

{
  "sub": "123",
  "email": "user@example.com",
  "role": "Admin"
}

Only include information required for authorization decisions.

Common Mistake #5: Incorrect Middleware Order

This one causes countless authentication failures.

Wrong:

app.UseAuthorization();
app.UseAuthentication();

Authorization runs before authentication.

The user identity doesn't exist yet.

Correct Order

app.UseAuthentication();
app.UseAuthorization();

Authentication establishes the user.

Authorization evaluates permissions.

Think of it as:

Identify User
    ↓
Check Permissions

Not the other way around.

Common Mistake #6: Forgetting HTTPS in Production

JWTs should never travel over plain HTTP.

Without HTTPS:

Tokens can be intercepted
Sessions can be hijacked
User accounts can be compromised

Always enforce HTTPS.

Example:

app.UseHttpsRedirection();

For reverse proxy deployments:

Nginx
IIS
Azure App Service

Ensure TLS termination is configured correctly.

Common Mistake #7: Using Extremely Long Token Expiration Times

Sometimes developers create tokens that remain valid for weeks or months.

Example:

expires: DateTime.UtcNow.AddDays(365)

That's dangerous.

If a token is stolen, the attacker now has access for an entire year.

Better Strategy

Use:

Short-lived access tokens
Refresh tokens

Typical approach:

Token Type	Lifetime
Access Token	15-60 Minutes
Refresh Token	Several Days

This reduces the impact of stolen access tokens.

Common Mistake #8: Poor Error Handling and Debugging

JWT failures are often difficult to diagnose.

Fortunately, JwtBearer provides useful events.

Example:

.AddJwtBearer(options =>
{
    options.Events = new JwtBearerEvents
    {
        OnAuthenticationFailed = context =>
        {
            Console.WriteLine(context.Exception.Message);

            return Task.CompletedTask;
        }
    };
});

This can save hours of debugging.

Common Things to Check

When debugging 401 responses:

Expired token?
Wrong issuer?
Wrong audience?
Invalid signing key?
Missing Bearer prefix?

These account for most authentication failures.

Common Mistake #9: Mixing Authentication and Authorization Logic

Many APIs blur the line between authentication and authorization.

Remember:

Authentication:

Who are you?

Authorization:

What can you do?

Role-Based Example

[Authorize(Roles = "Admin")]
public IActionResult GetUsers()
{
    return Ok();
}

Policy-Based Example

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("ManagersOnly",
        policy => policy.RequireRole("Manager"));
});

This keeps security rules organized and maintainable.

Common Mistake #10: Not Testing Authentication Properly

Authentication bugs often appear only after deployment.

Common surprises:

Reverse proxy issues
CORS interactions
HTTPS configuration differences
Expired tokens

Test authentication early.

Recommended Testing Approaches

Postman

Verify:

Login
Token generation
Protected endpoints

Swagger

Test authorization flow directly inside your API.

Integration Tests

Automate authentication testing.

Frontend Testing

Always test from the actual client application.

A token working in Postman doesn't guarantee it will work in the browser.

Production-Ready JWT Configuration Example

Here's a solid baseline configuration for .NET 8 APIs.

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters =
            new TokenValidationParameters
            {
                ValidateIssuer = true,
                ValidateAudience = true,
                ValidateLifetime = true,
                ValidateIssuerSigningKey = true,

                ValidIssuer = builder.Configuration["Jwt:Issuer"],
                ValidAudience = builder.Configuration["Jwt:Audience"],

                IssuerSigningKey =
                    new SymmetricSecurityKey(
                        Encoding.UTF8.GetBytes(
                            builder.Configuration["Jwt:Key"]!)),

                ClockSkew = TimeSpan.FromMinutes(2)
            };
    });

builder.Services.AddAuthorization();

This configuration enables:

Issuer validation
Audience validation
Token expiration validation
Signing key validation All critical for secure ASP.NET Core JWT Authentication.

JWT Authentication Security Checklist

Before deploying your API, verify the following:

Use strong signing keys
Store secrets securely
Enable HTTPS
Validate issuer
Validate audience
Validate token lifetime
Validate signing key
Use short-lived access tokens
Implement refresh tokens
Avoid sensitive claims
Log authentication failures
Test authentication in production-like environments

If you can check every item on this list, you're already ahead of many production systems.

Quick Summary

Mistake	Risk	Solution
Weak Secret Key	Token Forgery	Use Strong Secure Keys
Disabled Validation	Security Vulnerabilities	Enable Validation Checks
Long Expiration	Stolen Token Abuse	Use Short-Lived Tokens
Sensitive Claims	Data Exposure	Store Minimal Information
Wrong Middleware Order	Authentication Failure	Authenticate Before Authorize
No HTTPS	Token Interception	Enforce TLS
Poor Logging	Difficult Troubleshooting	Log Authentication Events
No Refresh Tokens	Poor Security Balance	Use Token Rotation
Mixed Auth Logic	Maintainability Issues	Separate AuthN and AuthZ
Insufficient Testing	Production Failures	Test Early and Often

Final Thoughts

JWT authentication is one of the most common approaches for securing modern APIs, but it's also one of the most frequently misconfigured.

Most authentication problems don't come from complex security vulnerabilities.

They come from small mistakes:

weak keys
disabled validation
incorrect middleware order
overly long token lifetimes
poor production configuration

The good news is that these issues are preventable once you understand how JWT token validation actually works.

When building secure ASP.NET Core APIs, focus on security first and convenience second.

Authentication is not an area where shortcuts age well.

AI-Assisted TDD vs. Pure TDD: I Picked the Iterative Dance

itysu tur — Fri, 05 Jun 2026 11:34:16 +0000

AI-Assisted TDD vs. Pure TDD: I Picked the Iterative Dance

How do you maintain a true test-first discipline when an AI assistant is constantly itching to write the implementation before you've even finished the test? That question gnawed at me for months.

I've been a TDD advocate for years, but the rise of AI coding assistants like GitHub Copilot and Claude Sonnet 4.6 threw a wrench in my process. My usual rhythm of red-green-refactor felt constantly disrupted. I needed a way to leverage the AI without losing the benefits of TDD, especially on a new .NET 9 project I was kicking off. I wanted a true ai tdd dotnet workflow, not just AI generating code around my tests.

My Initial Missteps and the 'Premature Implementation' Trap

Honestly, my first attempts at integrating AI into my TDD cycle were a mess. I'd typically prompt something like, "Write a C# 13 method to reverse a string, then write a unit test for it." And almost every time, the AI—whether it was Copilot's inline suggestion or a full response from Claude Opus 4.7 in Cursor 0.42—would spit out the implementation first, then a test that simply confirmed its own code. It wasn't TDD; it was "implementation-driven development with a side of AI-generated validation."

This felt like cheating, or at best, missing the point. The value of TDD, for me, lies in defining behavior before coding, letting the tests guide the design. When the AI gives you the answer upfront, that crucial design step is skipped. I might be wrong about this, but for me, the magic of TDD is in the constraint, the thinking it forces. The AI's eagerness to complete the thought was a constant hurdle.

Here’s a simplified version of what I kept getting, and what I was actively trying to avoid:

// My initial prompt (mental or explicit): "I need a method to safely parse an int from a string."
// AI's eager response, often before I've even thought of edge cases:
public static class StringParser
{
    public static int ParseIntOrDefault(string input, int defaultValue = 0)
    {
        if (int.TryParse(input, out int result))
        {
            return result;
        }
        return defaultValue;
    }
}

// And then, a test for it, which is useful but didn't guide the *design*:
[TestFixture]
public class StringParserTests
{
    [Test]
    public void ParseIntOrDefault_ValidInput_ReturnsParsedValue()
    {
        Assert.That(StringParser.ParseIntOrDefault("123"), Is.EqualTo(123));
    }

    [Test]
    public void ParseIntOrDefault_InvalidInput_ReturnsDefault()
    {
        Assert.That(StringParser.ParseIntOrDefault("abc"), Is.EqualTo(0));
    }
}

The implementation was often fine, but it bypassed my brain's TDD muscle memory. I was constantly running into this "premature implementation" trap.

The Rhythm I Found: Test-First Prompts

It took me an embarrassing amount of time to figure out: I needed to treat the AI like a highly capable, but literal, junior developer who needed very specific instructions. The key was to constrain the AI to only generate the test, and then, once I'd seen it fail, to ask for the implementation. This became my core tdd ai pair strategy.

What I ended up with was a two-stage prompting approach, primarily using Cursor 0.42's chat for the initial test generation and then Visual Studio 2026 with Copilot for quick completions on the implementation.

First, I'd prompt for the test, often specifying C# 13 and .NET 9 context:

"I'm working in C# 13 with .NET 9. I need a unit test for a new static method `GuidUtils.IsValidGuid(string s)`.
It should handle null, empty, invalid format strings, and a valid GUID. Focus ONLY on the test, no implementation."

Claude Sonnet 4.6 would then give me something wonderfully focused like this, which I'd drop into my test project:

using NUnit.Framework;
using System;

[TestFixture]
public class GuidUtilsTests
{
    [Test]
    public void IsValidGuid_NullString_ReturnsFalse()
    {
        Assert.That(GuidUtils.IsValidGuid(null), Is.False);
    }

    [Test]
    public void IsValidGuid_EmptyString_ReturnsFalse()
    {
        Assert.That(GuidUtils.IsValidGuid(""), Is.False);
    }

    [Test]
    public void IsValidGuid_InvalidFormat_ReturnsFalse()
    {
        Assert.That(GuidUtils.IsValidGuid("not-a-guid"), Is.False);
    }

    [Test]
    public void IsValidGuid_ValidGuid_ReturnsTrue()
    {
        Assert.That(GuidUtils.IsValidGuid(Guid.NewGuid().ToString()), Is.True);
    }
}

I'd run the tests, watch them all fail (red!), and then I'd prompt the AI for the implementation, often feeding it the failing test code as context, or just referencing the method signature:

"Implement the `GuidUtils.IsValidGuid` method in C# 13 to make the above tests pass. Keep it efficient."

And then, the AI would provide the minimal code to get to green:

using System;

public static class GuidUtils
{
    public static bool IsValidGuid(string s)
    {
        return Guid.TryParse(s, out _);
    }
}

This felt like genuine test driven ai. I was still driving the behavior definition, and the AI was an incredible accelerator for getting to the green state.

Where I'm Still Tweaking: Refactoring and Edge Cases

So, where am I now? I'm firmly in the camp of ai tdd pair as a viable, productive workflow. My test suites are growing faster, and I'm catching more edge cases upfront because the AI is so good at suggesting test scenarios. It’s particularly strong for utility methods and well-defined algorithms.

However, the journey isn't over. Refactoring, for instance, is still a tricky area. While I can prompt the AI to "refactor this C# method to improve readability," it often suggests a full rewrite based on patterns rather than an incremental, behavior-preserving refactor that I'd typically do with TDD. I find myself doing more of the refactoring manually, using the AI more for brainstorming ideas for refactorings rather than the actual code changes. Also, for complex domain logic with subtle business rules, I still often write the first few tests myself to truly embed my understanding. Your mileage may vary, but for me, the test generation part remains the biggest win.

The biggest remaining challenge for me is leveraging AI for complex domain modeling during the design phase, before any code or tests are written.

If you've tried to pair TDD with AI in a .NET context, especially for refactoring existing codebases, I'd love to hear what broke or what surprising workflows you discovered.

Azure Services as Aspire Resources: Service Bus, Storage, and Redis

Martin Oehlert — Fri, 05 Jun 2026 06:17:53 +0000

A [ServiceBusTrigger("orders", Connection = "messaging")] attribute doesn't hold a connection string. It holds the name "messaging", and something has to resolve that name to a real connection in every environment the function runs in. Part 1 moved one connection (host storage) out of local.settings.json and into the AppHost. The question this part answers is whether the same move holds for the connections you actually choose: a Service Bus namespace, a second storage account, a Redis cache, three services that in a traditional Functions app are three strings a developer pastes per machine and hopes match production.

The connection string problem, widened

The companion sample from Part 1 had two Functions projects sharing one host-storage emulator. That covered the connection the runtime needs for its own bookkeeping, the one injected as AzureWebJobsStorage. It didn't cover the connections your code triggers on.

Part 2 adds a third worker, OrderProcessor.ServiceBus, that consumes a Service Bus queue, dedupes against Redis, and writes a receipt blob to a storage account that isn't host storage. That one function touches three connections you name yourself:

public sealed class ConfirmOrderFunction(
    ILogger<ConfirmOrderFunction> logger,
    OrderValidator validator,
    IConnectionMultiplexer redis)
{
    [Function(nameof(ConfirmOrder))]
    [BlobOutput("receipts/{OrderId}.json", Connection = "receipts")]
    public async Task<Order?> ConfirmOrder(
        [ServiceBusTrigger("orders", Connection = "messaging")] OrderMessage message,
        CancellationToken cancellationToken)
    {
        // ...
    }
}

In a traditional setup each of those (messaging, receipts, and the Redis connection the multiplexer reads) is a string in local.settings.json, copied from the portal, kept current by hand on every machine and in every environment. Three names, three places to drift. The fix is the one from Part 1, applied three times: declare each service once in the AppHost as a resource, hand it to the Functions project by reference, and let Aspire compute the connection value per environment. What stays is the short name. "messaging" appears in the AppHost and on the trigger, and those two have to agree. The value behind the name stops being something you maintain.

The rest of this article is those three declarations and what each one resolves to.

Service Bus as an Aspire resource

The package is Aspire.Hosting.Azure.ServiceBus. Two lines in AppHost.cs declare the namespace and a queue:

var messaging = builder.AddAzureServiceBus("messaging").RunAsEmulator();
messaging.AddServiceBusQueue("orders");

AddAzureServiceBus("messaging") returns the namespace resource. Children come from AddServiceBusQueue / AddServiceBusTopic / AddServiceBusSubscription (the older AddQueue / AddTopic / AddSubscription names were obsoleted in 9.1, so a 9.x snippet from the Learn API reference won't compile against 13.x).

RunAsEmulator() is the line that earns the section. Locally it starts the Service Bus emulator as containers Aspire owns. In publish mode it's a no-op, so the same two lines provision a real namespace under azd. One declaration, two resolutions.

Two things about that emulator are worth knowing before you run it.

First, it isn't one container, it's two. The emulator needs a SQL backend, so Aspire pulls mcr.microsoft.com/azure-messaging/servicebus-emulator:2.0.0 plus mcr.microsoft.com/mssql/server:2022-latest, generates the SQL sa password, sets ACCEPT_EULA=Y on both, and injects the SQL connection into the emulator. You write one line; Aspire coordinates two containers and the secret between them. No .env file to edit.

Second, the emulator doesn't create entities at runtime. It reads a Config.json at startup and provisions exactly what's in it. Aspire generates that file from your AddServiceBusQueue("orders") declaration and mounts it, so the queue exists when the worker connects. On the live run the emulator logged Creating queue: orders then Emulator Service is Successfully Up!. If you need topics, subscriptions, or rules the emulator config supports but the fluent API doesn't reach, WithConfigurationFile and WithConfiguration are the escape hatches.

The trigger side is where Service Bus pays off the resource model, because Service Bus is one of the four integrations Aspire auto-wires into the Functions binding system. On the AppHost you hand the namespace to the worker by reference:

builder.AddAzureFunctionsProject<Projects.OrderProcessor_ServiceBus>("orders-sb")
    .WithHostStorage(hostStorage)
    .WithReference(messaging, "messaging");

The second argument to WithReference is the connection name. The trigger names the same string:

[ServiceBusTrigger("orders", Connection = "messaging")] OrderMessage message

That's the whole contract. Aspire computes the connection value (the emulator's local endpoint now, a real namespace under azd later) and injects it under messaging; the trigger resolves messaging and binds. The name matches because you typed it twice, not because anything derives it. Omit the second WithReference argument and it defaults to the resource name, which here is also messaging, so it would resolve either way; the explicit form is clearer about what the contract is. The worker needs Microsoft.Azure.Functions.Worker.Extensions.ServiceBus (5.24.0 against Worker 2.x) for the trigger attribute to exist.

Be honest with your team about the emulator's limits. Microsoft labels it dev/test only, production use is explicitly discouraged. It speaks AMQP over TCP, and it doesn't persist messages across a restart; entities re-provision from Config.json, but in-flight messages are gone. On Apple Silicon both images are amd64-only and run under Rosetta. That sounds like a caveat but it's the good kind: on the author's M-series machine the full message → trigger → blob path ran end to end with no special Docker flags beyond having Rosetta emulation available.

Storage beyond host storage

Part 1 used one storage resource for host bookkeeping. Application data shouldn't share it. The receipt this worker writes is your data, not the runtime's lease blobs and scaling state, so it gets its own resource:

var appStorage = builder.AddAzureStorage("app-storage").RunAsEmulator();
var receipts = appStorage.AddBlobs("receipts");

RunAsEmulator() here is Azurite, pulled as mcr.microsoft.com/azure-storage/azurite:3.35.0 and started and stopped with the AppHost. There's no npm install -g azurite, no second terminal running azurite --silent, no hand-written devstoreaccount1 string. The prerequisite step from every Functions README becomes a line in a project the team checks in.

One storage resource fans out to all three services. AddBlobs and AddQueues give you the blob and queue endpoints; AddTables gives you the table service. Note the plural: there's no singular AddTable in 13.x, and Aspire 9.4 moved these to top-level calls on the storage resource (AddBlobContainer, Add*ServiceClient on the client side), so older snippets miss the rename. Blob and Queue auto-wire into triggers the same way Service Bus does; Tables do not, and need the WithEnvironment form the last section covers.

The blob output binding is auto-wired by the same WithReference pattern:

builder.AddAzureFunctionsProject<Projects.OrderProcessor_ServiceBus>("orders-sb")
    .WithHostStorage(hostStorage)
    .WithReference(messaging, "messaging")
    .WithReference(receipts, "receipts")
    .WithReference(cache);

WithReference(receipts, "receipts") injects the connection the [BlobOutput(... Connection = "receipts")] attribute names. The function returns an Order, and Aspire serializes it to receipts/{OrderId}.json. The {OrderId} token in that path is worth a beat: it resolves from the Service Bus trigger's POCO, the OrderMessage that fired the function, not from any injected client. On the live run a message with OrderId w23-001 produced receipts/w23-001.json containing the serialized order. The blob binding read a value off the message that triggered it, across two different Azure services, with no glue code between them.

Ports are mapped dynamically, so never hardcode 127.0.0.1:10000; read the connection from the injected value. Azurite is in-memory by default. If you want receipts to survive a restart, WithDataVolume() or WithDataBindMount() opts into persistence.

Redis as an Aspire resource

Redis is the resource that breaks the pattern, and the break is the useful part of the section. The declaration looks like the others:

var cache = builder.AddRedis("cache");

AddRedis (from Aspire.Hosting.Redis) runs a local Redis container with health checks; at publish it deploys containerized Redis on Container Apps. For a managed cache in production the current API is AddAzureManagedRedis (Azure Managed Redis, Entra ID auth by default). Don't reach for AddAzureRedis, PublishAsAzureRedis, or .RunAsContainer() on the Azure Redis resource; all three are [Obsolete] in 13.x.

The break is that Redis is not auto-wired into the Functions trigger system. The four integrations that feed triggers and bindings are Blob, Queue, Event Hubs, and Service Bus. Redis isn't one of them, which means WithReference(cache) on its own does not make a Redis trigger resolve. What WithReference(cache) does serve is the Aspire client integration: register IConnectionMultiplexer in the worker with one line and read the cache from code triggered by something else.

That's the path this sample uses. In Program.cs:

builder.AddRedisClient("cache");

And the function takes IConnectionMultiplexer by constructor injection and uses Redis as an idempotency gate, because Service Bus delivers at-least-once and a retry can replay the same order:

var db = redis.GetDatabase();
var firstDelivery = await db.StringSetAsync(
    $"orders:seen:{message.OrderId}", "1", when: When.NotExists);
if (!firstDelivery)
{
    logger.LogWarning("Duplicate order {OrderId}, skipping receipt", message.OrderId);
    return null;
}

One detail from the live run is worth a callout, because it's the kind of thing that costs an afternoon if you hit it raw. Aspire's 13.x Redis container ships with TLS and auth on by default: it runs redis-server --requirepass <generated> --tls-port 6379 ... with Aspire-issued certs. A naive redis-cli against it gets "Connection reset by peer" because it spoke plaintext to a TLS port. AddRedisClient("cache") handles the handshake and the generated password from the injected connection string, so the worker code stays at IConnectionMultiplexer and GetDatabase(). Hand-rolling the connection would mean configuring TLS and the secret yourself.

If you genuinely want to trigger on Redis (Pub/Sub, List, or Stream), the Microsoft.Azure.Functions.Worker.Extensions.Redis extension exists, but two things apply. The trigger attribute's first argument is an app-setting name, so you wire the connection with the WithEnvironment form from the next section rather than WithReference. And the Redis triggers run only on Elastic Premium or dedicated App Service plans, not Consumption or Flex Consumption. For the serverless default, the IConnectionMultiplexer-via-DI path above is the one that works on every plan.

How Aspire resolves dev versus production

Three declarations, three behaviors at the trigger boundary. The rule underneath them is exact, so state it exactly: Aspire auto-wires four integrations into the Functions binding system through WithReference, and those four are Blob Storage, Queue Storage, Event Hubs, and Service Bus. For one of those, WithReference(resource, "name") is the whole wiring. For anything else (Redis, Cosmos, SQL, Tables, a custom service), you set the env var yourself:

builder.AddAzureFunctionsProject<Projects.OrderProcessor_ServiceBus>("orders-sb")
    .WithEnvironment("RedisConnection", cache.Resource.ConnectionStringExpression);

One line per non-auto-wired resource. Real, but bounded, and the same shape every time.

What the name buys you is single-sourcing of the connection value, not the name. WithReference(messaging, "messaging") and [ServiceBusTrigger(Connection = "messaging")] agree because you wrote "messaging" in both places. Aspire computes what that name resolves to and how that changes between local and published; it does not derive the name or check that the two spellings match. The one fully-automatic name in the whole system is AzureWebJobsStorage, injected by AddAzureFunctionsProject<T>() itself. Every other name is a contract you keep in code.

The resolution itself keys off execution context, not config files. RunAsEmulator() (Service Bus, Storage) and the local container (AddRedis) are what you get when you run the AppHost. Run azd in publish mode and RunAsEmulator() becomes a no-op, so the same declaration provisions the real Azure resource. There is no appsettings.Production.json toggling between them; the decision is whether you're running or publishing.

The connection's shape flips on publish, and this is the part that's easy to miss. Provisioned Azure resources default to identity-based connections, so a published Storage connection is a __serviceUri and a Service Bus connection is a __fullyQualifiedNamespace, not a key-bearing string. For the four auto-wired integrations Aspire emits the right suffix for you. For the escape-hatch resources you write that branch. A Tables service is the clean example: it's Storage, but not one of the auto-wired four, so locally the binding reads a connection string and on Azure it needs the identity-based service URI. You switch the env-var suffix on the execution context:

var ledger = appStorage.AddTables("ledger");

builder.AddAzureFunctionsProject<Projects.OrderProcessor_ServiceBus>("orders-sb")
    .WithEnvironment(
        builder.ExecutionContext.IsPublishMode ? "Ledger__serviceUri" : "Ledger",
        ledger.Resource.ConnectionStringExpression);

Locally that injects the Azurite table endpoint under the name Ledger; on publish the name becomes Ledger__serviceUri pointing at the provisioned account, and the Azure SDK reads managed identity off the suffix. The auto-wired four run this same switch for you; for everything else, this one line is it.

The default publish target is Azure Container Apps, which is GA; publishing as a real Function App needs Aspire.Hosting.Azure.AppService, still preview as of May 2026. Part 3 takes the publish path apart.

Three resources, one source of truth

The migration from Part 1 is additive again. The AppHost gains four declarations (a Service Bus namespace and its queue, a second storage resource, a Redis cache) and three WithReference lines on one new Functions project. The worker gains one AddRedisClient("cache") call. Those few lines start five containers when you run the AppHost: two Azurite instances (host storage and app-storage), the Service Bus emulator with its mssql/server:2022-latest backend, and Redis 8.6. You declared three services; Aspire pulled the images, generated the secrets between them, and wired every connection.

No connection strings moved into local.settings.json, because that's the file the whole exercise is removing as a source of truth. Keep FUNCTIONS_WORKER_RUNTIME in it and let Aspire own the rest; if a value is set in both, Aspire wins. One line is worth deleting on the way out: the Functions template seeds AzureWebJobsStorage to UseDevelopmentStorage=true, which starts its own Azurite and can race the one Aspire owns. Remove it and let AddAzureFunctionsProject<T>() inject host storage instead.

The honest scope: the Service Bus emulator is dev/test only and runs under Rosetta on Apple Silicon, Redis isn't auto-wired and its trigger extension is Premium-plan only, and identity-based connections on publish need one branch for the resources outside the auto-wired four. None of that is a blocker, but a teammate hits each one eventually, so put them in the README, not the postmortem.

Part 3 takes this AppHost to Azure: what azd provisions, why Container Apps is the default target, and what Aspire generates under the hood.

Of these three, which do you configure by hand today, a Service Bus connection per environment, a second storage account, or a Redis cache, and which one would you move into the AppHost first?

REDB inside, part 1 — the 13 tables the whole engine runs on (with the actual SQL, and why it's not EAV)

rinat kozin — Thu, 04 Jun 2026 18:49:10 +0000

A couple of weeks ago I published the redb.Core intro post — what RedBase is at the API level, why I wrote it, what production looks like, the LINQ surface, what generated SQL looks like for nested dictionary lookups. If you haven't read it, start there — it's the wide-angle shot.

This post starts a new series — "REDB inside" — that drills down into the engine. One article per layer:

Part 1 (this post) — the database schema. 13 tables, what each one does, why the design is what it is, and the SQL you'd run to dump any object flat.
Part 2 — code-first schemes. How SyncSchemeAsync<T> walks a C# class and turns it into rows in _schemes + _structures, the _structure_hash mechanism, automatic onboarding via InitializeAsync.
Part 3 — CRUD internals. SaveAsync, LoadAsync, the TreeDiff change-tracking algorithm, COPY-protocol bulk insert, lazy loading.
Part 4 — LINQ-to-SQL. How Where(x => x.Salary > 80000) becomes WHERE _id_structure = X AND _Long > 80000, the pivot CTE patterns, dialect differences (Postgres array_agg FILTER vs MSSQL MAX CASE WHEN).
Part 5 — trees. LoadTreeAsync, GetDescendantsAsync, WhereHasAncestor, closure-table vs recursive CTE.
Part 6 — window functions. Win.RowNumber(), Win.Rank(), PartitionBy/OrderBy over REDB objects.

Each one stands alone. You don't need to read them in order — but if you want to understand why anything in parts 2-6 works the way it does, you need this post. Everything else is built on the 13 tables.

The whole RedBase engine runs on 13 tables. No JSON blob hiding the schema, no NVARCHAR(MAX) catch-all column — every C# type lands in its own typed column. Let me show you how that works, and why this isn't classical EAV even though it kind of looks like it at first glance.

"Wait, isn't this just EAV?"

It's the most common reaction I get, and it deserves a real answer before we look at any DDL.

Classical EAV (Entity–Attribute–Value) looks like this:

object_id | attribute_name | value
----------|----------------|---------
42        | "FirstName"    | "Alice"
42        | "Age"          | "28"
42        | "Salary"       | "85000"

Everything in one table. Types erased. Attribute names are strings. Any non-trivial query becomes a self-join or a giant PIVOT. The filter "employees earning over $80k" turns into:

SELECT object_id
FROM   attributes
WHERE  attribute_name = 'Salary'
  AND  value::numeric > 80000;   -- runtime cast, no usable index

Add three more conditions and you're looking at three self-joins on the same table. Explain plans get embarrassing.

REDB doesn't do that. Here's what _values actually looks like:

CREATE TABLE _values (
    _id              bigint NOT NULL,
    _id_structure    bigint NOT NULL,   -- FK → _structures (which field this is)
    _id_object       bigint NOT NULL,   -- FK → _objects
    -- typed value columns, exactly one is non-NULL per row:
    _String          text NULL,
    _Long            bigint NULL,
    _Guid            uuid NULL,
    _Double          float NULL,
    _DateTimeOffset  timestamptz NULL,
    _Boolean         boolean NULL,
    _ByteArray       bytea NULL,
    _Numeric         numeric(38,18) NULL,
    _ListItem        bigint NULL,       -- FK → _list_items
    _Object          bigint NULL,       -- FK → _objects (cross-object reference)
    -- relational collection storage:
    _array_parent_id bigint NULL,       -- FK → _values (parent element)
    _array_index     text NULL          -- '0','1','2' for arrays, key for dictionaries
);

The field identity is a foreign key (_id_structure), not a string. The value lives in a typed column chosen at write time based on the field's declared C# type. Think of it as runtime type information (RTTI) persisted into the schema: the engine always knows what type each field is, because that's recorded once in _structures._id_type and reused for every value of that field.

Reading values back is one CASE expression dispatched on type, not a self-join:

CASE c.db_type
  WHEN 'String'  THEN v._String
  WHEN 'Long'    THEN v._Long::text
  WHEN 'Guid'    THEN v._Guid::text
  ...
END

The practical differences:

	Classical EAV	REDB `_values`
Field identity	string in `attribute_name`	FK → `_structures` → `_types`
Where the value lives	one `text`/`varchar(max)` column	typed column per C# type
Filter `Salary > 80000`	`WHERE attribute_name='Salary' AND value::numeric > 80000`	`WHERE _id_structure = $1 AND _Long > 80000`
Index on the value	string index + runtime cast	partial B-tree index on the typed column
Arrays/dictionaries	separate table or JSON blob	`_array_parent_id` + `_array_index` in the same row
Schema metadata	implicit in attribute names	first-class rows in `_schemes`/`_structures`/`_types`, denormalized into a metadata cache

So yes, the row shape rhymes with EAV — but the type system and the indexing story are completely different. That's why I've been pushing back on the EAV label.

The 13 tables, at a glance

_types          — type catalog (~37 system rows)
_schemes        — schemes (C# classes mapped to DB rows)
_structures     — fields of schemes (with nesting and collection metadata)
_objects        — objects (data rows, tree-shaped via self-FK)
_values         — field values (typed columns + relational collections)
_lists          — pick-list/dictionary catalog
_list_items     — pick-list entries
_users          — users (system IDs −1, 0, 1)
_roles          — roles
_users_roles    — M2M user ↔ role
_permissions    — permissions on objects (inherited along the tree)
_links          — M2M relations between objects
_functions      — stored expressions attached to schemes
_dependencies   — cross-scheme dependencies
─────────────────────────────────────────────
_scheme_metadata_cache   — denormalized cache of structures × types
_migrations              — history of props-schema migrations

The last two live in their own SQL files but matter just as much in practice. Let's walk through them layer by layer.

Layer 1 — the type catalog: `_types`

CREATE TABLE _types (
    _id      bigint NOT NULL PRIMARY KEY,
    _name    text NOT NULL UNIQUE,
    _db_type text NULL,   -- which _values column to use: 'Long', 'String', 'Guid', ...
    _type    text NULL    -- C# type name: 'long', 'string', 'Guid', ...
);

System type IDs are negative constants near long.MinValue. A small sample:

`_id`	`_name`	`_db_type`	C# type
-9223372036854775709	Boolean	Boolean	`bool`
-9223372036854775708	DateTime	DateTimeOffset	`DateTime`
-9223372036854775704	Long	Long	`long`
-9223372036854775700	String	String	`string`
-9223372036854775695	Decimal	Numeric	`decimal`
-9223372036854775675	Class	—	nested class (marker only)
-9223372036854775668	Array	—	`T[]` / `List<T>` (marker only)
-9223372036854775667	Dictionary	—	`Dictionary<K,V>` (marker only)

The scary-looking numbers are just constants picked far from anything a user-generated key could ever hit (user IDs start at 1_000_000 via a global_identity sequence). Class, Array, and Dictionary have no column of their own in _values — they're marker types; the actual leaves live in child rows.

There are ~37 built-in types total. Numeric ones (Int, Short, Byte, Float) physically store as Long/Double. Strings include semantic variants (Email, Url, Phone) that all use _String. Then DateOnly/TimeOnly/TimeSpan, geo (Latitude/Longitude), file metadata (FilePath/MimeType), Enum/EnumInt, and collection markers (Array/Dictionary/JsonDocument/XDocument).

Layer 2 — schemes and fields: `_schemes` + `_structures`

CREATE TABLE _schemes (
    _id             bigint NOT NULL,
    _id_parent      bigint NULL,          -- nesting (namespaces)
    _name           text NOT NULL UNIQUE, -- e.g. 'MyApp.Models.EmployeeProps'
    _alias          text NULL,
    _structure_hash uuid NULL,            -- field hash for fast change detection
    _type           bigint NOT NULL       -- FK → _types (Class by default)
);

CREATE TABLE _structures (
    _id              bigint NOT NULL,
    _id_parent       bigint NULL,     -- nested props class
    _id_scheme       bigint NOT NULL, -- FK → _schemes
    _id_type         bigint NOT NULL, -- FK → _types
    _id_list         bigint NULL,     -- FK → _lists (for ListItem fields)
    _name            text NOT NULL,   -- C# property name
    _alias           text NULL,
    _order           bigint NULL,
    _collection_type bigint NULL,     -- NULL=scalar, Array_ID or Dictionary_ID
    _key_type        bigint NULL,     -- key type for Dictionary<K,V>
    _readonly        boolean NULL,
    _allow_not_null  boolean NULL,
    _is_compress     boolean NULL,
    _store_null      boolean NULL,
    _default_value   bytea NULL
);

When you write:

[RedbScheme("Employee")]
public class EmployeeProps
{
    public string FirstName            { get; set; } = "";
    public int    Age                  { get; set; }
    public decimal Salary              { get; set; }
    public string[]? Skills            { get; set; }
    public Address? HomeAddress        { get; set; }   // nested class
}

…and await redb.SyncSchemeAsync<EmployeeProps>() fires for the first time, the engine:

Inserts a row into _schemes with _name = "MyApp.EmployeeProps".
Inserts one _structures row per public property.
For Skills: sets _collection_type = Array_ID.
For HomeAddress: sets _id_type = Class_ID and recursively creates child _structures rows whose _id_parent points back at the parent structure.

Then it computes a hash over all those structures and writes it to _schemes._structure_hash. Next time you call sync, comparing one UUID tells the engine whether anything actually changed — no row-by-row diff needed.

There's a DB-level trigger that validates field names: no system-reserved (_id, _name, _date_create), no C# keywords (class, int, string), no leading digits. If you accidentally try to name a property int, the INSERT throws before the bad row ever lands.

Layer 3 — objects: `_objects`

CREATE TABLE _objects (
    _id             bigint NOT NULL,
    _id_parent      bigint NULL,          -- tree parent (self-FK)
    _id_scheme      bigint NOT NULL,      -- FK → _schemes
    _id_owner       bigint NOT NULL,      -- FK → _users
    _id_who_change  bigint NOT NULL,      -- FK → _users
    _date_create    timestamptz NOT NULL,
    _date_modify    timestamptz NOT NULL,
    _date_begin     timestamptz NULL,
    _date_complete  timestamptz NULL,
    _key            bigint NULL,
    _name           text NULL,
    _note           text NULL,
    _hash           uuid NULL,
    -- value columns for RedbPrimitive<T>:
    _value_long     bigint NULL,
    _value_string   text NULL,
    _value_guid     uuid NULL,
    _value_bool     boolean NULL,
    _value_double   float NULL,
    _value_numeric  numeric(38,18) NULL,
    _value_datetime timestamptz NULL,
    _value_bytes    bytea NULL
);

Three things worth pointing out:

The tree via _id_parent is ON DELETE CASCADE. Drop a root, the whole subtree goes with it. Depth is unbounded. This is the primary organizational structure in REDB: sections, categories, folders, org charts, project trees — they're all just _objects rows pointing at a parent.

The _value_* columns are for RedbPrimitive<T>. When an object is conceptually a single primitive (e.g. RedbObject<long> for a counter, RedbObject<string> for a token), there's no need to spin up _values rows — the value rides in the object row itself. Eight columns, one per _db_type.

Soft delete is a scheme called @@__deleted (_id = -10). mark_for_deletion() walks the subtree via recursive CTE and atomically reparents everything under a trash container with _id_scheme = -10. Actual physical deletion is a separate, batched purge_trash(). This means you can offer "undelete" cheaply, and your data lake/CDC tools never see a destructive delete on the hot path.

Layer 4 — the values: `_values`

This is the table that earns its keep. Everything else exists to make this one fast and consistent.

The DDL was up top. The interesting part is how collections fit into a flat row layout without a side table.

Scalar field

Age = 28 produces exactly one row:

_id_structure=struct_Age   _id_object=42   _Long=28   _array_parent_id=NULL   _array_index=NULL

Array of primitives

Skills = ["C#", "SQL", "React"] produces a marker row plus one row per element:

-- marker: "the array property exists" (without it, the property is NULL, not [])
_id=100   _id_structure=struct_Skills   _id_object=42   _array_index=NULL   _array_parent_id=NULL

-- elements; _array_parent_id points at the marker; _array_index is the position
_id=101   _id_structure=struct_Skills   _id_object=42   _String="C#"     _array_index='0'   _array_parent_id=100
_id=102   _id_structure=struct_Skills   _id_object=42   _String="SQL"    _array_index='1'   _array_parent_id=100
_id=103   _id_structure=struct_Skills   _id_object=42   _String="React"  _array_index='2'   _array_parent_id=100

That marker row matters: it's how the engine tells null (no marker, no elements) apart from [] (marker present, zero children). The same shape works for empty dictionaries too.

Dictionary

PhoneDir = { "home": "+7 999…", "work": "+7 495…" }:

-- marker
_id=200   _id_structure=struct_PhoneDir   _id_object=42   _array_index=NULL   _array_parent_id=NULL

-- entries; _array_index holds the dictionary key (as text)
_id=201   _id_structure=struct_PhoneDir   _id_object=42   _String="+7 999..."   _array_index='home'   _array_parent_id=200
_id=202   _id_structure=struct_PhoneDir   _id_object=42   _String="+7 495..."   _array_index='work'   _array_parent_id=200

_array_index is text precisely so dictionaries with string keys work without a separate table. Numeric dictionaries store keys as their string representation.

Nested class

HomeAddress.City = "Moscow" works the same way. The _structures rows for Address.City, Address.Street, etc. carry an _id_parent pointing at the parent structure (HomeAddress). The _values rows for those leaves carry an _array_parent_id pointing at the marker row for HomeAddress on this particular object.

Three unique indexes keep all of this consistent

CREATE UNIQUE INDEX UIX__values__structure_object
    ON _values (_id_structure, _id_object)
    WHERE _array_index IS NULL AND _array_parent_id IS NULL;

CREATE UNIQUE INDEX UIX__values__structure_object_parent
    ON _values (_id_structure, _id_object, _array_parent_id)
    WHERE _array_index IS NULL AND _array_parent_id IS NOT NULL;

CREATE UNIQUE INDEX UIX__values__structure_object_array_index
    ON _values (_id_structure, _id_object, _array_parent_id, _array_index)
    WHERE _array_index IS NOT NULL;

These three together guarantee: (a) at most one scalar/marker row per (structure, object), (b) at most one nested-class marker per (structure, object, parent), and (c) at most one element per (structure, object, parent, index). Try to insert a duplicate array element and the DB rejects it before any logic bug can corrupt the shape.

Layer 5 — permissions: `_permissions`

CREATE TABLE _permissions (
    _id      bigint NOT NULL,
    _id_role bigint NULL,   -- XOR with _id_user (CHECK constraint)
    _id_user bigint NULL,
    _id_ref  bigint NOT NULL,  -- 0 = global, otherwise FK → _objects
    _select  boolean NULL,
    _insert  boolean NULL,
    _update  boolean NULL,
    _delete  boolean NULL
);

Permissions inherit along the object tree. A recursive CTE walks upwards from the target object up to 50 levels looking for the nearest ancestor that has an explicit permission row. _id_ref = 0 is the global fallback ("can this principal touch anything at all?"). Resolution priority is: user > role, specific object > global.

There's an automatic trigger that, when a child object is created without its own permission row, copies down the resolved permission from the nearest ancestor. The point isn't to materialize every permission — it's to keep the recursive CTE short. After a few months of activity the depth the resolver has to climb stays roughly constant.

`_scheme_metadata_cache` — why a cache table

Every query needs to know: "for an object with _id_scheme = X, which _structures rows exist, and what's the type of each?" That's a JOIN through _structures → _types that would otherwise fire on every single read.

So that JOIN is denormalized into a separate table that gets refreshed when the scheme changes:

CREATE TABLE _scheme_metadata_cache (
    _scheme_id           bigint NOT NULL,
    _structure_id        bigint NOT NULL,
    _parent_structure_id bigint,
    _name                text NOT NULL,
    type_name            text NOT NULL,   -- 'Long', 'String', 'Guid', ...
    db_type              text NOT NULL,   -- 'Long', 'String', 'Guid', ...
    type_semantic        text NOT NULL,   -- 'Object', '_RObject', 'Array', ...
    _collection_type     bigint,
    collection_type_name text,
    _key_type            bigint,
    key_type_name        text
    -- ... all the other _structures attributes inlined
);

A trigger on _schemes._structure_hash invalidates the cache for that scheme; on the next read, sync_metadata_cache_for_scheme(scheme_id) rebuilds it lazily. The big build_hierarchical_properties_optimized() function — the one that materializes an object's full property tree into JSON — never JOINs _structures or _types directly. It reads from this cache, and only from this cache.

Two SQL queries: dump any object flat

Here are two queries that show exactly what's in the box for a given object. The first uses raw JOINs (use this for ad-hoc debugging in DataGrip/SSMS). The second uses _scheme_metadata_cache — what the engine actually runs at scale.

Query 1 — flat pivot, no cache

-- PostgreSQL
SELECT
    s._name                                          AS scheme_name,
    st._name                                         AS field_name,
    t._name                                          AS type_name,
    CASE t._db_type
        WHEN 'String'         THEN v._String
        WHEN 'Long'           THEN v._Long::text
        WHEN 'Guid'           THEN v._Guid::text
        WHEN 'Double'         THEN v._Double::text
        WHEN 'Boolean'        THEN v._Boolean::text
        WHEN 'DateTimeOffset' THEN v._DateTimeOffset::text
        WHEN 'Numeric'        THEN v._Numeric::text
        WHEN 'ListItem'       THEN v._ListItem::text
        WHEN 'Object'         THEN v._Object::text
        WHEN 'ByteArray'      THEN encode(v._ByteArray, 'base64')
        ELSE                       NULL
    END                                              AS value_text,
    CASE
        WHEN v._array_parent_id IS NULL
         AND v._array_index     IS NULL
         AND t._name IN ('Array','Dictionary','Class')  THEN 'collection_marker'
        WHEN v._array_parent_id IS NULL
         AND v._array_index     IS NULL                 THEN 'scalar'
        WHEN v._array_parent_id IS NOT NULL             THEN 'element[' || v._array_index || ']'
        ELSE                                                 'scalar'
    END                                              AS slot,
    v._array_index,
    v._array_parent_id
FROM _values      v
JOIN _structures  st ON st._id = v._id_structure
JOIN _schemes     s  ON s._id  = st._id_scheme
JOIN _types       t  ON t._id  = st._id_type
WHERE v._id_object = :object_id
ORDER BY st._order NULLS LAST, v._array_index NULLS FIRST;

-- MS SQL Server
SELECT
    s._name                                          AS scheme_name,
    st._name                                         AS field_name,
    t._name                                          AS type_name,
    CASE t._db_type
        WHEN 'String'         THEN v._String
        WHEN 'Long'           THEN CAST(v._Long AS nvarchar(MAX))
        WHEN 'Guid'           THEN CAST(v._Guid AS nvarchar(MAX))
        WHEN 'Double'         THEN CAST(v._Double AS nvarchar(MAX))
        WHEN 'Boolean'        THEN CASE v._Boolean WHEN 1 THEN 'true' WHEN 0 THEN 'false' END
        WHEN 'DateTimeOffset' THEN CAST(v._DateTimeOffset AS nvarchar(MAX))
        WHEN 'Numeric'        THEN CAST(v._Numeric AS nvarchar(MAX))
        WHEN 'ListItem'       THEN CAST(v._ListItem AS nvarchar(MAX))
        WHEN 'Object'         THEN CAST(v._Object AS nvarchar(MAX))
        WHEN 'ByteArray'      THEN N'<binary, base64 in app code>'
        ELSE                       NULL
    END                                              AS value_text,
    CASE
        WHEN v._array_parent_id IS NULL AND v._array_index IS NULL THEN 'scalar'
        WHEN v._array_parent_id IS NOT NULL                        THEN 'element[' + ISNULL(v._array_index,'') + ']'
        ELSE                                                            'scalar'
    END                                              AS slot,
    v._array_index,
    v._array_parent_id
FROM [dbo].[_values]      v
JOIN [dbo].[_structures]  st ON st._id = v._id_structure
JOIN [dbo].[_schemes]     s  ON s._id  = st._id_scheme
JOIN [dbo].[_types]       t  ON t._id  = st._id_type
WHERE v._id_object = @object_id
ORDER BY st._order, v._array_index;

This is a diagnostic query — paste it into psql/DataGrip/SSMS, plug in any object ID, and you see exactly what's stored: which fields, which slot (scalar / collection marker / array element), which type. The marker rows for arrays show up too, which is exactly what you want when you're hunting down a null vs [] regression.

Query 2 — same result via `_scheme_metadata_cache`

-- PostgreSQL (via _scheme_metadata_cache)
SELECT
    c._scheme_id                                      AS scheme_id,
    c._name                                           AS field_name,
    c.type_name                                       AS type_name,
    c.db_type                                         AS db_type,
    c.collection_type_name                            AS collection_type,
    CASE c.db_type
        WHEN 'String'         THEN v._String
        WHEN 'Long'           THEN v._Long::text
        WHEN 'Guid'           THEN v._Guid::text
        WHEN 'Double'         THEN v._Double::text
        WHEN 'Boolean'        THEN v._Boolean::text
        WHEN 'DateTimeOffset' THEN v._DateTimeOffset::text
        WHEN 'Numeric'        THEN v._Numeric::text
        WHEN 'ListItem'       THEN v._ListItem::text
        WHEN 'Object'         THEN v._Object::text
        WHEN 'ByteArray'      THEN encode(v._ByteArray, 'base64')
        ELSE                       NULL
    END                                               AS value_text,
    v._array_index,
    v._array_parent_id,
    c._order
FROM _values                v
JOIN _scheme_metadata_cache c ON c._structure_id = v._id_structure
WHERE v._id_object = :object_id
ORDER BY c._order NULLS LAST, v._array_index NULLS FIRST;

-- MS SQL Server (via _scheme_metadata_cache)
SELECT
    c.[_scheme_id]                                    AS scheme_id,
    c.[_name]                                         AS field_name,
    c.[type_name]                                     AS type_name,
    c.[db_type]                                       AS db_type,
    c.[collection_type_name]                          AS collection_type,
    CASE c.[db_type]
        WHEN 'String'         THEN v._String
        WHEN 'Long'           THEN CAST(v._Long AS nvarchar(MAX))
        WHEN 'Guid'           THEN CAST(v._Guid AS nvarchar(MAX))
        WHEN 'Double'         THEN CAST(v._Double AS nvarchar(MAX))
        WHEN 'Boolean'        THEN CASE v._Boolean WHEN 1 THEN 'true' WHEN 0 THEN 'false' END
        WHEN 'DateTimeOffset' THEN CAST(v._DateTimeOffset AS nvarchar(MAX))
        WHEN 'Numeric'        THEN CAST(v._Numeric AS nvarchar(MAX))
        WHEN 'ListItem'       THEN CAST(v._ListItem AS nvarchar(MAX))
        WHEN 'Object'         THEN CAST(v._Object AS nvarchar(MAX))
        WHEN 'ByteArray'      THEN N'<binary>'
        ELSE                       NULL
    END                                               AS value_text,
    v._array_index,
    v._array_parent_id,
    c.[_order]
FROM [dbo].[_values]                v
JOIN [dbo].[_scheme_metadata_cache] c ON c.[_structure_id] = v.[_id_structure]
WHERE v.[_id_object] = @object_id
ORDER BY c.[_order], v.[_array_index];

Why the second one is the production query:

Two heavy JOINs (_structures, _types) gone. The cache row carries everything those joins would have produced.
The cache already has a B-tree on _structure_id and a stable _order for ordering — no extra sorts.
The cache is refreshed only when the scheme changes (_structure_hash flips), not on every read. Steady-state queries pay zero cost for it.
build_hierarchical_properties_optimized() goes one step further: it slurps all _values rows for one object into a _values[] array in a single SELECT, then walks the property tree purely in memory using unnest(). Recursion into nested classes and array elements never touches the table again. For deeply nested object graphs this is a big deal — you can materialize a 40-row, 8-level-deep object with two SELECTs total.

How this connects to the C# API

For context — what those tables look like from a SaveAsync/LoadAsync perspective. The full API tour is in the intro post; here's just the mapping back to the tables we just looked at:

[RedbScheme("Employee")]
public class EmployeeProps
{
    public string  FirstName { get; set; } = "";
    public string  LastName  { get; set; } = "";
    public int     Age       { get; set; }
    public decimal Salary    { get; set; }
    public string[]? Skills  { get; set; }
}

// InitializeAsync scans the assembly →
//   - inserts/updates rows in _schemes + _structures for each [RedbScheme]
//   - refreshes _scheme_metadata_cache on changed schemes
await redb.InitializeAsync(typeof(EmployeeProps).Assembly);

// SaveAsync →
//   - one row into _objects
//   - one row per scalar into _values (using the typed column for the C# type)
//   - for Skills: one marker row + one row per element, linked via _array_parent_id
var employee = new RedbObject<EmployeeProps>
{
    name  = "Alice Johnson",
    Props = new EmployeeProps
    {
        FirstName = "Alice",
        LastName  = "Johnson",
        Age       = 28,
        Salary    = 120_000m,
        Skills    = ["C#", "PostgreSQL", "Redis"]  // → 1 marker + 3 element rows
    }
};
long id = await redb.SaveAsync(employee);

// LoadAsync →
//   - SELECT _objects WHERE _id = id
//   - SELECT * FROM _values WHERE _id_object = id  (one shot, into a _values[])
//   - build_hierarchical_properties_optimized() materializes the C# graph
var loaded = await redb.LoadAsync<EmployeeProps>(id);

SaveAsync reads _scheme_metadata_cache to know which column to write each value to, mints IDs from the global_identity sequence, and writes _objects + _values. LoadAsync reads _objects first, then one SELECT pulls every _values row for that object into a memory array, and the recursive materializer never goes back to the database for that load.

A few design choices that aren't obvious

Negative constants for system IDs. User-generated keys come from a sequence starting at 1_000_000. System types, schemes, users live near long.MinValue. The two ranges can never collide. This means _types._id = -10 for the @@__deleted scheme isn't a special-case in any query — it's just a perfectly normal FK that happens to be negative.

_structure_hash on _schemes. Without it, every SyncSchemeAsync<T> call would have to re-read the schema structure and compare row-by-row. With it, comparing one UUID tells you whether anything changed. The cache-invalidation trigger fires only on real changes, so steady-state operation pays nothing.

Marker rows. The trickiest design choice in _values. There's no separate "collections" table — instead, a row with _array_index = NULL AND _array_parent_id = NULL and a collection-typed _id_structure is the marker, and child rows fan out from it via _array_parent_id. This is what makes null vs [] distinguishable, lets dictionaries with string keys work without a side table, and keeps nested-class hierarchies in the same physical structure as flat fields.

_Numeric NUMERIC(38, 18). Deliberate. double for money quietly loses pennies; nobody wants a 0.0000000001-off invoice total in production. The 38/18 precision/scale is more than enough for currency, percentage, weight, even small molar quantities. The cost is storage size (16 bytes vs 8), which on the kind of property volume REDB sees is noise.

Postgres vs MSSQL — the cascade-delete story. On Postgres, _values has ON DELETE CASCADE on its FK to _structures. On MSSQL the same constraint would create multiple cascade paths and SQL Server refuses to compile that. The workaround: an INSTEAD OF DELETE trigger on _structures that manually cascades into _values. Same observable behavior, different machinery. There are a handful of places in the codebase where the dialect abstraction exists specifically to paper over this kind of thing.

Series links

Intro post — An EF Core alternative for .NET apps with complex object graphs (published)
Part 1 (this post) — the 13 tables, RTTI vs EAV, _values, collection storage, _scheme_metadata_cache, two diagnostic queries
Part 2 — code-first schemes: SyncSchemeAsync<T>, _structure_hash, automatic onboarding
Part 3 — CRUD internals: SaveAsync/LoadAsync, TreeDiff change tracking, COPY-protocol bulk insert
Part 4 — LINQ → SQL: pivot CTEs, dialect splits, the OfficeLocations["HQ"].City walkthrough
Part 5 — trees: LoadTreeAsync, WhereHasAncestor, the closure-table vs recursive-CTE story
Part 6 — window functions: Win.RowNumber(), Win.Rank(), PartitionBy/OrderBy over REDB objects

Where to look

github.com/redbase-app — all repos in the ecosystem
github.com/redbase-app/redb — the redb.Core repo
Postgres schema (redbPostgre.sql) — all 13 tables + 40+ indexes + triggers + stored functions in one file
MSSQL schema (redbMSSQL.sql) — same shape, dialect-adjusted
redbase.app — docs and worked examples (EN)

Questions/critique very welcome in the comments — especially if you've built something similar and have war stories about indexing strategies on the values table, that's exactly the discussion I want to have.

The Industry Is Obsessed With Models (AI). Nobody Is Doing the "Engineering."

Sundar Rengamani — Thu, 04 Jun 2026 17:46:22 +0000

Every conference. Every benchmark. Every funding round.
Better models. Bigger context windows. Faster inference.

The industry has a supply-side obsession—and it has completely neglected the demand side: an enterprise that needs AI to deliver sovereign, auditable, compliant outcomes in production.

Nobody is engineering that.

The Real Enterprise Battleground

I am a Sovereign AI Architect. My job: make models deliver within a boundary—secrets, IP, and institutional knowledge stay inside it.

RAG doesn't solve this. Frontier models don't. Prompt engineering doesn't.
This is an engineering problem. And nobody is engineering it.

So I Started at the Bottom of the Pyramid

Strip away the model obsession and ask: what does the enterprise actually need?

You end up with data. Not vector stores. Not embeddings. Not retrieval pipelines.

Data itself. How it is treated. How it travels. Whether it can carry intelligence.

Can data have intelligence?

Yes—and it changes everything.

This led to the DataMolecule Carrier Pattern — DataEnvelope<T> — a typed, lineage-carrying entity that travels across agentic boundaries without losing context, without reconstructing what it already knew, and without dying at the scope boundary.

public class DataEnvelope<T> where T : class
{
    public string EnvelopeId { get; }
    public T Payload { get; }
    public ILineageChain Lineage { get; init; }
    public IEnvelopeContext Context { get; }
    public IIntentHints? Intent { get; init; }

    public void AppendLineageStep(ILineageStep step);

    public string ToAuditSummary();
    // Envelope={id} Correlation={id} Workflow={id}
    // Payload={T} LineageSteps={n} Intent={goal}
}

Intelligence travels. It does not reconstruct.

This Series Is Engineer-to-Engineer

Every post: a pattern, a decision, or an argument—with code, tradeoffs, and the reasoning behind the architecture.

// Coming next:
// DataEnvelope<T>        — typed carrier, deep dive
// AppendLineageStep()    — immutable lineage, not event sourcing
// DCPVault               — closed envelopes become sovereign corpus
// GoalRouter             — deterministic code vs probabilistic models
// SLM-per-agent          — structured carrier makes 7B viable

The real enterprise battleground is not the model. It is the engineering underneath it.

Engineer to engineer. Let's build.

DivineTreeDesigns · NuGet Pkgs · DivineTree.DCP · DivineTree.ICP · DivineTree.DCPVault · DivineTree.ICPVault

Apache PDFBox to IronPDF: What Actually Matters

IronSoftware — Thu, 04 Jun 2026 16:54:38 +0000

Most .NET teams who reach for Apache PDFBox end up on one of three NuGet packages: Pdfbox-IKVM, PdfBox_DotNet_Version, or MASES.NetPDF. None of them are official. Two of the three have been abandoned for years. The third still calls out to a real JVM at runtime via JCOBridge. If you have one of these in your .csproj and are wondering whether to keep maintaining a Java-shaped API and a Java-runtime dependency inside a .NET application, this guide is for you.

Apache PDFBox is a solid open-source Java library. The migration question is not about the upstream library's quality. It is about whether the .NET port you happen to be running still belongs in a modern .NET stack. This guide covers the shift to IronPDF, but eighty percent of the framework (dependency auditing, API mapping, testing patterns) applies to any .NET-native PDF library.

Why Migrate

PDFBox is one of the most widely deployed PDF libraries in the world. Here is why .NET teams specifically move away from its .NET ports:

Unofficial port status. Apache ships only Java artifacts. Every .NET PDFBox option on NuGet is a community-driven port. Pdfbox (built against PDFBox 1.8.2) and Pdfbox-IKVM were last published in 2013 and 2017 respectively. PdfBox_DotNet_Version was last published in 2019. MASES.NetPDF is the only actively maintained option, and it is a JCOBridge wrapper that requires a JVM at runtime alongside the CLR.
No HTML-to-PDF. PDFBox does not convert HTML in any form. If you need HTML rendering, you are pairing PDFBox with another tool, adding a second dependency on top of the port.
Runtime baggage. The IKVM-based ports bundle a .NET reimplementation of the JVM. MASES.NetPDF calls into a real JVM via JCOBridge. Either way, the deployment carries Java-runtime weight that idiomatic .NET libraries avoid.
IKVM compatibility gaps. The IKVM-based ports were built against older PDFBox lines (1.8.x or 2.0.x). They do not track upstream PDFBox 3.0.x, and IKVM's coverage of newer Java features is limited.
API verbosity for common operations. Because the ports expose the Java API directly, the surface keeps Java conventions: camelCase methods, File objects, explicit close() calls. Merging two PDFs requires constructing a PDFMergerUtility, adding sources, and calling mergeDocuments(MemoryUsageSetting...).
Manual resource management. Documents hold native resources and must be explicitly closed. In a port that wraps Java semantics, leaking a PDDocument is easier than leaking an IDisposable in idiomatic C#.
Text extraction ordering. PDFBox extracts text in the order it appears in the PDF content stream, which is not necessarily visual order. Reading order requires PDFTextStripper.setSortByPosition(true), a common source of bugs for teams unfamiliar with PDF internals.
No async support. The Java-shaped API is synchronous. In an async .NET pipeline, blocking on JVM-bridge calls ties up thread pool threads.
Font handling across platforms. Font resolution flows through the wrapped Java font infrastructure. Font availability and rendering may differ between development machines and Linux containers in production.
Sparse .NET community. Help, examples, and best practices for .NET-specific issues with these ports are difficult to find. Most search results point at the Java PDFBox documentation, which uses a slightly different API surface than each port exposes.

Comparison Table

Aspect	Apache PDFBox (.NET Ports)	IronPDF (.NET)
Focus	PDF manipulation, text extraction, form filling	HTML-first PDF generation + manipulation
Pricing	Free, Apache License 2.0	Per-developer, perpetual licenses available
API Style	Java objects mirroring PDF spec (PDDocument, PDPage)	C# fluent API, HTML-to-PDF, property-based
Learning Curve	Moderate, Java idioms plus PDF internals	Low, HTML/CSS developers productive quickly
HTML Rendering	None	Built-in Chrome rendering engine
Page Indexing	0-based	0-based
Thread Safety	PDDocument not thread-safe	`ChromePdfRenderer` stateless, safe to share
Namespace	`org.apache.pdfbox.` (IKVM) or `Org.Apache.Pdfbox.` (MASES)	`IronPdf`

Migration Complexity Assessment

Effort by Feature

Feature	Complexity	Notes
HTML to PDF	Low	PDFBox cannot do this; IronPDF is purpose-built for it
Text extraction	Medium	Both extract text; API shape and sort behavior differ
Merge	Low	Both offer merge; IronPDF is a one-liner
Split / extract pages	Low	Different API, same concept
Watermark	Medium	PDFBox uses PDPageContentStream drawing; IronPDF uses HTML overlay
Password / encryption	Medium	PDFBox uses AccessPermission + StandardProtectionPolicy; IronPDF uses SecuritySettings
Form filling (AcroForms)	Medium	Both support AcroForms with different API surfaces
Digital signatures	Medium-High	Different libraries and API patterns
PDF/A validation	High / N/A	PDFBox has the Preflight subproject; IronPDF supports PDF/A export but does not validate existing documents
Image extraction	Medium	Both support image extraction with different APIs
PDF rendering to image	Medium	PDFBox renders pages to BufferedImage; IronPDF rasterizes via `ToBitmap(dpi)`

Decision Matrix

Scenario	Recommendation
.NET app pinned to an abandoned IKVM-based PDFBox port	Migrate. The port no longer tracks upstream and brings IKVM-era constraints
PDFBox used only for text extraction	Evaluate. IronPDF extracts text, but also consider PdfPig as a lighter .NET-native alternative
PDFBox used for PDF/A validation via Preflight	Keep Preflight (or veraPDF) as a separate validator; IronPDF generates PDF/A but does not validate
Full .NET stack, needs HTML-to-PDF + manipulation	Migrate. IronPDF covers both in one NuGet package

Before You Start

Prerequisites

.NET 6+ (or .NET Framework 4.6.2+)
A trial or licensed IronPDF key
Inventory of which PDFBox port your project uses: Pdfbox, Pdfbox-IKVM, PdfBox_DotNet_Version, or MASES.NetPDF

Find PDFBox References

# Find PDFBox usage across the codebase
rg "org\.apache\.pdfbox|Org\.Apache\.Pdfbox|PDDocument|PDFTextStripper|PDFMergerUtility" --glob "*.cs"

# Identify which port the project references
rg "Pdfbox|Pdfbox-IKVM|PdfBox_DotNet_Version|MASES\.NetPDF" --glob "*.csproj"

In PowerShell: Get-ChildItem -Recurse -Filter *.cs | Select-String "PDDocument|pdfbox|PDFTextStripper".

Swap Dependencies

# Remove whichever PDFBox .NET port your project uses
dotnet remove package Pdfbox            # PDFBox 1.8.2-era IKVM port
dotnet remove package Pdfbox-IKVM       # IKVM wrapper, last published 2017
dotnet remove package PdfBox_DotNet_Version  # last published 2019
dotnet remove package MASES.NetPDF      # JCOBridge wrapper, requires JVM

# Install IronPDF
dotnet add package IronPdf

Quick Start Migration (3 Steps)

Step 1: License Configuration

Before (PDFBox .NET port, no license needed but a JVM-shaped runtime is):

// Apache 2.0 — no license key required.
// IKVM-based ports bundle a .NET-side JVM reimplementation;
// MASES.NetPDF calls into a real JVM via JCOBridge.
using org.apache.pdfbox.pdmodel;

class Program
{
    static void Main()
    {
        PDDocument document = new PDDocument();
        Console.WriteLine($"PDFBox ready. Pages: {document.getNumberOfPages()}");
        document.close();
    }
}

After (IronPDF, one line of configuration):

using IronPdf;

class Program
{
    static void Main()
    {
        // License key — trial available at ironpdf.com
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        Console.WriteLine($"IronPDF licensed: {License.IsLicensed}");
        // No bundled JVM, no JCOBridge, no Java-shaped API
    }
}

Step 2: Namespace Imports

Before (PDFBox .NET port, IKVM-style):

using org.apache.pdfbox.pdmodel;
using org.apache.pdfbox.pdmodel.font;
using org.apache.pdfbox.text;
using org.apache.pdfbox.multipdf;
using java.io;

After (IronPDF):

using IronPdf;
using IronPdf.Editing;    // watermarks, headers, footers
using IronPdf.Rendering;  // render options

Step 3: Basic PDF Creation

Before (PDFBox .NET port, manual page construction):

using org.apache.pdfbox.pdmodel;
using org.apache.pdfbox.pdmodel.font;
using System;

class Program
{
    static void Main()
    {
        PDDocument document = new PDDocument();
        try
        {
            PDPage page = new PDPage();
            document.addPage(page);

            PDPageContentStream cs = new PDPageContentStream(document, page);
            cs.beginText();
            cs.setFont(PDType1Font.HELVETICA_BOLD, 24);
            cs.newLineAtOffset(72, 700); // x, y from bottom-left
            cs.showText("Monthly Report");
            cs.endText();
            cs.close();

            document.save("report_pdfbox.pdf");
        }
        finally
        {
            document.close();
        }
        Console.WriteLine("Saved with PDFBox.");
    }
}

After (IronPDF, HTML rendering):

using IronPdf;

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

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

        var pdf = renderer.RenderHtmlAsPdf(
            "<h1 style='font-family:Helvetica;font-size:24pt;'>Monthly Report</h1>");

        pdf.SaveAs("report_ironpdf.pdf");
        Console.WriteLine("Saved with IronPDF.");
    }
}

No bundled JVM. No coordinate math. The IronPDF HTML-to-PDF tutorial covers rendering options in detail.

API Mapping Tables

These map the Java-shaped APIs exposed by the PDFBox .NET ports to native IronPDF APIs. Because the ports surface Java method names directly through IKVM or JCOBridge, the differences are both naming (camelCase to PascalCase) and conceptual (page construction to HTML rendering).

Namespace Mapping

PDFBox .NET Port	IronPDF Namespace	Purpose
`org.apache.pdfbox.pdmodel` / `Org.Apache.Pdfbox.Pdmodel`	`IronPdf`	Core document operations
`org.apache.pdfbox.text` / `Org.Apache.Pdfbox.Text`	`IronPdf`	Text extraction
`org.apache.pdfbox.multipdf` / `Org.Apache.Pdfbox.Multipdf`	`IronPdf`	Merge/split utilities
`org.apache.pdfbox.pdmodel.font`	CSS `font-family` in HTML	Font handling
`org.apache.pdfbox.pdmodel.encryption`	`IronPdf.Security`	Security/encryption

Core Class Mapping

PDFBox Class	IronPDF Class	Description
`PDDocument`	`PdfDocument`	The PDF document object
`PDPage`	`pdf.Pages[n]`	Individual page access
`PDPageContentStream`	HTML/CSS via `ChromePdfRenderer`	Content creation (IronPDF uses HTML instead of drawing commands)
`PDFMergerUtility`	`PdfDocument.Merge()`	Document merging

Document Loading Methods

Operation	PDFBox .NET Port	IronPDF
Open from file	`PDDocument.load(new File("f.pdf"))`	`PdfDocument.FromFile("f.pdf")`
Open with password	`PDDocument.load(file, "pass")`	`PdfDocument.FromFile("f.pdf", "pass")`
Create new	`new PDDocument()`	`renderer.RenderHtmlAsPdf(html)`
Save	`document.save("out.pdf")`	`pdf.SaveAs("out.pdf")`

Page Operations

Operation	PDFBox .NET Port	IronPDF
Get page count	`document.getNumberOfPages()`	`pdf.PageCount`
Get page	`document.getPage(index)` (0-based)	`pdf.Pages[index]` (0-based)
Add page	`document.addPage(new PDPage())`	Render HTML (pages auto-created)
Remove page	`document.removePage(index)`	`pdf.RemovePages(index)`

Merge / Split Operations

Operation	PDFBox .NET Port	IronPDF
Merge	`PDFMergerUtility` → `addSource()` → `mergeDocuments()`	`PdfDocument.Merge(pdf1, pdf2)`
Extract pages	`PDDocument.getPage()` + new doc + import page	`pdf.CopyPages(start, end)`

Four Complete Before/After Migrations

1. HTML to PDF

Before (PDFBox has no HTML-to-PDF; common workaround):

// PDFBox cannot convert HTML to PDF.
// Common workaround: shell out to wkhtmltopdf, then optionally
// post-process the result with PDFBox.
using System.Diagnostics;

class HtmlToPdfPdfbox
{
    static void Main()
    {
        var psi = new ProcessStartInfo
        {
            FileName = "wkhtmltopdf",
            Arguments = "--page-size Letter --margin-top 20 --margin-bottom 20 input.html report.pdf"
        };
        var p = Process.Start(psi);
        p.WaitForExit();

        if (p.ExitCode != 0)
        {
            Console.Error.WriteLine($"wkhtmltopdf failed: {p.ExitCode}");
            return;
        }

        // Optional: post-process with PDFBox if needed
        // PDDocument doc = PDDocument.load(new File("report.pdf"));
        // ... manipulate ...
        // doc.save("report_final.pdf");
        // doc.close();

        Console.WriteLine("Generated with wkhtmltopdf + PDFBox.");
    }
}

After (IronPDF):

using IronPdf;

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

        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.Letter;
        renderer.RenderingOptions.MarginTop = 20;
        renderer.RenderingOptions.MarginBottom = 20;
        renderer.RenderingOptions.PrintHtmlBackgrounds = true;

        var pdf = renderer.RenderHtmlAsPdf(@"
            <html><head><style>
                body { font-family: Arial, sans-serif; }
                .title { color: #1a237e; border-bottom: 2px solid #1a237e; padding-bottom: 10px; }
                table { width: 100%; border-collapse: collapse; margin-top: 20px; }
                td, th { padding: 10px; border: 1px solid #e0e0e0; }
                th { background: #f5f5f5; }
            </style></head><body>
                <h1 class='title'>Q4 Sales Report</h1>
                <table>
                    <tr><th>Region</th><th>Revenue</th><th>Growth</th></tr>
                    <tr><td>North</td><td>$1.2M</td><td>+12%</td></tr>
                    <tr><td>South</td><td>$890K</td><td>+8%</td></tr>
                    <tr><td>West</td><td>$2.1M</td><td>+22%</td></tr>
                </table>
            </body></html>");

        pdf.SaveAs("report.pdf");
        Console.WriteLine("Saved with IronPDF.");
    }
}

No external process. No second toolchain. See the IronPDF HTML-to-PDF tutorial.

2. Merge PDFs

Before (PDFBox .NET port):

using org.apache.pdfbox.multipdf;
using org.apache.pdfbox.io;
using System;

class MergePdfbox
{
    static void Main()
    {
        PDFMergerUtility merger = new PDFMergerUtility();
        merger.addSource("part1.pdf");
        merger.addSource("part2.pdf");
        merger.setDestinationFileName("merged_pdfbox.pdf");

        // MemoryUsageSetting governs heap vs temp-file buffering
        merger.mergeDocuments(MemoryUsageSetting.setupMainMemoryOnly());
        Console.WriteLine("Merged with PDFBox.");
    }
}

After (IronPDF):

using IronPdf;

class MergeIronPdf
{
    static void Main()
    {
        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");
        Console.WriteLine("Merged with IronPDF.");
    }
}

No MemoryUsageSetting. No merger utility class. See IronPDF merge documentation.

3. Watermark

Before (PDFBox .NET port, content-stream drawing):

using org.apache.pdfbox.pdmodel;
using org.apache.pdfbox.pdmodel.font;
using org.apache.pdfbox.util;
using java.io;
using System;

class WatermarkPdfbox
{
    static void Main()
    {
        PDDocument doc = PDDocument.load(new File("input.pdf"));
        try
        {
            foreach (PDPage page in doc.getPages())
            {
                PDPageContentStream cs = new PDPageContentStream(
                    doc, page, PDPageContentStream.AppendMode.APPEND, true, true);

                cs.setFont(PDType1Font.HELVETICA, 48);
                cs.setNonStrokingColor(200, 200, 200); // light gray

                // Rotate 45 degrees around page center
                float cx = page.getMediaBox().getWidth() / 2;
                float cy = page.getMediaBox().getHeight() / 2;
                cs.transform(Matrix.getRotateInstance(
                    Math.toRadians(45), cx, cy));

                cs.beginText();
                cs.newLineAtOffset(cx - 100, cy); // approximate centering
                cs.showText("CONFIDENTIAL");
                cs.endText();
                cs.close();
            }

            doc.save("watermarked_pdfbox.pdf");
        }
        finally
        {
            doc.close();
        }
        Console.WriteLine("Watermarked with PDFBox.");
    }
}

After (IronPDF):

using IronPdf;

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

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

        pdf.ApplyWatermark(
            "<h1 style='color:rgb(200,200,200);font-size:48px;opacity:0.5;font-family:Helvetica;'>CONFIDENTIAL</h1>",
            rotation: 45
        );

        pdf.SaveAs("watermarked.pdf");
        Console.WriteLine("Watermarked with IronPDF.");
    }
}

Content-stream operations, matrix transforms, and per-page loops collapse into one HTML string.

4. Password Protection

Before (PDFBox .NET port):

using org.apache.pdfbox.pdmodel;
using org.apache.pdfbox.pdmodel.encryption;
using java.io;
using System;

class PasswordPdfbox
{
    static void Main()
    {
        PDDocument doc = PDDocument.load(new File("input.pdf"));
        try
        {
            AccessPermission perms = new AccessPermission();
            perms.setCanPrint(false);
            perms.setCanModify(false);
            perms.setCanExtractContent(false);

            StandardProtectionPolicy policy = new StandardProtectionPolicy(
                "owner123",  // owner password
                "user456",   // user password
                perms
            );
            policy.setEncryptionKeyLength(128);

            doc.protect(policy);
            doc.save("protected_pdfbox.pdf");
        }
        finally
        {
            doc.close();
        }
        Console.WriteLine("Protected with PDFBox.");
    }
}

After (IronPDF):

using IronPdf;

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

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

        pdf.SecuritySettings.OwnerPassword = "owner123";
        pdf.SecuritySettings.UserPassword = "user456";
        pdf.SecuritySettings.AllowUserPrinting = IronPdf.Security.PdfPrintSecurity.NoPrint;
        pdf.SecuritySettings.AllowUserCopyPasteContent = false;
        pdf.SecuritySettings.AllowUserEdits = IronPdf.Security.PdfEditSecurity.NoEdit;

        pdf.SaveAs("protected.pdf");
        Console.WriteLine("Protected with IronPDF.");
    }
}

No AccessPermission + StandardProtectionPolicy ceremony. See IronPDF security documentation.

Critical Migration Notes

The Runtime Shift Is the Migration

Unlike a port-to-port API swap, this migration changes the runtime shape of the dependency. You are eliminating an IKVM-bundled JVM (or a real JVM via JCOBridge) and the Java-style surface that comes with it. Plan for the dependency cleanup, not just the code rewrite. The .csproj references, transitive Java-class assemblies, and any bootstrap code that initialized the bridge all need to go.

Page Indexing

Both PDFBox and IronPDF use 0-based page indexing. This is the one thing that does not change.

Text Extraction Ordering

PDFBox's PDFTextStripper extracts text in content-stream order by default, which can produce scrambled output. You must set setSortByPosition(true) for visual reading order. IronPDF's ExtractAllText() returns text without requiring that toggle; if extraction quality matters for your corpus, compare outputs side-by-side on representative documents during the migration.

Resource Management

PDFBox's PDDocument requires an explicit close() call. IronPDF's PdfDocument implements IDisposable, so a using block handles cleanup. The pattern maps naturally, and disposal failures are easier to catch in idiomatic C# than in Java-shaped wrappers.

Bouncy Castle Dependency

The IKVM-based PDFBox ports pull in Bouncy Castle for encryption. IronPDF handles encryption internally in .NET, so the Bouncy Castle dependency goes away with the port.

Performance Considerations

Eliminating the Bridge

Calls through IKVM or JCOBridge cross a runtime boundary on every invocation. Direct .NET calls in IronPDF avoid that crossover:

// Before: Java-bridged call through the .NET port
// PDDocument doc = PDDocument.load(new File(path));

// After: in-process .NET, no bridge
using var pdf = PdfDocument.FromFile(path);

Renderer Reuse

private static readonly ChromePdfRenderer _renderer = new ChromePdfRenderer();

Disposal

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

Edge Cases Worth Flagging

Text extraction quality: PDFBox's PDFTextStripper is well-regarded for extraction quality. Compare IronPDF's output against your representative document corpus. For extraction-heavy workloads, also consider PdfPig, a .NET-native PDF text extraction library under Apache 2.0.
PDF/A validation: PDFBox's Preflight module validates PDF/A compliance. IronPDF generates PDF/A but does not validate existing documents. If you need validation, keep Preflight or move to veraPDF.
Large file memory: PDFBox exposes MemoryUsageSetting to choose between heap and temp-file buffering for large documents. IronPDF handles this internally; benchmark with your largest production documents during migration.

Migration Checklist

Pre-Migration (8 items)

[ ] Identify which PDFBox .NET port is referenced: Pdfbox, Pdfbox-IKVM, PdfBox_DotNet_Version, or MASES.NetPDF
[ ] List all PDFBox operations in use: merge, text extraction, form fill, encryption, etc.
[ ] Determine whether PDFBox Preflight (PDF/A validation) is in the dependency tree
[ ] Obtain an IronPDF trial key from ironpdf.com/get-started/license-keys/
[ ] Create a migration branch
[ ] Document any bootstrap code that initializes IKVM or JCOBridge
[ ] Identify all call sites that pass java.io.File or other bridged Java types
[ ] Plan removal of IKVM/JCOBridge runtime assets from the deployment

Code Migration (10 items)

[ ] Add the IronPdf NuGet package to the .NET project
[ ] Set IronPdf.License.LicenseKey in application startup
[ ] Replace PDDocument.load(new File(...)) with PdfDocument.FromFile(...)
[ ] Replace PDFMergerUtility patterns with PdfDocument.Merge()
[ ] Replace PDPageContentStream watermark drawing with ApplyWatermark()
[ ] Replace AccessPermission + StandardProtectionPolicy with SecuritySettings
[ ] Replace external-tool HTML-to-PDF with ChromePdfRenderer.RenderHtmlAsPdf()
[ ] Add using blocks for all PdfDocument instances
[ ] Test text extraction output against the PDFBox baseline
[ ] Remove the PDFBox port and IKVM/JCOBridge packages from .csproj

Testing (7 items)

[ ] Compare PDF merge output byte-for-byte or visually
[ ] Compare text extraction output against PDFBox for 10+ diverse documents
[ ] Test password protection round-trip (encrypt, save, open, verify permissions)
[ ] Test watermark positioning on multi-page documents
[ ] Benchmark native IronPDF calls against the PDFBox-port baseline
[ ] Validate on Linux containers (the bundled JVM and IronPDF's runtime behave differently)
[ ] Run integration tests for all existing PDF workflows

Post-Migration (4 items)

[ ] Remove IKVM/JCOBridge runtime assemblies from the build output
[ ] Drop the JDK or JRE from CI agents if it was only there for the port
[ ] Slim Docker base images that previously included Java tooling
[ ] Update architecture diagrams (one fewer runtime to think about)

Where to Go From Here

The real migration here is runtime-to-runtime, not API-to-API. You are removing a Java-shaped surface, a bundled or bridged JVM, and the Java exception types and File objects that leak through any .NET PDFBox port. The dependency simplification is where the savings compound.

Worth knowing even without IronPDF: if you are pinned to an IKVM-based PDFBox port for compatibility reasons, IKVM's coverage of newer Java versions is limited. If you stay in .NET but want a free option, PdfPig handles text extraction and basic manipulation in pure C# under Apache 2.0, though it does not do HTML-to-PDF.

What is the most unusual PDFBox-port setup you have inherited? I have seen IKVM bindings, JCOBridge wrappers, a CLI shell-out, and even a scheduled job that polled a shared folder. Drop it in the comments if you have seen something even more unusual.

The free trial is on NuGet if you want to test before committing.

Moving from ActivePDF to IronPDF: Three Components to One

IronSoftware — Thu, 04 Jun 2026 16:53:22 +0000

Three separate ActivePDF NuGet packages. Three separate DLL references. Three separate licensing conversations with procurement. Your WebGrabber handles HTML conversion, Toolkit handles manipulation, and DocConverter handles everything else. None of them communicate cleanly, and all of them require Windows Server.

Then the Apryse acquisition happened, and now your support tickets route through a portal that looks nothing like the one your team bookmarked two years ago. The product still works. But the question every architect eventually asks is: do we really need three components for what is, fundamentally, one pipeline?

This guide walks you through consolidating ActivePDF into IronPDF, a single NuGet package that covers HTML-to-PDF, manipulation, merge, watermark, and security. Eighty percent of this content applies regardless of your target library. The other twenty percent shows the specific IronPDF API mappings. Use what is useful, ignore what is not.

Why Migrate

ActivePDF has served enterprise .NET shops for over a decade. Here is why teams re-evaluate:

Modular overhead. You buy and license Toolkit, WebGrabber, and DocConverter separately. Each has its own DLL, its own NuGet package, its own API surface. A single PDF generation workflow might touch all three.
Windows Server lock-in. ActivePDF components require Windows Server. If you are moving to Linux containers, Docker on ARM, or Azure App Service on Linux, ActivePDF does not follow you.
MSI installer dependencies. WebGrabber and DocConverter require MSI installation on the host, not just a NuGet restore. This breaks immutable infrastructure patterns and complicates CI/CD.
Acquisition uncertainty. Apryse acquired ActivePDF and merged support portals. The product roadmap, pricing, and long-term component strategy may shift toward Apryse's own PDFTron SDK.
IE-era rendering engine. WebGrabber historically offered Native and Internet Explorer rendering engines. Modern HTML5/CSS3 applications need a Chrome-class renderer.
API verbosity. Toolkit uses COM-style patterns inherited from its Classic ASP roots. Method names like SetMasterPassword and CopyForm work, but they are verbose compared to fluent property-based APIs.
Limited cross-platform path. Even though Toolkit's NuGet targets .NET Standard 1.0, the underlying native code and WebGrabber/DocConverter dependencies are Windows-only.
Separate HTML conversion path. If you need both HTML-to-PDF and PDF manipulation, you are calling WebGrabber to generate the PDF, then loading it into Toolkit to manipulate it. That is two separate APIs for one workflow.
DocConverter as a Windows service. DocConverter runs as a watched-folder service or COM automation host. In a microservices architecture, this model feels like a detour.
License complexity. Each ActivePDF component is licensed separately, often per-server. For teams scaling horizontally, the licensing math gets expensive.

Comparison Table

Aspect	ActivePDF (Toolkit + WebGrabber)	IronPDF
Focus	Modular: Toolkit = manipulation, WebGrabber = HTML-to-PDF	Unified: generation + manipulation in one package
Pricing	Per-component, per-server licensing	Per-developer, perpetual licenses available
API Style	COM-influenced methods, procedural	Fluent properties, C#-native patterns
Learning Curve	Medium, need to learn multiple component APIs	Low, single namespace, discoverable API
HTML Rendering	WebGrabber: Native and IE engines	Chrome rendering engine, modern web standards
Page Indexing	1-based in Toolkit (`-1` means "to end")	0-based page indices in most APIs
Thread Safety	Toolkit instances are stateful; serialize access per instance	`ChromePdfRenderer` is stateless, safe to share
Namespace	`APToolkitNET` / `APWebGrabber`	`IronPdf`

Migration Complexity Assessment

Effort by Feature

Feature	Complexity	Notes
HTML to PDF (from WebGrabber)	Low	Direct replacement; IronPDF eliminates the separate WebGrabber dependency
PDF manipulation (from Toolkit)	Medium	API shape differs; Toolkit's COM-style methods map to IronPDF properties
Merge	Low	`PdfDocument.Merge()` replaces Toolkit's merge methods
Split / extract pages	Low	IronPDF page indexer vs. Toolkit page operations
Watermark / stamping	Medium	Toolkit draws watermarks as page text per page; IronPDF uses HTML-based `ApplyWatermark`
Password / encryption	Low	Both support owner/user passwords; property names differ
Form filling	Medium	Toolkit has extensive form APIs; IronPDF uses `FormField` collection
Document conversion (300+ formats)	High / N/A	DocConverter has no direct IronPDF equivalent. Use IronPDF for HTML/URL; for Office to PDF, consider a dedicated converter
Print-to-PDF (Server)	N/A	No direct equivalent in IronPDF. Consider OS-level print drivers or alternative tools
Watched-folder automation (Meridian)	N/A	Architectural pattern, implement with FileSystemWatcher or message queues
Digital signatures	Medium	Different API surface; see the IronPDF digital signatures documentation

Decision Matrix

Scenario	Recommendation
HTML-to-PDF + basic manipulation, no DocConverter	Migrate. IronPDF unifies WebGrabber + Toolkit into one NuGet
Heavy DocConverter usage (Office, CAD conversions)	Partial migration. Use IronPDF for HTML/PDF ops, keep DocConverter or find a dedicated converter
Scaling to Linux / Docker / cross-platform	Migrate. ActivePDF is Windows-only
Deep Toolkit form automation	Evaluate IronPDF's form API coverage for your specific form workflows

Before You Start

Prerequisites

.NET 6+ (or .NET Framework 4.6.2+)
A trial or licensed IronPDF key
Inventory of which ActivePDF components your codebase uses

Find ActivePDF References

# Find all ActivePDF using statements and DLL references
rg -l "APToolkitNET|APWebGrabber|ActivePDF|APDocConverter" --glob "*.cs"

# Count Toolkit instantiations
rg -c "new Toolkit\(" --glob "*.cs"

# Find project/config references
rg -l "ActivePDF" --glob "*.csproj" --glob "*.config"

If you don't have rg:

grep -rl "APToolkitNET\|APWebGrabber\|ActivePDF" --include="*.cs" .

In PowerShell, Get-ChildItem -Recurse -Filter *.cs | Select-String "APToolkitNET|APWebGrabber|ActivePDF" covers the same ground.

Swap NuGet Packages

# Remove ActivePDF packages
dotnet remove package ActivePDF.Toolkit
dotnet remove package ActivePDF.WebGrabber  # if present as NuGet

# Install IronPDF (replaces both)
dotnet add package IronPdf

If WebGrabber or DocConverter were installed via MSI rather than NuGet, remove the DLL references from your .csproj manually and uninstall the MSI from your build/deploy hosts.

Quick Start Migration (3 Steps)

Step 1: License Configuration

Before (ActivePDF Toolkit):

// ActivePDF Toolkit licensing is handled by the installed product (per-server
// or per-core license file), not by a code-level API. From Toolkit 10 onward
// the native libraries also need to be discoverable - typically via the
// CoreLibPath constructor argument pointing at the install directory.
using APToolkitNET;
using System;

class Program
{
    static void Main()
    {
        using (Toolkit toolkit = new Toolkit(
            CoreLibPath: @"C:\Program Files\ActivePDF\Toolkit\bin"))
        {
            // Licensing comes from the installed ActivePDF license file.
            // Toolkit methods return integer status codes (0 = success).
            Console.WriteLine("ActivePDF Toolkit ready.");
        }
    }
}

After (IronPDF):

using IronPdf;

class Program
{
    static void Main()
    {
        // One line. Works in containers, CI, serverless.
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        Console.WriteLine($"IronPDF licensed: {License.IsLicensed}");
    }
}

Step 2: Namespace Imports

Before:

// ActivePDF - Toolkit and WebGrabber ship and license separately
using APToolkitNET;       // Toolkit: PDF manipulation
using APWebGrabber;       // WebGrabber: HTML-to-PDF / URL-to-PDF

After:

using IronPdf;
using IronPdf.Editing;    // watermarks, headers, footers
using IronPdf.Rendering;  // render options

Step 3: Basic HTML-to-PDF

Before (ActivePDF WebGrabber):

// WebGrabber renders from a URL or HTML file path, so HTML strings
// have to be written to a temp file first.
using APWebGrabber;
using System;
using System.IO;

class Program
{
    static void Main()
    {
        var wg = new WebGrabber();

        string html = @"
            <html><body>
                <h1>Invoice #1042</h1>
                <p>Amount: $5,200.00</p>
            </body></html>";

        string tempHtml = Path.Combine(Path.GetTempPath(), "input.html");
        File.WriteAllText(tempHtml, html);

        wg.URL = tempHtml;
        wg.OutputDirectory = Directory.GetCurrentDirectory();
        wg.OutputFilename = "invoice.pdf";

        // ConvertToPDF returns 0 on success.
        int result = wg.ConvertToPDF();
        Console.WriteLine(result == 0 ? "Saved with WebGrabber." : $"WebGrabber error: {result}");
    }
}

After (IronPDF):

using IronPdf;

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

        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.Letter;
        renderer.RenderingOptions.MarginTop = 12; // mm
        renderer.RenderingOptions.MarginBottom = 12;

        var pdf = renderer.RenderHtmlAsPdf(@"
            <html><body>
                <h1>Invoice #1042</h1>
                <p>Amount: $5,200.00</p>
            </body></html>");

        pdf.SaveAs("invoice.pdf");
        Console.WriteLine("Saved with IronPDF.");
    }
}

No output directory configuration. No status-code checking. No separate install. One NuGet, one renderer, one SaveAs. See the IronPDF HTML-to-PDF tutorial for URL-based and file-based rendering.

API Mapping Tables

Namespace Mapping

ActivePDF Namespace	IronPDF Namespace	Purpose
`APToolkitNET`	`IronPdf`	Document manipulation
`APWebGrabber`	`IronPdf`	HTML-to-PDF conversion
N/A (COM properties)	`IronPdf.Editing`	Watermarks, headers, footers

Core Class Mapping

ActivePDF Class	IronPDF Class	Description
`APToolkitNET.Toolkit`	`PdfDocument`	PDF loading, manipulation, saving
`APWebGrabber.WebGrabber`	`ChromePdfRenderer`	HTML/URL to PDF conversion
`DocConverter`	N/A (no direct equivalent)	300+ format conversion, use dedicated tools
Status code returns (int, `0` = success)	Standard .NET exceptions	Error handling pattern shift

Document Loading Methods

Operation	ActivePDF Toolkit	IronPDF
Open existing PDF	`toolkit.OpenInputFile("file.pdf")`	`PdfDocument.FromFile("file.pdf")`
Open with password	`toolkit.OpenInputFile("file.pdf", password: "pass")`	`PdfDocument.FromFile("file.pdf", "pass")`
Create from HTML	WebGrabber separate component	`renderer.RenderHtmlAsPdf(html)`
Create from URL	WebGrabber with `URL` property	`renderer.RenderUrlAsPdf("https://...")`

Page Operations

Operation	ActivePDF Toolkit	IronPDF
Get page count	`toolkit.NumPages` (property)	`pdf.PageCount`
Copy specific pages	`toolkit.CopyForm(startPage, endPage)`	`pdf.CopyPages(start, end)`
Add pages from another PDF	`toolkit.MergeFile(file, startPage, endPage)`	`PdfDocument.Merge(pdf1, pdf2)`
Delete pages	`toolkit.DeletePage(index)`	`pdf.RemovePages(index)`

Merge / Split Operations

Operation	ActivePDF Toolkit	IronPDF
Merge multiple PDFs	`OpenOutputFile` + loop `MergeFile(path, 1, -1)`	`PdfDocument.Merge(pdf1, pdf2, pdf3)`
Split by page range	`toolkit.CopyForm(start, end)`	`pdf.CopyPages(start, end)`

Four Complete Before/After Migrations

1. HTML to PDF

Before (ActivePDF WebGrabber):

using APWebGrabber;
using System;
using System.IO;

class HtmlToPdfActivePdf
{
    static void Main()
    {
        var wg = new WebGrabber();

        string html = @"
            <html>
            <head><style>
                body { font-family: 'Segoe UI', sans-serif; }
                .banner { background: #1a237e; color: #fff; padding: 24px; }
                .items { margin: 20px; }
                table { width: 100%; border-collapse: collapse; }
                td, th { padding: 10px; border-bottom: 1px solid #eee; }
            </style></head>
            <body>
                <div class='banner'><h1>Order Confirmation</h1></div>
                <div class='items'>
                    <table>
                        <tr><th>Item</th><th>Qty</th><th>Price</th></tr>
                        <tr><td>Widget Pro</td><td>5</td><td>$49.95</td></tr>
                        <tr><td>Gadget Lite</td><td>2</td><td>$19.99</td></tr>
                    </table>
                </div>
            </body>
            </html>";

        // WebGrabber takes a URL or file path; HTML strings go via a temp file.
        string tempHtml = Path.Combine(Path.GetTempPath(), "order.html");
        File.WriteAllText(tempHtml, html);

        wg.URL = tempHtml;
        wg.OutputDirectory = @"C:\output\";
        wg.OutputFilename = "order.pdf";
        wg.PageSize = APWebGrabber.Enums.PageSize.Letter;

        int result = wg.ConvertToPDF();
        Console.WriteLine(result == 0 ? "Success" : $"Error: {result}");
    }
}

After (IronPDF):

using IronPdf;

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

        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.Letter;
        renderer.RenderingOptions.PrintHtmlBackgrounds = true;
        renderer.RenderingOptions.CssMediaType = IronPdf.Rendering.PdfCssMediaType.Screen;

        var pdf = renderer.RenderHtmlAsPdf(@"
            <html>
            <head><style>
                body { font-family: 'Segoe UI', sans-serif; }
                .banner { background: #1a237e; color: #fff; padding: 24px; }
                .items { margin: 20px; }
                table { width: 100%; border-collapse: collapse; }
                td, th { padding: 10px; border-bottom: 1px solid #eee; }
            </style></head>
            <body>
                <div class='banner'><h1>Order Confirmation</h1></div>
                <div class='items'>
                    <table>
                        <tr><th>Item</th><th>Qty</th><th>Price</th></tr>
                        <tr><td>Widget Pro</td><td>5</td><td>$49.95</td></tr>
                        <tr><td>Gadget Lite</td><td>2</td><td>$19.99</td></tr>
                    </table>
                </div>
            </body>
            </html>");

        pdf.SaveAs("order.pdf");
        Console.WriteLine("Saved with IronPDF.");
    }
}

No output directory. No status code to check. No MSI prerequisite. The Chrome engine renders the CSS grid and background colors faithfully. See the IronPDF HTML-to-PDF tutorial for advanced rendering options.

2. Merge PDFs

Before (ActivePDF Toolkit):

using APToolkitNET;
using System;

class MergeActivePdf
{
    static void Main()
    {
        using (Toolkit toolkit = new Toolkit())
        {
            // Open the destination first, then merge each source file into it.
            int result = toolkit.OpenOutputFile(@"C:\output\merged.pdf");
            if (result != 0) { Console.WriteLine("Output error: " + result); return; }

            // MergeFile signature: MergeFile(FileName, StartPage, EndPage); -1 = "to end".
            result = toolkit.MergeFile(@"C:\input\part1.pdf", 1, -1);
            if (result != 0) { Console.WriteLine("Merge1 error: " + result); return; }

            result = toolkit.MergeFile(@"C:\input\part2.pdf", 1, -1);
            if (result != 0) { Console.WriteLine("Merge2 error: " + result); return; }

            toolkit.CloseOutputFile();
            Console.WriteLine("Merged with ActivePDF.");
        }
    }
}

After (IronPDF):

using IronPdf;

class MergeIronPdf
{
    static void Main()
    {
        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");
        Console.WriteLine("Merged with IronPDF.");
    }
}

The open-output, merge-file, close-output ceremony reduces to a single static call. See the IronPDF merge documentation.

3. Watermark

Before (ActivePDF Toolkit - drawn as page text per page):

using APToolkitNET;
using System;

class WatermarkActivePdf
{
    static void Main()
    {
        using (Toolkit toolkit = new Toolkit())
        {
            int result = toolkit.OpenOutputFile("watermarked.pdf");
            if (result != 0) return;

            toolkit.OpenInputFile("input.pdf");

            // Toolkit draws watermarks as page text per page using CopyForm + PrintText.
            int pageCount = toolkit.NumPages;
            for (int i = 1; i <= pageCount; i++)
            {
                toolkit.CopyForm(i, 0);
                toolkit.SetFont("Helvetica", 72);
                toolkit.SetTextColor(200, 200, 200);
                toolkit.PrintText(150, 400, "DRAFT");
            }

            toolkit.CloseInputFile();
            toolkit.CloseOutputFile();
            Console.WriteLine("Watermarked with ActivePDF.");
        }
    }
}

After (IronPDF):

using IronPdf;

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

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

        // HTML watermark - full CSS control, one call covers all pages.
        pdf.ApplyWatermark(
            "<h1 style='color:rgb(200,200,200);font-size:48px;font-family:Helvetica;'>DRAFT</h1>",
            rotation: 45,
            opacity: 50
        );

        pdf.SaveAs("watermarked.pdf");
        Console.WriteLine("Watermarked with IronPDF.");
    }
}

4. Password Protection

Before (ActivePDF Toolkit):

using APToolkitNET;
using System;

class PasswordActivePdf
{
    static void Main()
    {
        using (Toolkit toolkit = new Toolkit())
        {
            int result = toolkit.OpenOutputFile("protected.pdf");
            if (result != 0) return;

            toolkit.OpenInputFile("input.pdf");

            // Toolkit applies encryption via a single call.
            // Signature: SetEncryption(ownerPassword, userPassword, keyLength, permissions)
            toolkit.SetEncryption("owner123", "user456", 128, 0);

            toolkit.CopyForm(0, 0); // copy all pages into the encrypted output
            toolkit.CloseInputFile();
            toolkit.CloseOutputFile();
            Console.WriteLine("Protected with ActivePDF.");
        }
    }
}

After (IronPDF):

using IronPdf;

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

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

        pdf.SecuritySettings.OwnerPassword = "owner123";
        pdf.SecuritySettings.UserPassword = "user456";
        pdf.SecuritySettings.AllowUserPrinting = IronPdf.Security.PdfPrintSecurity.NoPrint;
        pdf.SecuritySettings.AllowUserCopyPasteContent = false;
        pdf.SecuritySettings.AllowUserEdits = IronPdf.Security.PdfEditSecurity.NoEdit;

        pdf.SaveAs("protected.pdf");
        Console.WriteLine("Protected with IronPDF.");
    }
}

No open-output/close-output dance. No separate input/output file streams. See IronPDF password protection documentation.

Critical Migration Notes

Status Codes to Exceptions

ActivePDF returns integer status codes from nearly every method (0 = success, non-zero = error). IronPDF throws exceptions on failure. Your error handling needs to shift from if (result != 0) checks to try/catch blocks:

// ActivePDF pattern
int result = toolkit.MergeFile("file.pdf", 1, -1); // 1 to -1 = all pages
if (result != 0) { /* handle error */ }

// IronPDF pattern
try
{
    var pdf = PdfDocument.FromFile("file.pdf");
}
catch (Exception ex)
{
    // handle error
}

Page Indexing Differences

ActivePDF Toolkit uses 1-based page numbering in most operations. IronPDF uses 0-based indexing. Audit every page reference in your code.

Input/Output File Pattern

ActivePDF Toolkit separates "open input" and "open output" into distinct calls. IronPDF loads a document and saves it. There is no separate output file concept. Any code that relies on the input/output split needs restructuring:

// ActivePDF pattern
toolkit.OpenOutputFile("output.pdf");
toolkit.OpenInputFile("input.pdf");
toolkit.CopyForm(1, -1); // copy all input pages into the output
toolkit.CloseInputFile();
toolkit.CloseOutputFile();

// IronPDF pattern
var pdf = PdfDocument.FromFile("input.pdf");
// ... manipulate ...
pdf.SaveAs("output.pdf");

Unit Conversion

ActivePDF WebGrabber's PageWidth / PageHeight properties are in points (612 x 792 = US Letter; 595 x 842 = A4). IronPDF expresses standard sizes through the PdfPaperSize enum and custom sizes through SetCustomPaperSizeInMillimeters / SetCustomPaperSizeInInches. Margins in IronPDF are millimeters, so if any of your existing configuration uses inches, multiply by 25.4 (for example, a 0.5 inch margin becomes MarginTop = 12.7 mm).

Performance Considerations

Eliminating the Component Hop

With ActivePDF, a typical HTML-to-manipulated-PDF workflow looks like: WebGrabber converts HTML, saves to disk, Toolkit opens the file, manipulates, then saves again. That is two disk round-trips and two component initializations.

IronPDF keeps everything in memory:

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html); // in-memory PdfDocument
pdf.ApplyWatermark("<h1>DRAFT</h1>");     // still in memory
pdf.SecuritySettings.UserPassword = "x";   // still in memory
pdf.SaveAs("final.pdf");                   // one write to disk

Renderer Reuse

ChromePdfRenderer is stateless. Create one and share it:

private static readonly ChromePdfRenderer _renderer = new ChromePdfRenderer();

Disposal

PdfDocument is IDisposable. In high-throughput services, wrap in using:

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

Edge Cases Worth Flagging

DocConverter replacement: If you depend on DocConverter for Office-to-PDF, IronPDF does not natively convert .docx or .xlsx to PDF. Consider pairing IronPDF with a library like IronWord or a dedicated conversion service. Alternatively, Puppeteer Sharp or LibreOffice headless can handle Office conversions.
Watched-folder patterns: If Meridian's watched-folder feature is part of your pipeline, replace it with a FileSystemWatcher + IronPDF processing loop. This gives you more control over error handling and retry logic.
Large batch processing: IronPDF supports Parallel.ForEach with a shared renderer instance. ActivePDF Toolkit instances are stateful, so concurrent code typically serializes access per instance or pools instances.

Migration Checklist

Pre-Migration (8 items)

[ ] Inventory which ActivePDF components are in use: Toolkit, WebGrabber, DocConverter, Meridian, Server
[ ] Run rg scan to find all ActivePDF references across the codebase
[ ] Identify DocConverter-dependent workflows that need alternative solutions
[ ] Obtain an IronPDF trial key from ironpdf.com/get-started/license-keys/
[ ] Create a migration branch
[ ] Document any WebGrabber MSI installation steps in deployment scripts
[ ] Identify all status-code error handling patterns that need try/catch conversion
[ ] List all 1-based Toolkit page-index references (and any uses of -1 for "to end") that need updating

Code Migration (10 items)

[ ] Remove all ActivePDF NuGet packages and DLL references
[ ] Uninstall WebGrabber / DocConverter MSIs from build servers (if applicable)
[ ] Add IronPdf NuGet package
[ ] Replace all namespace imports
[ ] Replace licensing calls with IronPdf.License.LicenseKey = "..."
[ ] Replace WebGrabber HTML-to-PDF with ChromePdfRenderer.RenderHtmlAsPdf()
[ ] Replace Toolkit open/copy/close patterns with PdfDocument.FromFile() + SaveAs()
[ ] Replace SetEncryption(...) with SecuritySettings properties
[ ] Replace status-code error handling with try/catch
[ ] Update Toolkit 1-based page indices and -1 "to end" sentinels for the new APIs

Testing (7 items)

[ ] Compare PDF output visually between ActivePDF and IronPDF for key templates
[ ] Test HTML rendering of your most complex CSS (grid, flexbox, web fonts)
[ ] Verify password protection open/save round-trip
[ ] Test merge with 5+ documents
[ ] Validate watermark rendering on multi-page documents
[ ] Run load tests with concurrent rendering
[ ] Test on Linux container if cross-platform is a goal

Post-Migration (4 items)

[ ] Remove WebGrabber/DocConverter MSI installation from deployment automation
[ ] Remove ActivePDF license files and server registrations
[ ] Update project documentation and architecture diagrams
[ ] Monitor production for two weeks, tracking PDF-related error rates

Final Thoughts

The biggest win in this migration is consolidation. Going from three separate components (WebGrabber + Toolkit + potentially DocConverter) to a single NuGet package simplifies your dependency tree, your licensing, and your deployment pipeline. The biggest risk is DocConverter: if you rely on Office-to-PDF conversion for 300+ formats, plan that replacement separately.

Worth knowing even without IronPDF: the ActivePDF Toolkit pattern of opening an output file, merging files into it, then closing is fragile. Forget to close and you get corrupted files. Any modern PDF library that uses an in-memory document model eliminates this class of bug.

What is the most obscure ActivePDF Toolkit method your codebase depends on? I am curious whether it is CopyForm with page-range offsets, some Meridian watched-folder hook, or maybe DocConverter's CAD-to-PDF pipeline. Let me know in the comments, those are the patterns that trip up real-world migrations.

The free trial is on NuGet if you want to test before committing.