DEV Community: IronSoftware

QuestPDF's $1M Cap: What Happens When You Outgrow It

IronSoftware — Mon, 08 Jun 2026 18:08:23 +0000

Disclosure: I'm on the team at Iron Software, which makes IronPDF.

The board-meeting moment

There is a particular meeting that happens at growing SaaS companies, usually in the second half of a year that has gone better than the founders expected. Revenue is on track to cross $1M. The board deck is polished. And somewhere on slide eleven, a finance lead mentions that one of the company's core dependencies is a PDF library called QuestPDF, and that the Community License the engineering team adopted four years ago at the seed stage no longer fits the company that has emerged.

This lays out the math you can run yourself rather than telling you which library to buy.

Many teams reach the moment described above. The architectural decision they are about to revisit is one they made under different conditions: smaller team, no revenue, optimistic timeline. The library they chose was, in many cases, QuestPDF. The conversation is happening not because QuestPDF did anything wrong. It is happening because the company grew.

That is a good problem to have. It is also a problem with a number on it.

What QuestPDF is, and why teams keep choosing it

Before the licensing math, the technical reality. QuestPDF deserves the credit it gets.

The library released version 2026.2.4 in March 2026, continuing a release cadence that has been remarkably consistent over multiple years. Total NuGet downloads sit above 21 million. The GitHub repository has more than 14,000 stars and an open-issue backlog that, while non-trivial, is being worked. By the standards of .NET PDF tooling, where some "free" libraries have not seen a meaningful commit in half a decade, QuestPDF is one of the most actively maintained options in its category.

The fluent API is the part most engineers fall in love with. It reads almost like a templating language inside C#. Defining a page, adding a header, composing a table, controlling page breaks: each operation is a chained method call. There is no XAML, no HTML rendering pipeline, no headless browser. The library runs as managed .NET code on whatever runtime your application targets, including current LTS releases such as .NET 8 (supported through November 2026) and .NET 10 (supported through November 2028, per Microsoft's official policy).

A sample of the kind of code an engineer writes against it:

using QuestPDF.Fluent;
using QuestPDF.Helpers;
using QuestPDF.Infrastructure;

QuestPDF.Settings.License = LicenseType.Community;

Document.Create(container =>
{
    container.Page(page =>
    {
        page.Size(PageSizes.A4);
        page.Margin(2, Unit.Centimetre);

        page.Header().Text("Q3 Customer Statement").FontSize(20).Bold();

        page.Content().Column(col =>
        {
            col.Item().Text("Prepared by Acme Corp, automated billing pipeline.");
            col.Item().PaddingTop(15).Text("Generated at: " + DateTime.UtcNow.ToString("u"));
        });

        page.Footer().AlignCenter().Text(t =>
        {
            t.Span("Page ");
            t.CurrentPageNumber();
            t.Span(" of ");
            t.TotalPages();
        });
    });
})
.GeneratePdf("statement.pdf");

Anyone who has tried to drive a PDF generator with imperative coordinates and cursor positions can feel the difference. Code like this is reviewable, testable, and something a backend engineer who is not a PDF specialist can pick up in an afternoon and ship by the end of the week.

That accessibility is the real reason QuestPDF caught on. The .NET ecosystem has had PDF libraries for two decades, but until QuestPDF, it did not have a free one whose API felt designed by someone who actually likes writing C#. The library's documentation is also unusually good for an open-source project: complete, organized, with worked examples for the layout primitives most teams will need.

QuestPDF is genuinely good. If your annual gross revenue is under $1M USD, QuestPDF is a defensible default and arguably the strongest free option in the .NET PDF space. The Community MIT License lets you ship it in a closed-source commercial product without ambiguity. The maintainer cadence is real. The API is good. There is no asterisk on this paragraph.

The asterisk lives on the next page of the same document.

The licensing model, in plain English

QuestPDF's published licensing model has three tiers. The thresholds and prices below are sourced from the project's own license documentation and pricing page as of May 2026.

Tier 1: Community MIT License (free). Available to open-source projects, charities, and educational use; transitive dependency consumption (you depend on a library that depends on QuestPDF); and companies with annual gross revenue under $1M USD.

Tier 2: Professional License ($999, perpetual, plus local tax, per QuestPDF's pricing page). Required when your company has crossed the $1M revenue threshold and has up to 10 developers using QuestPDF. The fee is one-time; the version you license remains valid forever, with one year of updates included and optional annual renewal at the same price for continued updates.

Tier 3: Enterprise License ($2,999, perpetual, plus local tax). Required when your company has crossed the $1M threshold and has more than 10 developers using QuestPDF (organization-wide, no per-seat counting). Same perpetual structure as Professional.

A note on the pricing model: this is a perpetual license, not a subscription. The version you pay for never stops working, even if you decline renewal. Most growing teams will renew anyway, because they want the security patches and feature updates that ship in subsequent releases, but the renewal is for updates, not for the right to keep running the library at all. Throughout the rest of this article, when we model "$999/year" or "$2,999/year" we mean the renewal cadence most teams will adopt, not a subscription that switches off if missed.

Now we have enough to model.

The hidden threshold: why QuestPDF isn't truly free for growing companies

The "Community" framing on QuestPDF's MIT tier is accurate as the maintainer has documented it, and the documentation is the cleanest in the .NET PDF ecosystem on the question. The framing is also, structurally, a soft trap for any company whose trajectory is "small now, growing." The license terms themselves are published openly; the trap lies in the cognitive shape of how teams adopt the library.

Three properties of QuestPDF's commercial gate are worth surfacing explicitly.

The threshold is self-attested. QuestPDF's license guide names the figure ($1M USD in annual gross revenue), names the currency, and ties the upgrade obligation to crossing that figure. There is no audit clause, no automated revenue probe, no trigger event the maintainer enforces from outside. The honor system is the system. That sounds permissive, and at the engineering level it is. At the legal level it means a company that crosses the threshold and does not upgrade is operating a commercial library outside its license terms, and the absence of an audit does not change that fact when the question reaches the company's legal department, an acquirer's due diligence, or a customer's vendor-risk review.

The threshold is binary, not graduated. There is no "between $1M and $10M" tier where the obligation is partial. A company at $999,999 in annual gross revenue owes nothing. A company at $1,000,001 owes the Professional or Enterprise fee in full. This is a perfectly defensible commercial design, but it means there is no early-warning phase: the obligation arrives on the day the financial reports cross the line, and most engineering teams hear about it after the fact, when finance is already preparing year-end statements.

The threshold is tied to the company, not to the project. Companies sometimes assume the $1M figure applies to revenue from the specific product using QuestPDF. It doesn't. The license measures total annual gross revenue of the licensee. A company whose QuestPDF-using product generates $50K but whose other lines of business produce $5M is over the threshold for QuestPDF licensing purposes.

The combined effect of these three properties is that "free" in QuestPDF's Community tier means "free until your company outgrows the tier, after which it is paid retroactively from the moment of crossing." For sub-threshold companies, this changes nothing. For companies on a growth curve, this is the fact the State C migration scenario below exists to model.

None of the above is a complaint about QuestPDF's commercial model. The model is reasonable and the threshold is generous by industry standards. The point is that the word "free" carries a temporal qualifier most adoption discussions do not name out loud.

The TCO model

Here is the question every engineering leader at a growing company should be able to answer in a sentence: what does the next five years of PDF generation cost?

For QuestPDF, the calculation has three states.

State A: Sub-threshold (revenue under $1M)

Year-1 cost: $0. Year-2 cost: $0. Integration time: whatever you would spend on any library; call it a week or two of one engineer.

This is genuinely free. The company that stays under $1M in annual gross revenue indefinitely owes QuestPDF nothing, ever. For lifestyle businesses, internal tools at non-revenue-generating organizations, side projects, and pre-revenue startups, this is the right answer. Use QuestPDF.

State B: Cross the threshold, license commercially

Year you cross $1M: license becomes mandatory. Up to 10 devs: $999/year. Beyond 10: $2,999/year. Five-year exposure for a small-team company: $4,995. Five-year exposure for an enterprise-license company: $14,995.

These are real numbers, but they are not scary numbers by enterprise-software standards. The Professional License at $999/year is roughly a mid-tier monitoring SaaS subscription. The Enterprise License at $2,999/year is below the noise floor for most engineering org budgets.

If your company crosses the revenue threshold and your engineering culture is comfortable with a quiet annual line item, this is the rational path. Pay the license. Keep using the library you already use.

State C: Cross the threshold, migrate away

This is the most expensive path, and a common one.

The pattern: a company adopted QuestPDF at the seed stage. Three years later, revenue is approaching $1M. Someone in finance flags the licensing terms during a vendor audit. The engineering team's first instinct is to evaluate alternatives rather than sign a license, partly cost-optimization reflex, partly accumulated frustration with one or two QuestPDF-shaped corners in the codebase, partly because nobody likes being told they have to buy something they used to get free.

The migration cost is where the model gets interesting. PDF generation is rarely an isolated module. By the time a company crosses the revenue threshold, the library is woven into report generation, customer statements, invoice rendering, contract output, signed audit trails, regulatory filings. A typical cross-section:

12 to 25 distinct PDF output paths in the codebase.
200 to 600 lines of fluent-API layout code per path, on average.
Test coverage tied to specific rendering output.
Visual-regression tests with checked-in reference PDFs.
Cross-team ownership: a generation library is rarely owned by one squad.

A realistic migration estimate for a company in this state: two to four engineer-months for the migration itself, plus one to two engineer-months for QA and visual regression. At a fully-loaded cost of around $15,000 per engineer-month (conservative for a US-based mid-level engineer), that is $45,000 to $90,000 in real spend, plus opportunity cost on roadmap features that did not get built during the migration window.

Compare that to a Professional License: $999 a year for ten years before the migration math breaks even. The Enterprise License: about fifteen years.

Migration only makes financial sense if you are moving to something that solves a problem the licensing fee does not, or if your migration target was always going to be necessary anyway because of feature requirements QuestPDF does not cover: HTML-to-PDF rendering, digital signatures, PDF/A archival output, accessibility tagging, OCR integration. For those workflows, the license fee is not the deciding number. The feature gap is.

The decision is not about quality

Nothing here says QuestPDF is bad. QuestPDF is technically excellent, the maintainer's commercial model is reasonable, and the price points are fair for what is offered.

The decision is about fit: what curve your company is on, what features you need, and how much engineering time you are willing to spend on a migration that buys nothing your users will see.

For the company under $1M in revenue, whose PDF needs are layout-focused and whose roadmap does not include the features QuestPDF has chosen not to build, the answer is QuestPDF. That answer is not even close. There is no commercial library at the same price.

For the company growing into the $1M boundary, whose PDF surface area is large and whose feature roadmap includes any of the items on the list above, the question worth asking before adopting any free PDF library is the one this piece opened with: what does the board meeting in year three look like?

If the answer makes you reach for a calculator, you have already done the analysis. The numbers will tell you the rest.

When your input is HTML, not C

QuestPDF builds documents from a C# layout API and deliberately does not render HTML. That is a clean model when the document originates in code, and an awkward one when the source of truth is an HTML or Razor template produced by a design team, an email system, or an existing web view, because reproducing that layout means rebuilding it by hand. Teams in that position, along with companies that have crossed QuestPDF's $1M revenue line and would rather buy a perpetual license with support than re-architect, usually want an HTML-first renderer. A commercial library can provide that. IronPDF, for example, takes an HTML string straight to PDF and renders Razor and Blazor components directly, keeping the template as the source of truth instead of porting it into layout code.

Has your team crossed QuestPDF's $1M line yet? Did you license, migrate, or rearchitect, and how did the numbers come out?

Try IronPDF free for 30 days, no credit card, no watermark: dotnet add package IronPdf

iText in .NET: 3 Legitimate Paths Before You dotnet add

IronSoftware — Mon, 08 Jun 2026 17:53:39 +0000

The moment of adoption

Picture the most ordinary version of this decision. A senior .NET developer, mid-sprint, needs PDF generation for a customer feature. They open a terminal, type dotnet add package itext7, watch NuGet resolve the dependency, and move on. No license dialog. No compliance prompt. No conversation with legal. The package installs, the code compiles, the feature ships. The license terms, a substantive document with substantive obligations, were technically agreed to at the moment of dotnet restore, but the act of agreeing was structurally invisible.

The point here is the difference between adopting a library and choosing one, rather than which library is better. For iText, those are not the same act, and the difference matters enough to be worth a deliberate look.

This article offers a framework. iText's licensing is publicly documented, technically clean, and defensible on the maintainer's terms. There are three legitimate paths a .NET team can take with it, and the goal is to make each path a chosen one rather than a discovered one.

What iText is, and what it has earned

Before any license analysis, the technical reality. A library nobody wants to use does not generate licensing conversations.

iText has been in continuous development since 1999, and is one of a small number of PDF SDKs whose feature coverage maps to substantially the full ISO PDF specification rather than a commercially convenient subset. The .NET port (itext on NuGet) reached version 9.6.0 in April 2026, with a public cadence that ships multiple minor versions per year. iText is owned by Apryse, which acquired the iText Group in April 2022 and rebranded from PDFTron in February 2023. The transition did not interrupt the engineering trajectory; the codebase has stayed healthy across two decades and a change of ownership.

What makes iText technically credible, and what most adopters are reaching for even if they could not articulate it at install time, is the depth of standards coverage. PDF/A archival profiles (A-1 through A-4) for record-retention compliance. PDF/UA accessibility tagging for regulated disclosures. ISO-32000-2 (PDF 2.0) features. Full digital-signature workflows including PAdES levels and PKCS11 hardware-token signing. Post-quantum signing primitives in the 9.5 release. Brotli-compressed streams, AES-256 encryption, XFA forms, page-level redaction with proper content-stream rewriting (genuinely hard to get right), OCR via the pdfOCR add-on, and a low-level object model that exposes essentially every node of the PDF tree.

That feature surface is uncommon. Regulated workflows in finance, life sciences, and the public sector require PDF/A archival output, digital signatures with timestamping, PDF/UA tagging, and audit-trail formats that map to specific ISO standards. The .NET ecosystem has many PDF libraries; the count whose feature breadth covers the full regulated-industry standards landscape is small, and iText sits at the top of it. When a team picks iText for a regulated-document workflow, the choice is rational on the technical merits, often the most rational technical choice available.

The maintainer's track record reinforces this. The iText 9 release timeline shows steady minor releases, with iText Core 9.6.0 the most recent at the time of writing. iText 8 reaches end-of-life in October 2026 per the iText Core 9.1 announcement, giving teams a clear migration runway. Release notes read like the changelog of a library taken seriously: appropriate bug-fix density, deprecation cycles communicated in advance, ISO standards work tracked publicly. The post-acquisition Apryse era has not slowed the cadence. By the standards of long-lived open-source projects, iText sits in the top decile on maintainership consistency.

The dual-license structure is itself a virtue worth naming. iText publishes the AGPL terms on its own site in plain English, explains the obligations in the maintainer's voice, and offers a clearly delineated commercial alternative. The posture is explicit, openly stated, and free of legalese, and it is consistently presented across iText's website, NuGet metadata, and source repositories. A team that wants to know what they are agreeing to can know in fifteen minutes of reading.

Legitimate use cases for iText AGPL are real and substantial. Open-source projects whose own license is AGPL-compatible can adopt iText with the obligations posing no marginal cost; the product is already open. Academic and reproducible-research workflows align naturally with source disclosure. Internal-only enterprise tools that are not network-deployed to external users sit outside §13's network-interaction trigger. Government and public-sector deployments where source transparency is itself a goal can choose AGPL deliberately. SaaS products explicitly built on AGPL-compatible terms are viable too; some companies treat source disclosure as a product feature rather than a constraint. None of these are workarounds; they are the use cases the maintainer designed the AGPL distribution to serve.

The commercial tier, in turn, is a reasonable professionally-supported path for teams whose deployment model does not align with AGPL. Customers receive warranted intellectual property, professional support and maintenance per the How to buy page, release from the AGPL obligations, and a contractual relationship with a commercial entity. The maintainer's business model is to monetize commercial use through this tier, and that model is defensible: it funds the engineering depth that produces the standards coverage. Without commercial revenue, the breadth of the open-source distribution would not exist on this scale.

The license, in iText's own words

iText is published under a dual-license model. The free distribution is licensed under the GNU Affero General Public License version 3. The paid distribution is licensed under one of Apryse's commercial agreements: a Volume-based subscription priced on the quantity of PDF files processed, or an OEM Distribution license with custom terms. Both ship the same technical capability; the difference is the licensing terms.

iText's AGPL documentation page describes the obligations in the maintainer's voice. Three statements, quoted verbatim:

"you must prominently mention iText and include the iText copyright and AGPL license in output file metadata, and also retain the producer line in every PDF that is created or manipulated using iText."

"You may not deploy it on a network without disclosing the full source code of your own applications under the AGPL license. You must distribute all source code, including your own product and web-based applications."

"It's a legal violation to use iText Core/Community and our open source add-ons in a non-AGPL environment."

Those statements come from the maintainer, not from a critic. The structural implication: iText's vendor explicitly characterizes use of the free distribution inside a closed-source product as outside the license's intended scope. Apryse intends the AGPL distribution as the deliberate-AGPL path and the commercial distribution as the closed-source-product path. Both are legitimate; the choice is the adopter's.

The legal mechanism behind the network-disclosure obligation is AGPL §13, quoted in full from the Free Software Foundation's canonical text:

"Notwithstanding any other provision of this License, if you modify the Program, your modified version must prominently offer all users interacting with it remotely through a computer network (if your version supports such interaction) an opportunity to receive the Corresponding Source of your version by providing access to the Corresponding Source from a network server at no charge, through some standard or customary means of facilitating copying of software."

§13 is what makes AGPL different from GPL. Standard GPL is triggered by distribution of the binary. AGPL adds a trigger for network interaction: a SaaS company that runs AGPL code on its own servers and never ships the binary is still inside §13's scope the moment a user interacts with the application over a network. The maintainer's plain-English summary is the same obligation expressed in product terms.

The implications are non-obvious to casual readers. A .NET team accustomed to MIT and Apache 2.0 dependencies, where the full set of obligations is "preserve the copyright notice," may model iText's license slot in a manifest as similar in shape. It is structurally different. That difference is what deserves the deliberate look.

The AGPL trap and what it costs closed-source teams

The AGPL framing in the maintainer's own documentation is the second move in a two-step history that most teams installing dotnet add package itext7 have not heard. The first move happened on December 1, 2009. Up to that date, iText shipped under the MPL/LGPL dual-license, a permissive arrangement that placed iText in the same risk category as MIT or Apache 2.0 dependencies. iText 2.1.7 was the last release under those terms. iText 5 and everything after it shipped under AGPL v3.

That switch is the moment "iText is free" stopped being a complete sentence. Every team running iText 5, 7, 8, or 9 in a closed-source product is now operating under a copyleft license whose §13 network-interaction clause is structurally incompatible with the SaaS deployment model most .NET teams default to. The maintainer's commercial license is the documented escape hatch. The trap, as it is often experienced, comes from the installation that bypassed the license entirely rather than from the license itself.

The pattern repeats often enough to be predictable. A team prototypes with iText AGPL. The prototype ships. Two years later, a SOC 2 reviewer, an acquisition due-diligence team, or an enterprise customer's security questionnaire flags iText in the SBOM and asks whether the company holds a commercial license. The answer is no, because nobody ever bought one. The team's three options at that moment are the same as Apryse intends: open-source the entire codebase (rarely feasible), purchase a commercial subscription on terms negotiated under time pressure, or migrate to a different library at the cost of weeks of engineering time the roadmap did not budget for.

There is nothing dishonest about iText's posture. The license terms are published clearly, the maintainer explains them in their own voice, and the AGPL distribution is itself a legitimate offering for teams whose deployment model fits. The trap is structural, not editorial. It exists because dotnet add package itext7 does not read a license file aloud, and because the version of "free" most developers carry in their head is closer to MIT than to AGPL. For closed-source commercial teams, the practical answer is to treat iText as a paid library by default and to engage Apryse sales before adoption rather than after the audit.

This is the case where "not recommended for commercial use" needs the qualifier "not recommended for closed-source commercial use without a commercial license." iText is unambiguously safe for AGPL-compatible projects and unambiguously expensive (in license fees, migration cost, or compliance exposure) for everything else.

What the commercial path actually looks like

Apryse does not publish a price card; the How to buy page directs interested customers to sales for both commercial offerings. The Volume-based subscription scales cost with usage, "based on the quantity of PDF files processed" per the maintainer's description. The transition from perpetual to subscription pricing happened on April 2, 2020, so any pricing comparison from before that date no longer applies. The OEM Distribution license is for vendors who embed iText in a shipped product; pricing is fully bespoke. Both tiers release the customer from AGPL obligations and provide professional support and maintenance.

The point about pricing is structural: cost-modeling for iText commercial requires a sales conversation. That is not a defect; it is consistent with a usage-shaped commercial model. It does mean the cost of Path B (below) cannot be modeled from public sources alone. A team considering iText commercial should engage Apryse sales early, scope the deployment honestly, and obtain a quote reflecting their actual usage profile before treating commercial-iText as a known-cost option. Engaging early in this context means what it means with any usage-priced enterprise vendor: an initial discovery conversation is normally free and does not commit either side to anything; an honest scope discussion of expected document volumes, deployment footprint, and any standards-coverage features the workload depends on costs nothing beyond the meeting time; and the resulting written quote is something the team can take into the build-vs-buy review without obligation. None of those steps commits a team to licensing; they exist so the team can model Path B accurately before the decision is in front of the budget owner.

The three legitimate paths

For a .NET team standing at the moment of dotnet add package itext7, three paths are legitimate, and the right one depends on the team's situation.

Path A: Adopt iText AGPL deliberately

For teams whose deployment context aligns with AGPL's obligations: open-source projects whose own license is AGPL-compatible, academic and reproducible-science workflows, internal-only enterprise tools that never expose iText-using code to external network users, government and public-sector projects where source disclosure aligns with mission, and SaaS products explicitly built on AGPL-compatible terms.

Criterion: the team has read AGPL §13, confirmed with counsel that the deployment model meets the obligations, and is choosing AGPL because it fits, not because it was the default at install time. Cost: ongoing engineering discipline around attribution and source-disclosure obligations. Benefit: zero license fee for a feature surface that would otherwise be expensive.

Path B: Adopt iText commercial

For teams who need iText's specific feature set (PDF/A breadth, PAdES signing, PDF/UA tagging, advanced redaction, OCR) inside a closed-source commercial product. The commercial license is the professionally-supported channel for using iText in a closed-source context.

Criterion: the team needs coverage that iText offers and a non-iText alternative does not (or does not at acceptable engineering cost), and the deployment model is closed-source commercial. Cost: the commercial subscription, scaling with usage. Benefit: full feature surface with warranted IP, professional support, and a contractual counterparty for procurement. For SaaS deployments at scale, the line item is real and grows with the business; the implication is to engage sales early and model the cost honestly against the value the feature surface delivers, before the team has architected itself into a position where switching libraries would be expensive.

Path C: Use a different library

For teams whose required feature set does not justify the iText commercial cost, or whose licensing posture is permissive-only (MIT, Apache 2.0) by policy. The .NET PDF ecosystem includes multiple legitimate alternatives across MIT-licensed open-source, permissively-licensed commercial, and free-for-commercial-use options. Path C means deliberately choosing a library whose license posture matches the team's deployment model when neither iText path fits, without prescribing a single product.

Criterion: the feature set the team actually needs is achievable on a non-iText library at acceptable engineering investment, and the team's licensing posture is misaligned with AGPL. Cost: the engineering work to evaluate alternatives and possibly accept a feature gap. Benefit: a license slot in the dependency manifest that does not require a sales conversation or an AGPL §13 reading to defend.

Closing

The moment we opened with (a developer typing dotnet add package itext7, NuGet resolving, the feature shipping) deserves a deliberate answer from your team, not a default one. iText is a technically excellent library with a clearly documented dual-license structure, and either path within iText is legitimate when chosen on its merits: AGPL with intent, or commercial with contract. So is the third path, of using a different library when neither iText path fits. What is not legitimate is the unchosen path: an AGPL dependency inside a closed-source commercial product, adopted as a side-effect of dotnet add and never modeled against the obligations the maintainer has documented in plain English on its own website. That posture is the one this framework exists to make harder to fall into by default.

The deliberate read takes an afternoon. The implications of skipping it can compound for years.

If AGPL doesn't fit: a commercial alternative

iText is free under AGPL v3, and that license is the catch. Ship it inside a closed-source product or a hosted service and the network-use clause obliges you to either release your source or buy iText's commercial license. A solo developer or small SaaS that cannot open-source its codebase, and an enterprise that needs contractual indemnity rather than a copyleft obligation, both run into that wall.

IronPDF, a commercial library, covers the same advanced surface (forms, signatures, PDF/A) under a one-off license with no copyleft, so a closed-source release raises no AGPL question.

It can apply digital signatures and the rest of that surface from licensed code that never triggers source disclosure. A commercial-library workflow looks like this:

// Install: dotnet add package IronPdf
using IronPdf;

// A commercial key: no copyleft, no AGPL source-disclosure obligation
IronPdf.License.LicenseKey = "YOUR-TRIAL-OR-LICENSE-KEY";

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Closed-source and compliant</h1>");
pdf.SaveAs("document.pdf");

Pro: a permissive commercial license with no copyleft, where iText's free tier is AGPL.
Pro: a free 30-day trial, no credit card, and no watermark while you evaluate.
Con: a paid license from first use, where iText's AGPL distribution is free for open-source projects.

If AGPL exposure is the blocker, the trial key arrives by email with no card so you can validate a closed-source build first. For AGPL-compatible or open-source projects, iText remains the deeper, standards-complete choice.

Have you been caught by iText's AGPL terms in a closed-source product, or did you adopt it deliberately? How did the license question play out for your team?

License terms, version numbers, and quoted text in this article were verified against publicly available sources in May 2026; AGPL §13 is quoted from the Free Software Foundation's canonical license text.

Try IronPDF free for 30 days, no credit card, no watermark: dotnet add package IronPdf

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.

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.

Moving from ABCpdf to IronPDF: What I Learned

IronSoftware — Thu, 04 Jun 2026 16:45:46 +0000

Your ABCpdf Doc object just swallowed a 47-page HTML invoice and spat out a blank PDF. Again. The bundled Chromium engine you pinned eighteen months ago is now several Chromium majors behind upstream, and the CSS grid you shipped last sprint renders as a single column. You could pin a newer ABCChrome runtime, patch the HTML, or file another ticket. Or you could migrate.

This guide walks you through replacing ABCpdf with IronPDF in a .NET codebase. Eighty percent of what follows is general migration knowledge (dependency auditing, API surface mapping, testing strategy) that applies even if you pick a different target library. The remaining twenty percent is where IronPDF specifically cuts the boilerplate. Copy-paste the code, run the checklist, and ship.

Why Migrate

Nobody migrates a working PDF pipeline for fun. Here are the concrete triggers that push teams to evaluate alternatives:

HTML engine version churn. ABCpdf bundles multiple Chromium forks ("ABCChrome") and exposes them through EngineType.Chrome123, Chrome117, Chrome86, and Chrome65. The default in v13 is Chrome123, but pinning to an older engine to keep behavior stable means you fall behind on CSS features supported by modern browsers.
Native runtime deployment. ABCpdf requires platform-specific native binaries alongside the managed assembly. On Linux this means pulling the ABCpdf.ABCChrome117.Linux or ABCpdf.ABCChrome123.Linux runtime packages. Docker builds, Azure App Services, and CI agents all need these resolved correctly.
License file mechanics. ABCpdf uses license keys that historically lived in the registry or in XSettings-style installation calls. Cloud-first deployments, especially ephemeral containers, fight with this model.
API verbosity for common tasks. Generating a PDF from HTML in ABCpdf requires creating a Doc, calling Doc.AddImageHtml(), sometimes chaining additional pages, then calling doc.Save() and doc.Clear(). That is a lot of ceremony for "turn this HTML into a file."
Page coordinate system. ABCpdf uses a bottom-left origin with point-based coordinates. If your team thinks in pixels or CSS units, every measurement needs manual conversion.
Thread safety caveats. ABCpdf Doc objects are not designed to be shared across threads. High-throughput services need careful pooling or per-request instantiation, and it is easy to get wrong under load.
Cross-platform gaps. Linux support arrived in v13, but some features (XPS, WPF rendering) remain Windows-only. macOS is not supported at all. If your deployment matrix spans operating systems, you carry conditional code.
Font embedding complexity. Getting CJK or custom web fonts to render correctly often requires manual font installation on the server, plus explicit configuration in ABCpdf's rendering options.
No built-in Razor or template integration. If your .NET app uses Razor views, you must pre-render them to HTML strings yourself before passing to ABCpdf.
Upgrade friction between major versions. Namespace and assembly names change between major versions (e.g., WebSupergoo.ABCpdf12 to WebSupergoo.ABCpdf13). Every major upgrade is a mini-migration anyway.

Comparison Table

Aspect	ABCpdf	IronPDF
Focus	Full PDF manipulation with multiple HTML engines	HTML-first PDF generation and manipulation
Pricing	Tiered: Standard $329 (32-bit), Professional $479, Enterprise $4,790, Group $33,530	Per-developer, perpetual licenses available
API Style	Imperative `Doc` object, manual page chaining	Fluent renderer, one-call HTML-to-PDF
Learning Curve	Moderate, coordinate system and chaining take time	Low, HTML/CSS developers productive in minutes
HTML Rendering	Multiple Chromium versions (Chrome123/117/86/65), Gecko, WebKit, MSHtml	Built-in Chromium rendering engine
Page Indexing	1-based	0-based
Thread Safety	`Doc` not designed for shared use, manual pooling required	`ChromePdfRenderer` reusable across requests
Namespace	`WebSupergoo.ABCpdf13`	`IronPdf`

Migration Complexity Assessment

Effort by Feature

Feature	Complexity	Notes
HTML to PDF	Low	Direct replacement, IronPDF handles pagination automatically
URL to PDF	Low	`RenderUrlAsPdf` replaces `AddImageUrl`
Merge	Low	`PdfDocument.Merge()` is a one-liner
Split / extract pages	Low	Page range copy via `CopyPages`
Watermark	Medium	ABCpdf uses `Doc.AddText` at coordinates, IronPDF uses `ApplyWatermark` with HTML
Password / encryption	Low	Property-based in both, IronPDF uses `SecuritySettings`
Digital signatures	Medium	Different API surface, consult the IronPDF signing docs
Form filling	Medium	ABCpdf uses field atoms, IronPDF uses a `FormField` collection
PDF/A compliance	Medium-High	ABCpdf has long-standing PDF/A export, IronPDF supports PDF/A export as well
Text extraction	Low	Both offer text extraction, API shape differs
Accessibility tagging	High	ABCpdf 13 has mature auto-tagging, evaluate IronPDF coverage against your requirements

Decision Matrix

Scenario	Recommendation
HTML-heavy generation, minimal low-level manipulation	Migrate, IronPDF's one-call renderer saves significant code
Heavy PDF/A and accessibility tagging workflows	Evaluate carefully, ABCpdf 13's tagging is mature
Docker / Linux-first deployment	Migrate, IronPDF's single NuGet, no separate native runtime package
Existing large ABCpdf codebase with coordinate-based drawing	Phased migration, wrap new features in IronPDF, legacy in ABCpdf

Before You Start

Prerequisites

.NET 6+ (or .NET Framework 4.6.2+)
A trial or licensed IronPDF key
Access to your CI pipeline configuration

Find ABCpdf References

Use rg (ripgrep) to locate every ABCpdf touchpoint:

# Find all ABCpdf using statements and references
rg -l "WebSupergoo|ABCpdf|XSettings|Doc\.Add" --glob "*.cs"

# Count occurrences for effort estimation
rg -c "new Doc\(\)" --glob "*.cs"

# Find project file references
rg -l "ABCpdf" --glob "*.csproj"

If you do not have rg, the grep equivalent:

grep -rl "WebSupergoo\|ABCpdf\|XSettings" --include="*.cs" .

In PowerShell, Get-ChildItem -Recurse -Filter *.cs | Select-String -Pattern "WebSupergoo|ABCpdf" achieves the same result.

Swap NuGet Packages

# Remove ABCpdf
dotnet remove package ABCpdf

# Install IronPDF
dotnet add package IronPdf

Quick Start Migration (3 Steps)

Step 1: License Configuration

Before (ABCpdf):

using WebSupergoo.ABCpdf13;

class Program
{
    static void Main()
    {
        // ABCpdf license -- installed via XSettings or registry
        XSettings.InstallLicense("YOUR-ABCPDF-KEY");
        Console.WriteLine("ABCpdf license installed.");
    }
}

After (IronPDF):

using IronPdf;

class Program
{
    static void Main()
    {
        // IronPDF license -- one line, works in containers
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

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

Step 2: Namespace Imports

Before:

using WebSupergoo.ABCpdf13;
using WebSupergoo.ABCpdf13.Objects;

After:

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

Step 3: Basic HTML-to-PDF

Before (ABCpdf, verbose Doc lifecycle):

using WebSupergoo.ABCpdf13;
using WebSupergoo.ABCpdf13.Objects;
using System;

class Program
{
    static void Main()
    {
        XSettings.InstallLicense("YOUR-ABCPDF-KEY");

        Doc doc = new Doc();
        doc.HtmlOptions.Engine = EngineType.Chrome123;
        doc.Rect.Inset(20, 20);

        doc.AddImageHtml("<h1>Invoice</h1><p>Hello from ABCpdf</p>");
        doc.Save("invoice.pdf");
        doc.Clear(); // manual cleanup required
    }
}

After (IronPDF):

using IronPdf;

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

        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.CssMediaType = IronPdf.Rendering.PdfCssMediaType.Screen;
        renderer.RenderingOptions.MarginTop = 20;
        renderer.RenderingOptions.MarginBottom = 20;

        var pdf = renderer.RenderHtmlAsPdf("<h1>Invoice</h1><p>Hello from IronPDF</p>");
        pdf.SaveAs("invoice.pdf");
        // no Clear() needed, IDisposable handles cleanup via using blocks
    }
}

The manual Doc.Clear() and the engine selection step are gone. IronPDF paginates multi-page HTML automatically.

API Mapping Tables

Namespace Mapping

ABCpdf Namespace	IronPDF Namespace	Purpose
`WebSupergoo.ABCpdf13`	`IronPdf`	Core classes
`WebSupergoo.ABCpdf13.Objects`	`IronPdf.Editing`	Document manipulation
`WebSupergoo.ABCpdf13.Atoms`	`IronPdf.Rendering`	Render options, low-level types

Core Class Mapping

ABCpdf Class	IronPDF Class	Description
`Doc`	`ChromePdfRenderer` + `PdfDocument`	ABCpdf combines rendering and document in one object, IronPDF separates them
`XSettings`	`IronPdf.License`	Licensing configuration
`HtmlOptions` / `EngineType`	`ChromePdfRenderOptions`	HTML rendering configuration
`Rect`	`RenderingOptions.MarginTop` etc.	Page area / margin control

Document Loading Methods

Operation	ABCpdf	IronPDF
Load from file	`new Doc(); doc.Read("file.pdf")`	`PdfDocument.FromFile("file.pdf")`
Load from bytes	`doc.Read(byteArray)`	`PdfDocument.FromBinaryData(byteArray)`
Load from stream	`doc.Read(stream)`	`PdfDocument.FromStream(stream)`
Load password-protected	`new Doc("file.pdf", "pass")`	`PdfDocument.FromFile("file.pdf", "pass")`

Page Operations

Operation	ABCpdf	IronPDF
Get page count	`doc.PageCount`	`pdf.PageCount`
Navigate to page	`doc.Page = n` (1-based)	`pdf.Pages[n]` (0-based)
Add blank page	`doc.AddPage()`	Render HTML with empty content, or copy from template
Delete page	`doc.Delete(pageId)`	`pdf.RemovePages(index)`

Merge / Split Operations

Operation	ABCpdf	IronPDF
Merge documents	`doc.Append(otherDoc)`	`PdfDocument.Merge(pdf1, pdf2)`
Extract page range	Manual page copy loop	`pdf.CopyPages(startIndex, endIndex)`

Four Complete Before/After Migrations

1. HTML to PDF

Before (ABCpdf):

using WebSupergoo.ABCpdf13;
using WebSupergoo.ABCpdf13.Objects;
using System;

class HtmlToPdfAbcpdf
{
    static void Main()
    {
        XSettings.InstallLicense("YOUR-ABCPDF-KEY");

        Doc doc = new Doc();
        doc.HtmlOptions.Engine = EngineType.Chrome123;
        doc.HtmlOptions.BrowserWidth = 1280;
        doc.Rect.Inset(30, 30);

        string html = @"
            <html>
            <head><style>
                body { font-family: Arial; }
                .header { background: #2c3e50; color: white; padding: 20px; }
                table { width: 100%; border-collapse: collapse; }
                td, th { border: 1px solid #ddd; padding: 8px; }
            </style></head>
            <body>
                <div class='header'><h1>Monthly Report</h1></div>
                <table>
                    <tr><th>Metric</th><th>Value</th></tr>
                    <tr><td>Revenue</td><td>$142,000</td></tr>
                    <tr><td>Users</td><td>8,421</td></tr>
                </table>
            </body>
            </html>";

        doc.AddImageHtml(html);
        doc.Save("report_abcpdf.pdf");
        doc.Clear();
        Console.WriteLine("Saved with ABCpdf.");
    }
}

After (IronPDF):

using IronPdf;

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

        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.CssMediaType = IronPdf.Rendering.PdfCssMediaType.Screen;
        renderer.RenderingOptions.PrintHtmlBackgrounds = true; // preserve CSS backgrounds
        renderer.RenderingOptions.MarginTop = 30;
        renderer.RenderingOptions.MarginBottom = 30;
        renderer.RenderingOptions.ViewPortWidth = 1280;

        string html = @"
            <html>
            <head><style>
                body { font-family: Arial; }
                .header { background: #2c3e50; color: white; padding: 20px; }
                table { width: 100%; border-collapse: collapse; }
                td, th { border: 1px solid #ddd; padding: 8px; }
            </style></head>
            <body>
                <div class='header'><h1>Monthly Report</h1></div>
                <table>
                    <tr><th>Metric</th><th>Value</th></tr>
                    <tr><td>Revenue</td><td>$142,000</td></tr>
                    <tr><td>Users</td><td>8,421</td></tr>
                </table>
            </body>
            </html>";

        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("report_ironpdf.pdf");
        Console.WriteLine("Saved with IronPDF.");
    }
}

PrintHtmlBackgrounds = true is what preserves the dark header background you set in CSS. ABCpdf rendered that by default. ViewPortWidth maps directly to ABCpdf's BrowserWidth. The IronPDF HTML-to-PDF tutorial covers the full rendering options including JavaScript wait conditions and custom headers.

2. Merge PDFs

Before (ABCpdf):

using WebSupergoo.ABCpdf13;
using System;

class MergeAbcpdf
{
    static void Main()
    {
        XSettings.InstallLicense("YOUR-ABCPDF-KEY");

        Doc doc1 = new Doc();
        doc1.Read("part1.pdf");

        Doc doc2 = new Doc();
        doc2.Read("part2.pdf");

        doc1.Append(doc2); // mutates doc1 in place
        doc1.Save("merged_abcpdf.pdf");
        doc1.Clear();
        doc2.Clear();
        Console.WriteLine("Merged with ABCpdf.");
    }
}

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");

        // Static merge -- returns a new PdfDocument, inputs are unchanged
        var merged = PdfDocument.Merge(pdf1, pdf2);
        merged.SaveAs("merged_ironpdf.pdf");
        Console.WriteLine("Merged with IronPDF.");
    }
}

PdfDocument.Merge() accepts params PdfDocument[], so you can pass any number of documents in one call. The merge and split documentation has patterns for merging 5+ documents and combining generated PDFs with file-based ones.

3. Watermark

Before (ABCpdf):

using WebSupergoo.ABCpdf13;
using System;

class WatermarkAbcpdf
{
    static void Main()
    {
        XSettings.InstallLicense("YOUR-ABCPDF-KEY");

        Doc doc = new Doc();
        doc.Read("input.pdf");

        // Apply text watermark to each page -- manual coordinate loop
        for (int i = 1; i <= doc.PageCount; i++)
        {
            doc.Page = i;
            doc.Color.String = "200 200 200"; // light gray
            doc.Font = doc.AddFont("Helvetica");
            doc.FontSize = 48;
            doc.Rect.SetRect(100, 300, 400, 100);
            doc.AddText("CONFIDENTIAL");
        }

        doc.Save("watermarked_abcpdf.pdf");
        doc.Clear();
        Console.WriteLine("Watermarked with ABCpdf.");
    }
}

After (IronPDF):

using IronPdf;

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

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

        // HTML watermark -- use any CSS, no coordinate math, applies to all pages
        pdf.ApplyWatermark(
            "<h1 style='color:lightgray;font-size:48px;opacity:0.5;'>CONFIDENTIAL</h1>",
            rotation: 45,
            hyperlink: null
        );

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

The coordinate math and per-page loop collapse into a single ApplyWatermark call. Position control via VerticalAlignment and HorizontalAlignment enums in IronPdf.Editing is covered in the watermark alignment docs.

4. Password Protection

Before (ABCpdf):

using WebSupergoo.ABCpdf13;
using System;

class PasswordAbcpdf
{
    static void Main()
    {
        XSettings.InstallLicense("YOUR-ABCPDF-KEY");

        Doc doc = new Doc();
        doc.Read("input.pdf");

        doc.Encryption.Type = EncryptionType.AES128;
        doc.Encryption.Password = "user456";
        doc.Encryption.CanPrint = false;
        doc.Encryption.CanCopy = false;
        doc.Encryption.CanEdit = false;

        doc.Save("protected_abcpdf.pdf");
        doc.Clear();
        Console.WriteLine("Protected with ABCpdf.");
    }
}

After (IronPDF):

using IronPdf;

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

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

        // Named properties, no integer flags to look up
        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_ironpdf.pdf");
        Console.WriteLine("Protected with IronPDF.");
    }
}

IronPDF uses typed enums instead of integer flags. The full SecuritySettings surface is in the PDF permissions and passwords docs.

Critical Migration Notes

Page Indexing Differences

ABCpdf uses 1-based page numbering (doc.Page = 1 is the first page). IronPDF uses 0-based indexing (pdf.Pages[0] is the first page). Every loop, every page reference, every index needs adjusting. A quick rg "doc\.Page\s*=" --glob "*.cs" will find them all.

Doc Object vs. Separate Renderer and Document

ABCpdf's Doc is both the renderer and the document. IronPDF separates these: ChromePdfRenderer handles creation, PdfDocument handles the result. If your ABCpdf code passes doc around for both rendering and manipulation, you will need to refactor call sites to accept the appropriate type.

Unit Conversion

ABCpdf works in PDF points (1 point = 1/72 inch) with a bottom-left origin. IronPDF margins are specified in millimeters by default. If you have hard-coded coordinate values, convert them: 1 point = 0.353 mm.

Disposal Patterns

ABCpdf required an explicit doc.Clear() to release resources. IronPDF's PdfDocument is IDisposable, so a standard using block handles cleanup. Drop the Clear() call and wrap with using when migrating each site.

Performance Considerations

Renderer Reuse

In ABCpdf, you create a new Doc per render. In IronPDF, ChromePdfRenderer is meant to be created once and shared across requests:

// Create once, share across all requests
private static readonly ChromePdfRenderer _renderer = new ChromePdfRenderer();

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

Disposal

Always dispose PdfDocument instances when done. In high-throughput services, this matters:

using var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");
// pdf is disposed here

For async patterns in concurrent workloads, the Microsoft async programming docs cover Task.WhenAll and ConfigureAwait(false) usage that applies when batching PDF generation.

Edge Cases Worth Flagging

Large HTML tables (1000+ rows): Both libraries handle these, but consider paginating in HTML with page-break-before: always for predictable output.
JavaScript-dependent rendering: IronPDF's Chrome engine executes JS by default. If your HTML relies on JS to build the DOM, leave renderer.RenderingOptions.EnableJavaScript = true and consider adding a RenderDelay if content loads asynchronously.
Concurrent rendering: IronPDF's ChromePdfRenderer is designed for reuse across requests. For batch jobs, Parallel.ForEach with the same renderer instance works. ABCpdf typically required explicit Doc-per-thread isolation.

Migration Checklist

Pre-Migration (8 items)

[ ] Run rg scan to inventory all ABCpdf usage across the codebase
[ ] Catalog which ABCpdf features you actually use (HTML-to-PDF, merge, forms, etc.)
[ ] Obtain an IronPDF trial key from ironpdf.com/get-started/license-keys/
[ ] Create a migration branch in source control
[ ] Identify integration tests that exercise PDF generation paths
[ ] Document any ABCpdf coordinate-based drawing code that needs rethinking
[ ] Check for ABCpdf license files or registry entries in deployment scripts
[ ] Review Docker / CI configurations for native runtime package copy steps

Code Migration (10 items)

[ ] Replace NuGet package: remove ABCpdf, add IronPdf
[ ] Update all using directives from WebSupergoo.ABCpdf* to IronPdf
[ ] Replace XSettings.InstallLicense() with IronPdf.License.LicenseKey = "..."
[ ] Replace Doc + AddImageHtml with ChromePdfRenderer.RenderHtmlAsPdf()
[ ] Replace Doc.Append() with PdfDocument.Merge()
[ ] Replace coordinate-based watermarks with ApplyWatermark() HTML
[ ] Replace encryption integer flags with SecuritySettings properties
[ ] Convert all 1-based page indices to 0-based
[ ] Convert point-based margins to millimeters
[ ] Replace doc.Clear() calls with using blocks

Testing (7 items)

[ ] Run existing PDF output tests and compare visually
[ ] Verify multi-page HTML renders without manual chaining
[ ] Test password-protected PDF open/save round-trip
[ ] Test merge with 3+ documents
[ ] Validate watermark positioning on single-page and multi-page docs
[ ] Load-test concurrent rendering in staging
[ ] Verify Docker/Linux deployment produces identical output

Post-Migration (4 items)

[ ] Remove ABCpdf native runtime packages from deployment artifacts
[ ] Remove ABCpdf license registry entries or file deployment steps
[ ] Update project documentation and onboarding guides
[ ] Monitor production error rates for PDF-related exceptions for two weeks

Conclusion

The hardest part of this migration is not the API mapping. It is the coordinate-system shift and the engine-version cleanup. If your codebase is mostly HTML-to-PDF with straightforward merge and security, expect a one-to-two day migration for a mid-size project. If you have heavy coordinate-based drawing or accessibility tagging, plan for a phased approach.

Worth knowing even without IronPDF: pinning an HTML engine to a specific Chromium major (ABCpdf's Chrome117, Chrome86, etc.) is a common source of "renders fine in the browser, renders wrong in the PDF" bugs. Any modern HTML-to-PDF library that tracks a single, current Chromium internally eliminates that class of bug entirely.

Have you hit an edge case migrating from ABCpdf that is not covered here? Maybe around ABCpdf's ContentStreamScanner, custom atom manipulation, or 3D PDF rendering. Drop it in the comments. Those are the patterns that are hardest to Google and most useful to document.

The free trial is on NuGet if you want to test the migration against your actual templates before committing.

TuesPechkin vs IronPDF: side by side for .NET teams in 2026

IronSoftware — Mon, 25 May 2026 14:52:00 +0000

IronPDF is a commercial .NET library using a modern Chromium rendering engine — the same technology powering Chrome and Edge. Rather than wrapping a decade-old WebKit fork, it renders HTML/CSS/JavaScript the way current browsers display content. Install via NuGet (IronPdf), no separate binary downloads required, and it targets Windows, Linux, macOS, Docker, and Azure.

The core API centers on ChromePdfRenderer with methods like RenderHtmlAsPdf() for strings, RenderUrlAsPdf() for live sites, and RenderHtmlFileAsPdf() for local templates. It handles CSS Grid, Flexbox, Web Fonts, SVG, and JavaScript execution out of the box, making it suitable for modern SaaS reporting, invoice systems, and document automation.

Where TuesPechkin Fits

Product Status

TuesPechkin is a .NET wrapper around the wkhtmltopdf native binary, distributed via the TuesPechkin NuGet package paired with TuesPechkin.Wkhtmltox.Win64 or TuesPechkin.Wkhtmltox.Win32 for the platform-specific binary. The underlying wkhtmltopdf project — built on a WebKit fork from roughly 2015 — has been archived upstream and is no longer receiving active development. Teams adopting it today inherit a dependency chain that predates modern .NET and modern web standards.

Capability Gaps

Limited modern CSS: CSS Grid and newer Flexbox features can render incorrectly — verify against your version
Constrained JavaScript execution: Complex SPAs or dynamic content may not render as expected
Pre-async API surface: Originally targeted .NET Framework, lacks async/await patterns
Manual container setup: Native library management is typically required in Docker images

Operational Constraints

Resident native binary: The wkhtmltox native library stays resident in the host process after conversions, which can matter for long-running web workers
Thread safety pattern: Typically requires a singleton/ThreadSafeConverter pattern with RemotingToolset for IIS scenarios
Architecture-specific deployment: Separate Win32EmbeddedDeployment vs Win64EmbeddedDeployment packages depending on target bitness
Azure App Service / serverless: Native-binary dependency commonly fails on locked-down PaaS hosts

Support Model

Community-maintained. There is no commercial backing, SLA, or hotfix pipeline; rendering-engine issues typically route to the upstream wkhtmltopdf tracker, which is itself archived.

Architecture Notes

The StaticDeployment pattern requires pre-extracting native DLLs to a specific folder structure before first use. This adds steps to CI/CD pipelines and can introduce race conditions in horizontally scaled environments. The RemotingToolset abstraction, while solving IIS hosting issues, adds an AppDomain boundary and serialization overhead.

Feature Comparison Overview

Aspect	TuesPechkin	IronPDF
Current Status	Wrapper around archived wkhtmltopdf upstream	Active development, regular updates
HTML Support	HTML 4/5 partial, circa-2015 CSS	Full HTML5, CSS3, CSS Grid, Flexbox
Rendering Engine	WebKit fork (circa 2015)	Chromium
Installation	NuGet + native binary package + runtime deps	Single NuGet package
Support	Community forums	Commercial support, engineering team
Future Trajectory	Upstream archived	Chromium-aligned roadmap

Code Comparison: HTML String Conversion

TuesPechkin — HTML String to PDF

// NuGet: Install-Package TuesPechkin
// NuGet: Install-Package TuesPechkin.Wkhtmltox.Win64
using TuesPechkin;
using System;
using System.IO;

public class TuesPechkinExample
{
    private static IConverter _converter;

    static TuesPechkinExample()
    {
        // Pre-create deployment path for the native binary
        string deploymentPath = Path.Combine(
            AppDomain.CurrentDomain.BaseDirectory,
            "wkhtmltopdf"
        );

        Directory.CreateDirectory(deploymentPath);

        // Singleton thread-safe converter pattern (common for web apps)
        _converter = new ThreadSafeConverter(
            new RemotingToolset<PdfToolset>(
                new Win64EmbeddedDeployment(
                    new StaticDeployment(deploymentPath)
                )
            )
        );
    }

    public byte[] GenerateInvoice(string htmlContent)
    {
        var document = new HtmlToPdfDocument
        {
            GlobalSettings =
            {
                PaperSize = PaperKind.A4,
                Orientation = GlobalSettings.PaperOrientation.Portrait,
                Margins = new MarginSettings { Unit = Unit.Millimeters, Top = 10 }
            },
            Objects =
            {
                new ObjectSettings
                {
                    HtmlText = htmlContent,
                    WebSettings = { LoadImages = true }
                }
            }
        };

        return _converter.Convert(document);
    }
}

Things to note in this pattern:

The converter is typically a static singleton — it is not designed for per-request creation and disposal
Win64EmbeddedDeployment is bitness-specific; 32-bit apps need the Win32 equivalent
StaticDeployment requires the folder to exist before first use (worth scripting in CI rather than relying on first-call creation)
The API is synchronous — there is no async overload, so the call blocks the calling thread
CSS support reflects the underlying WebKit fork; modern Grid and newer Flexbox features may not render as expected
The native binary is loaded into the host process and remains resident across calls

IronPDF — HTML String to PDF

// NuGet: Install-Package IronPdf
using IronPdf;
using System.Threading.Tasks;

public class IronPdfExample
{
    public async Task<byte[]> GenerateInvoiceAsync(string htmlContent)
    {
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        var renderer = new ChromePdfRenderer();

        // Modern CSS rendering settings
        renderer.RenderingOptions.CssMediaType =
            IronPdf.Rendering.PdfCssMediaType.Screen;
        renderer.RenderingOptions.PrintHtmlBackgrounds = true;

        using var pdf = await renderer.RenderHtmlAsPdfAsync(htmlContent);
        return pdf.BinaryData;
    }
}

IronPDF's approach eliminates the static deployment ceremony. The renderer handles native dependencies automatically, works on any CPU architecture, and disposes cleanly. The async pattern prevents thread blocking, making it suitable for high-traffic ASP.NET Core applications. Learn more about HTML string conversion and the ChromePdfRenderer API.

Code Comparison: URL to PDF with Authentication

TuesPechkin — URL Conversion

// NuGet: Install-Package TuesPechkin
// NuGet: Install-Package TuesPechkin.Wkhtmltox.Win64
using TuesPechkin;
using System;
using System.IO;

public class TuesPechkinUrlConverter
{
    private readonly IConverter _converter;

    public TuesPechkinUrlConverter()
    {
        string deploymentPath = Path.Combine(
            AppDomain.CurrentDomain.BaseDirectory,
            "wkhtmltopdf"
        );
        Directory.CreateDirectory(deploymentPath);

        _converter = new ThreadSafeConverter(
            new RemotingToolset<PdfToolset>(
                new Win64EmbeddedDeployment(
                    new StaticDeployment(deploymentPath)
                )
            )
        );
    }

    public void ConvertUrlToPdf(string url, string outputPath)
    {
        var document = new HtmlToPdfDocument
        {
            GlobalSettings =
            {
                PaperSize = PaperKind.A4,
                Orientation = GlobalSettings.PaperOrientation.Portrait
            },
            Objects =
            {
                new ObjectSettings
                {
                    PageUrl = url,
                    WebSettings =
                    {
                        LoadImages = true,
                        // Basic HTTP auth surface only
                        UserStyleSheet = "print.css"
                    }
                }
            }
        };

        byte[] pdfBytes = _converter.Convert(document);
        File.WriteAllBytes(outputPath, pdfBytes);
    }
}

Things to note in this pattern:

Authentication surface is limited to basic HTTP auth — there is no first-class bearer token or OAuth flow
UserStyleSheet paths are resolved against the deployment, which can be fragile in container environments — verify paths against your runtime layout
JavaScript-heavy pages (SPAs) may not render fully under the WebKit fork
Custom request headers and programmatic cookies are not part of the URL-loading API
Modern TLS handshakes can fail with HTTPS hosts depending on the bundled binary version
There is no first-class timeout knob on the URL fetch path

IronPDF — URL to PDF with Modern Auth

// NuGet: Install-Package IronPdf
using IronPdf;
using System;
using System.Threading.Tasks;

public class IronPdfUrlConverter
{
    public async Task<byte[]> ConvertAuthenticatedUrlAsync(
        string url,
        string bearerToken)
    {
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        var renderer = new ChromePdfRenderer();

        // Cookie-based credential passthrough
        renderer.LoginCredentials.CustomCookies.Add(
            new System.Net.Cookie("AuthToken", bearerToken, "/", new Uri(url).Host)
        );

        renderer.RenderingOptions.Timeout = 60; // seconds
        renderer.RenderingOptions.WaitFor.RenderDelay(500); // Wait for JS

        using var pdf = await renderer.RenderUrlAsPdfAsync(url);
        return pdf.BinaryData;
    }
}

IronPDF handles modern authentication patterns, sets explicit timeouts, and waits for JavaScript execution. The async API prevents blocking in web contexts, and resource disposal is automatic. See the Chrome rendering engine guide for advanced scenarios.

Code Comparison: Complex Layout with Images

TuesPechkin — Layout Rendering

// NuGet: Install-Package TuesPechkin
// NuGet: Install-Package TuesPechkin.Wkhtmltox.Win64
using TuesPechkin;
using System;
using System.IO;

public class TuesPechkinLayoutRenderer
{
    private readonly IConverter _converter;

    public TuesPechkinLayoutRenderer()
    {
        string path = Path.Combine(
            AppDomain.CurrentDomain.BaseDirectory,
            "wkhtmltopdf"
        );
        Directory.CreateDirectory(path);

        _converter = new ThreadSafeConverter(
            new RemotingToolset<PdfToolset>(
                new Win64EmbeddedDeployment(new StaticDeployment(path))
            )
        );
    }

    public byte[] RenderDashboard(string htmlWithGrid)
    {
        var document = new HtmlToPdfDocument
        {
            GlobalSettings =
            {
                PaperSize = PaperKind.A4,
                Orientation = GlobalSettings.PaperOrientation.Landscape,
                Margins = new MarginSettings
                {
                    Unit = Unit.Millimeters,
                    Top = 10,
                    Bottom = 10,
                    Left = 10,
                    Right = 10
                }
            },
            Objects =
            {
                new ObjectSettings
                {
                    HtmlText = htmlWithGrid,
                    WebSettings =
                    {
                        LoadImages = true,
                        PrintMediaType = true // Use print CSS
                    }
                    // No first-class viewport setting on this API
                }
            }
        };

        return _converter.Convert(document);
    }
}

Things to note in this pattern:

CSS Grid is not part of the underlying engine's spec coverage — Grid layouts typically need fallback markup
Flexbox is partially supported; flex-wrap and newer features may not match modern browsers — verify against your version
Web Fonts loaded from external CDNs can fail depending on the binary's TLS support
SVG support is limited compared to a current Chromium engine
Base64-encoded images may render inconsistently depending on the binary version
There is no built-in viewport-width knob for responsive layouts

IronPDF — Modern Layout Rendering

// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Rendering;
using System.Threading.Tasks;

public class IronPdfLayoutRenderer
{
    public async Task<byte[]> RenderDashboardAsync(string htmlWithGrid)
    {
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        var renderer = new ChromePdfRenderer();

        // Modern layout support
        renderer.RenderingOptions.PaperOrientation = 
            PdfPaperOrientation.Landscape;
        renderer.RenderingOptions.MarginTop = 10;
        renderer.RenderingOptions.MarginBottom = 10;
        renderer.RenderingOptions.CssMediaType = PdfCssMediaType.Screen;
        renderer.RenderingOptions.PrintHtmlBackgrounds = true;

        // Responsive viewport for mobile-first designs
        renderer.RenderingOptions.PaperFit.UseResponsiveCssRendering(1280);

        using var pdf = await renderer.RenderHtmlAsPdfAsync(htmlWithGrid);
        return pdf.BinaryData;
    }
}

IronPDF's Chromium engine natively supports CSS Grid, Flexbox, Web Fonts, SVG, and Canvas elements. The UseResponsiveCssRendering method allows viewport control for mobile-first layouts. Pixel-perfect rendering documentation explains advanced customization.

API Mapping Reference

TuesPechkin Concept	IronPDF Equivalent
`HtmlToPdfDocument`	`ChromePdfRenderer.RenderHtmlAsPdf()`
`ObjectSettings.PageUrl`	`ChromePdfRenderer.RenderUrlAsPdf()`
`ObjectSettings.HtmlText`	Pass string to `RenderHtmlAsPdf()`
`GlobalSettings.PaperSize`	`RenderingOptions.PaperSize`
`GlobalSettings.Orientation`	`RenderingOptions.PaperOrientation`
`MarginSettings`	`RenderingOptions.MarginTop/Bottom/Left/Right`
`WebSettings.LoadImages`	Enabled by default, no explicit flag
`ThreadSafeConverter`	Renderer is thread-safe by design
`StaticDeployment`	Automatic native dependency management
`RemotingToolset`	Not required—no IIS special handling
`Convert()` method	`RenderHtmlAsPdf()` / `RenderUrlAsPdf()`
`PdfToolset`	Abstracted—no manual toolset selection
Header/Footer APIs	`RenderingOptions.TextHeader` / `TextFooter`

Comprehensive Feature Comparison

Feature Category	TuesPechkin	IronPDF
Status & Support
Active Development	Wrapper around archived wkhtmltopdf	Yes (regular releases)
Commercial Support	No	Yes — engineering team + SLA
Security Patches	Depends on upstream	Regular product updates
.NET 9 Support	Not first-class	Yes
LTS Commitment	No	Multi-year roadmap
Content Creation
HTML5 Support	Partial (circa-2015 WebKit fork)	Full (Chromium)
CSS3 Features	Limited spec coverage	Grid, Flexbox, Variables
JavaScript Execution	Limited	Chrome V8 engine
Web Fonts	Partial	Full support (Google Fonts, custom)
SVG Rendering	Basic	Chromium-grade SVG
Responsive Layouts	No viewport API	UseResponsiveCssRendering()
PDF Operations
HTML to PDF	Yes	Yes
URL to PDF	Yes	Yes
Async API	No	Yes
Merge PDFs	Out of scope	Built-in `PdfDocument.Merge()`
Split PDFs	Out of scope	Yes — PdfDocument operations
Add Watermarks	Out of scope	Yes — text and image
Digital Signatures	Out of scope	Yes — X.509 certificates
Form Creation	Out of scope	`CreatePdfFormsFromHtml = true`
Extract Text	Out of scope	Yes — `PdfDocument.ExtractAllText()`
Security
Password Protection	Out of scope	Yes — AES
Certificate Encryption	Out of scope	Yes
Permissions (Print/Copy)	Out of scope	Yes — granular control
Redaction	Out of scope	Yes
Deployment
Native Binary Residency	Loaded into host process	Managed internally
Thread Safety	Singleton + `ThreadSafeConverter` pattern	Thread-safe
Container Deployment	Manual native-binary extraction	Works out of the box
Azure App Service	Typically not supported	Supported
Linux Compatibility	Native binary only	Yes (.NET Core / 5+)
macOS Support	Native binary only	Yes
Development
NuGet Install	2 packages + native runtime deps	Single package
Code Surface	Deployment ceremony required	Typically 3–5 lines
Debugging	Limited error messages	Detailed exceptions
Samples	Community-curated	Extensive docs + examples

Patterns Teams Hit When Migrating

When teams move off TuesPechkin, these patterns commonly come up — verify each against your version and target environment:

CSS Grid layouts: The underlying engine predates the Grid spec; layouts using Grid typically need fallback markup
Native binary stays resident: The wkhtmltox library is loaded into the host process and stays loaded across calls
Modern TLS/HTTPS: Older bundled binaries can struggle with current TLS handshakes
JavaScript-heavy pages: SPAs and dynamic dashboards may not render fully
Docker images: Containers typically need explicit native-binary extraction and runtime deps
Azure App Service / locked-down PaaS: Native-binary dependencies commonly fail in these environments
Bitness selection: 32-bit vs 64-bit requires the matching TuesPechkin.Wkhtmltox.Win32 / Win64 package
Web Fonts from CDNs: Loading from external CDNs can fail depending on the binary's TLS support
SVG rendering: SVG coverage is narrower than current browsers
Synchronous API: There is no async overload; calls block the calling thread

Installation Comparison

TuesPechkin:

Install-Package TuesPechkin
Install-Package TuesPechkin.Wkhtmltox.Win64  # or .Win32 for 32-bit
# Plus the matching Visual C++ runtime on the host

using TuesPechkin;

// Static initialization before first use
string deployPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "wkhtmltopdf");
Directory.CreateDirectory(deployPath);
var converter = new ThreadSafeConverter(
    new RemotingToolset<PdfToolset>(
        new Win64EmbeddedDeployment(new StaticDeployment(deployPath))
    )
);

IronPDF:

Install-Package IronPdf

using IronPdf;

IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

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

Conclusion

TuesPechkin solved a real problem in the .NET Framework era — it gave .NET teams a clean managed surface over wkhtmltopdf. For teams maintaining legacy applications with simple layout needs and no budget for commercial tools, it can still do the job, with the caveat that the underlying wkhtmltopdf project is archived upstream and not receiving further development.

Migration tends to come up when:

Your CSS uses Grid, newer Flexbox, or CSS Variables
You deploy to Docker, Azure App Service, or Linux containers
Long-running web workers care about native-binary residency
You need async patterns for scalable web apps
JavaScript-heavy content (SPAs, charts) needs to render the way browsers render it today
You want ongoing patch management from a vendor

IronPDF approaches the problem differently: a current Chromium engine, native dependencies handled internally, and a .NET-idiomatic API. The trade-off is a commercial license in exchange for less deployment ceremony and rendering that tracks current browsers. For teams where rendering fidelity and maintenance burden are real concerns, that trade-off often pays back inside the first sprint.

What is your experience with wkhtmltopdf-based tools in modern .NET projects? Any gotchas or workarounds worth sharing?

Related Resources:

Scryber.Core vs IronPDF: side by side for .NET teams

IronSoftware — Mon, 25 May 2026 14:50:00 +0000

Picture this: a flexbox layout that previews cleanly in the browser but breaks pagination once it hits the PDF renderer, and the docs say only "CSS support is partial." The root cause is usually the same — the PDF library uses a custom CSS pipeline rather than a browser engine, and a spec feature you depended on simply is not implemented.

Scryber.Core is an open-source, template-driven PDF library for .NET that emphasizes programmatic document layout and data binding with a Handlebars-style template syntax. It is built entirely in C# with no browser dependency, which makes it portable and lightweight. The trade-off is that its XHTML/CSS support depends on the maintainer implementing each spec feature manually. If you are reaching for Scryber, this comparison aims to help you decide when its approach fits, and when a Chromium-based renderer would save troubleshooting time.

Understanding IronPDF

IronPDF uses Google Chrome's rendering engine (Chromium/Blink) to generate PDFs, which means it supports whatever Chrome supports: CSS Grid, Flexbox, CSS variables, web fonts, SVG, and JavaScript. When you call ChromePdfRenderer.RenderHtmlAsPdf(), your HTML renders the way it would in Chrome's "Print to PDF" feature. If a CSS property works in Chrome DevTools, it typically works in the PDF.

The trade-off is footprint: IronPDF bundles the Chromium engine, which is substantially larger than Scryber's pure-C# package. For teams that value "write HTML once, render everywhere" over minimal package size, that is usually an acceptable trade. IronPDF targets .NET 10, 9, 8, 7, 6, .NET Core, and .NET Framework, and runs on Windows, Linux, macOS, Docker, and major cloud platforms.

Key Characteristics of Scryber.Core

Product Status

Open-source project under LGPL-3.0; commercial use is permitted, but modifications to Scryber itself must be shared under LGPL. Active maintainer (richard-scryber) on GitHub. The library has steady releases — current version is 9.x. Community support runs through GitHub issues; there is no dedicated commercial support team.

Rendering Capabilities

Scryber implements a custom XHTML/CSS layout engine rather than embedding a browser engine, so support for modern web standards is whatever the maintainer has implemented. CSS Grid is not part of the supported layout model — verify against the latest docs before relying on it. Complex CSS selectors (:nth-of-type, advanced attribute selectors, less-common pseudo-elements) have partial support. JavaScript execution is not supported — any dynamic content must be pre-rendered server-side. Web fonts work via @font-face but may need explicit configuration. SVG is supported; CSS animations and some advanced transforms typically are not.

Layout and Pagination

The layout engine uses Scryber's own flow logic rather than a browser layout algorithm, which can lead to subtle differences from a browser preview. Page size and margins are declared via CSS @page in the template, which is Scryber's idiom for paged-media layout. Remote images are fetched synchronously at render time. Table rendering and font-metrics calculation may differ from a browser, so dense or complex layouts can need tuning.

Support Status

Community-driven support via GitHub issues; response time depends on maintainer availability. Documentation covers basic scenarios thoroughly but is thinner on edge-case troubleshooting. No SLA or hotfix guarantees. Commercial projects need to factor in LGPL compliance — linking is permitted, but modifications to Scryber itself must be published.

Architecture Notes

Template syntax mixes XHTML with Handlebars-style binding ({{variable}}), backed by Scryber's own expression engine — not standard JavaScript/Razor. Data binding happens at render time via doc.Params; there is no strongly-typed model binding equivalent to MVC Razor. Performance can scale with document complexity, since the layout engine is single-threaded. Debugging layout differences requires understanding Scryber's box model rather than browser DevTools.

Feature Comparison Overview

Aspect	Scryber.Core	IronPDF
Current Status	Active open-source (single maintainer)	Commercial, active development
HTML Support	XHTML + CSS subset	Full HTML5 / CSS3 / JavaScript (Chromium)
Rendering Engine	Custom layout engine	Chromium-based
Installation	Single NuGet (smaller footprint)	Single NuGet (Chromium bundled)
Support	GitHub issues (community)	Commercial engineering support
Licensing	LGPL-3.0	Commercial license

Code Comparison: Common Scenarios

Scryber.Core — Rendering HTML with Data Binding

Scryber's approach uses XHTML templates with Handlebars-style binding. Here is an invoice with a line-items list:

// NuGet: Install-Package Scryber.Core
using Scryber.Components;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;

public class ScryberInvoiceGenerator
{
    public void GenerateInvoice(int invoiceId, string outputPath)
    {
        // XHTML template with Scryber {{ }} binding
        string templateHtml = @"
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
    <title>Invoice {{invoiceNumber}}</title>
    <style>
        @page { size: A4 portrait; margin: 20pt; }
        body { font-family: Arial, sans-serif; margin: 20px; }
        .invoice-header { display: block; }
        table { width: 100%; border-collapse: collapse; }
        td, th { border: 1px solid #ddd; padding: 8px; }
    </style>
</head>
<body>
    <div class='invoice-header'>
        <h1>Invoice #{{invoiceNumber}}</h1>
        <p>Date: {{invoiceDate}}</p>
    </div>

    <table>
        <thead>
            <tr><th>Item</th><th>Quantity</th><th>Price</th></tr>
        </thead>
        <tbody>
            <template data-bind='{{#each items}}'>
                <tr>
                    <td>{{name}}</td>
                    <td>{{quantity}}</td>
                    <td>${{price}}</td>
                </tr>
            </template>
        </tbody>
    </table>

    <p><strong>Total: ${{total}}</strong></p>
</body>
</html>";

        var invoiceData = FetchInvoiceData(invoiceId);

        using (var reader = new StringReader(templateHtml))
        using (var doc = Document.ParseDocument(reader, string.Empty, ParseSourceType.DynamicContent))
        using (var stream = new FileStream(outputPath, FileMode.Create))
        {
            // Bind data via Params dictionary
            doc.Params["invoiceNumber"] = invoiceData.InvoiceNumber;
            doc.Params["invoiceDate"] = invoiceData.Date.ToString("yyyy-MM-dd");
            doc.Params["total"] = invoiceData.Total;

            doc.Params["items"] = invoiceData.Items.Select(i => new
            {
                name = i.ItemName,
                quantity = i.Quantity,
                price = i.Price
            }).ToArray();

            doc.SaveAsPDF(stream);
        }
    }

    private InvoiceData FetchInvoiceData(int invoiceId)
    {
        // Implementation details...
        return new InvoiceData();
    }
}

public class InvoiceData
{
    public string InvoiceNumber { get; set; }
    public DateTime Date { get; set; }
    public decimal Total { get; set; }
    public List<LineItem> Items { get; set; }
}

public class LineItem
{
    public string ItemName { get; set; }
    public int Quantity { get; set; }
    public decimal Price { get; set; }
}

Things to know when working with Scryber:

XHTML strictness: Templates must be well-formed XHTML. Most real-world HTML needs to be cleaned up before Scryber will parse it.
In-memory templates: Document.ParseDocument(reader, "", ParseSourceType.DynamicContent) accepts a TextReader, so you can render directly from a string without writing to disk.
Data binding syntax: The {{#each}} and <template data-bind=...> constructs require a specific object shape. If your model does not match, project it to anonymous types first.
CSS scope: Modern layout features such as CSS Grid are not part of Scryber's supported subset; verify Flexbox behavior against your version.
Page geometry: Page size and margins live in CSS @page, which is the documented Scryber idiom.
No JavaScript: Any client-side logic must be pre-computed server-side before binding.
Fonts: @font-face is supported but may need explicit paths or embedded data; metrics can differ slightly from a browser.

IronPDF — Rendering HTML with Data Binding

IronPDF accepts HTML strings, files, or URLs directly. No template file requirement, no special binding syntax:

// NuGet: Install-Package IronPdf
using IronPdf;
using System.Linq;

public void GenerateInvoice(int invoiceId, string outputPath)
{
    IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

    var invoiceData = FetchInvoiceData(invoiceId);

    string invoiceHtml = $@"
<!DOCTYPE html>
<html>
<head>
    <style>
        body {{ font-family: Arial, sans-serif; margin: 20px; }}
        .invoice-header {{
            display: flex;
            justify-content: space-between;
            align-items: center;
        }}
        table {{ width: 100%; border-collapse: collapse; margin-top: 20px; }}
        td, th {{ border: 1px solid #ddd; padding: 8px; }}
    </style>
</head>
<body>
    <div class='invoice-header'>
        <h1>Invoice #{invoiceData.InvoiceNumber}</h1>
        <p>Date: {invoiceData.Date:yyyy-MM-dd}</p>
    </div>

    <table>
        <thead>
            <tr><th>Item</th><th>Quantity</th><th>Price</th></tr>
        </thead>
        <tbody>
            {string.Join("", invoiceData.Items.Select(item => $@"
            <tr>
                <td>{item.ItemName}</td>
                <td>{item.Quantity}</td>
                <td>${item.Price:F2}</td>
            </tr>"))}
        </tbody>
    </table>

    <p><strong>Total: ${invoiceData.Total:F2}</strong></p>
</body>
</html>";

    var renderer = new ChromePdfRenderer();
    using var pdf = renderer.RenderHtmlAsPdf(invoiceHtml);
    pdf.SaveAs(outputPath);
}

Learn more about HTML to PDF conversion and handling HTML files.

IronPDF characteristics worth noting:

HTML renders through Chromium, so a browser preview is a reliable proxy for the PDF output.
Work with HTML strings, files, or URLs directly — no template-file I/O required.
CSS Grid, Flexbox, and modern layout features are supported through the Chromium engine.
JavaScript executes before PDF generation when enabled (see the JavaScript support guide).

Scryber.Core — Handling Modern CSS

Scryber's CSS support covers a documented subset; for features outside that subset you typically fall back to traditional layout primitives:

// NuGet: Install-Package Scryber.Core
using Scryber.Components;
using System.IO;

public void RenderComplexLayout(string outputPath)
{
    string templateHtml = @"
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
    <style>
        @page { size: A4 portrait; margin: 20pt; }

        :root {
            --primary-color: #3498db;
            --spacing: 20px;
        }

        body {
            font-family: 'Segoe UI', Tahoma, sans-serif;
            margin: var(--spacing);
            color: #333;
        }

        /* CSS Grid is not part of Scryber's supported layout model */
        .grid-container { display: block; }

        /* Flexbox: basic support; complex justify/wrap combinations may need testing */
        .flex-container { display: flex; }

        /* Traditional two-column layout via floats works reliably */
        .two-column { width: 100%; }
        .two-column .column {
            float: left;
            width: 48%;
            margin-right: 2%;
        }

        .table-striped tr:nth-child(even) {
            background-color: #f2f2f2;
        }
    </style>
</head>
<body>
    <h1 style='color: var(--primary-color);'>Layout Sample</h1>

    <table style='width: 100%;'>
        <tr>
            <td style='width: 50%; vertical-align: top;'><p>Column 1 content</p></td>
            <td style='width: 50%; vertical-align: top;'><p>Column 2 content</p></td>
        </tr>
    </table>
</body>
</html>";

    using (var reader = new StringReader(templateHtml))
    using (var doc = Document.ParseDocument(reader, string.Empty, ParseSourceType.DynamicContent))
    using (var stream = new FileStream(outputPath, FileMode.Create))
    {
        doc.SaveAsPDF(stream);
    }
}

Scryber CSS checklist:

Preview in the browser first, then verify Scryber renders the same layout.
Test CSS features in isolation before combining them in production templates.
For complex multi-column or card-grid designs, traditional layouts (tables, floats) are typically more predictable than Grid.
Check the project's GitHub issues for any documented limitations relevant to your CSS.
Expect some differences from CSS Paged Media — page geometry is set via @page in CSS, which is Scryber's documented idiom.
Verify fonts load as expected; silent fallback can happen if a font cannot be resolved.

IronPDF — Rendering Modern CSS

IronPDF renders through Chromium, so modern CSS generally works as it does in the browser:

// NuGet: Install-Package IronPdf
using IronPdf;

public void RenderComplexLayout(string outputPath)
{
    IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

    string html = @"
<!DOCTYPE html>
<html>
<head>
    <style>
        :root {
            --primary-color: #3498db;
            --spacing: 20px;
        }

        body {
            font-family: 'Segoe UI', Tahoma, sans-serif;
            margin: var(--spacing);
        }

        .grid-container {
            display: grid;
            grid-template-columns: repeat(3, 1fr);
            gap: var(--spacing);
        }

        .flex-container {
            display: flex;
            justify-content: space-between;
            flex-wrap: wrap;
            align-items: center;
        }

        .grid-item:nth-child(3n) {
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            color: white;
        }

        .card::before {
            content: '\2192';
            margin-right: 10px;
        }
    </style>
</head>
<body>
    <h1 style='color: var(--primary-color);'>Layout Sample</h1>

    <div class='grid-container'>
        <div class='card'>Item 1</div>
        <div class='card'>Item 2</div>
        <div class='card'>Item 3</div>
    </div>

    <div class='flex-container'>
        <p>Flex Item 1</p>
        <p>Flex Item 2</p>
        <p>Flex Item 3</p>
    </div>
</body>
</html>";

    var renderer = new ChromePdfRenderer();
    using var pdf = renderer.RenderHtmlAsPdf(html);
    pdf.SaveAs(outputPath);
}

Preview in Chrome DevTools, get the same PDF output.

API Mapping Reference

Scryber.Core API	IronPDF Equivalent
`Document.ParseDocument(reader, "", ParseSourceType.DynamicContent)`	`ChromePdfRenderer.RenderHtmlAsPdf(html)`
`Document.ParseDocument(path)`	`ChromePdfRenderer.RenderHtmlFileAsPdf(path)`
`doc.Params[key] = value`	String interpolation or Razor templates
`{{variable}}` syntax	C# string interpolation `{variable}`
`{{#each collection}}`	LINQ `.Select()` + `string.Join()`
`doc.SaveAsPDF(stream)`	`pdf.SaveAs(path)` or `pdf.BinaryData`
`@page` CSS in template	`ChromePdfRenderer.RenderingOptions` (paper size, margins)
`doc.RenderOptions.Compression`	`ChromePdfRenderer.RenderingOptions`
`doc.Info.Title` / `doc.Info.Author`	`pdf.MetaData.Title` / `pdf.MetaData.Author`
Custom font embedding	CSS `@font-face` (Chromium font handling)

Comprehensive Feature Comparison

Category	Feature	Scryber.Core	IronPDF
Status	Active development	Yes (single maintainer)	Yes (commercial team)
	.NET 10 support	.NET Standard 2.0/2.1, .NET 8/9	Yes
	Open source	Yes (LGPL-3.0)	No (commercial)
Support	Documentation	Read-the-docs site + samples	Comprehensive with troubleshooting
	Community channel	GitHub issues	Commercial engineering support
	SLA availability	No	Yes (support plans)
Content Creation	HTML templates	XHTML with Scryber binding	Standard HTML
	CSS3 support	Subset	Full (Chromium)
	CSS Grid	Not supported	Yes
	Flexbox	Partial	Yes
	JavaScript execution	No	Yes
	Modern selectors	Partial	Full
PDF Operations	Merge PDFs	Not supported	Yes
	Split PDFs	Not supported	Yes
	Watermarks	Overlay HTML in template	`ApplyStamp` / `ApplyWatermark`
	Digital signatures	Not part of public API	Yes
Security	Encryption	Not part of public API	Yes
	Permissions	Not part of public API	Yes
Differences	CSS Grid rendering	Not supported	Supported
	Flexbox	Partial	Supported
	Font metrics	Custom engine	Chromium metrics
	JavaScript support	None	Full
	Input strictness	Well-formed XHTML required	Real-world HTML accepted
Development	Learning curve	Scryber template syntax	Standard HTML
	Debugging tools	Custom engine	Chrome DevTools as preview
	Performance (large docs)	Single-threaded layout	Optimized Chromium pipeline

Installation Comparison

Scryber.Core Installation

# Install base package
dotnet add package Scryber.Core

# Namespace imports
# using Scryber.Components;   // Document, Page, etc.
# using Scryber.Drawing;      // Units, colors
# using Scryber.PDF;          // RenderOptions / OutputCompressionType

Pure-C# install, no native dependencies. Templates can be supplied as files on disk or directly from a TextReader / StringReader in memory.

IronPDF Installation

# Single package with bundled Chromium
dotnet add package IronPdf

# Namespace import
# using IronPdf;

Larger package because Chromium ships with it. Accepts HTML strings, files, or URLs without template files.

When Scryber.Core Makes Sense

Scryber.Core fits scenarios where its trade-offs align with project constraints.

Lightweight footprint priorities: If package size matters more than full CSS compatibility — embedded systems, IoT devices, or environments with strict size limits — Scryber's pure-C# footprint is noticeably smaller than a Chromium-bundled renderer.

Template-driven workflows: Teams already comfortable with XHTML templates and Handlebars-style binding may find Scryber's syntax a natural fit. If your architecture separates presentation (templates) from logic and you do not need modern CSS layout, Scryber works well.

LGPL-compatible projects: Open-source projects under LGPL-3.0 or compatible licenses can use Scryber without licensing costs. Commercial projects can link to Scryber under LGPL terms (your application code does not need to be open-sourced; modifications to Scryber itself do).

Simple document layouts: Reports with tables, text, and images — no responsive web-style layouts — render reliably in Scryber. If your PDF templates look more like "formatted Word documents" than "web pages," Scryber's limitations rarely surface.

When IronPDF is the Better Choice

For most modern .NET teams, IronPDF's architecture aligns with current web-tooling practices.

Chrome DevTools as your preview: If your workflow is "design in browser, export to PDF," IronPDF's Chromium-based rendering removes most of the "looks good in browser, breaks in PDF" gap. Teams using modern CSS (Grid, Flexbox, transforms, animations) avoid working around partial-support questions.

JavaScript-dependent content: Anything that depends on JavaScript execution — charts rendered by Chart.js, dynamic forms with validation, content loaded via AJAX — needs a JavaScript-capable renderer. Scryber does not execute JS; IronPDF does.

Support and SLA requirements: Enterprise teams needing guaranteed response times typically need more than community GitHub issues. IronPDF provides commercial support with SLAs available.

Rapid iteration: When CSS does not render as expected, Chrome DevTools let you inspect and adjust the page interactively, then re-render. Scryber's custom engine does not have a comparable inspector, so iteration is more of a guess-and-check loop.

Conclusion

Scryber.Core is a thoughtful open-source PDF library that prioritizes a lightweight footprint and template-driven generation. For simple documents and teams comfortable working inside its XHTML/CSS subset, it is a viable choice. Its custom rendering engine does mean you cannot rely on browser previews matching PDF output one-to-one, which can slow down troubleshooting.

IronPDF's Chromium-based approach narrows that gap. HTML renders similarly in browser and PDF. Modern CSS features work without checking documentation for partial support. JavaScript executes when needed. The trade-off is package size, which most teams accept for development velocity and rendering predictability.

For teams building new PDF workflows today, the question is: do you optimize for package size (Scryber) or development speed (IronPDF)? Most teams choose speed once they have spent enough time debugging layout differences.

What CSS feature has caused you the most PDF rendering headaches?

Additional IronPDF resources: JavaScript in HTML to PDF, HTML file rendering guide.

PDFium vs IronPDF: the decision guide for .NET teams

IronSoftware — Mon, 25 May 2026 12:49:00 +0000

A .NET team needs PDF thumbnails for a document portal, reaches for a PDFium-based wrapper, and ships locally in an hour. Then the deployment to a Linux container surfaces a "Unable to load DLL 'pdfium.dll'" — and a few hours later, the team also realises the wrapper renders pages but cannot fill the AcroForm fields the next user story depends on. That gap — rendering engine vs. full PDF toolkit — is the real story when comparing PDFium with IronPDF.

PDFium is Google's open-source C++ PDF library, the same engine that ships inside Chromium and Android, released under BSD-3-Clause. There is no official Google-supplied .NET binding. The .NET ecosystem ships several community wrappers around the native engine, including:

PdfiumViewer (Apache 2.0; archived August 2019, last NuGet release 2.13.0 in November 2017)
PdfiumViewer.Updated (maintained community fork targeting .NET Core / .NET 6)
PDFiumCore (Dtronix, .NET Standard 2.1 P/Invoke bindings)
Pdfium.Net.SDK (Patagames, commercial)

The wrappers differ in API surface, platform support, and maintenance cadence, but they share one trait: PDFium itself is a rendering and parsing engine, not an HTML-to-PDF or document-authoring engine. None of the wrappers can convert HTML to PDF on their own, because PDFium has no HTML parser.

Understanding IronPDF

IronPDF is a commercial PDF generation and manipulation library built on a Chromium rendering engine. The core use case is creating PDFs from HTML, URLs, or other content with rendering aligned to Chrome Print Preview. Unlike PDFium wrappers that render existing PDFs to images, IronPDF generates new PDFs from web content (HTML5, CSS3, JavaScript), manipulates existing PDFs (merge, split, forms, signatures, encryption), and extracts content (text, images, metadata). It targets .NET Framework 4.6.2+, .NET Core 3.1+, and modern .NET versions through .NET 10, with cross-platform packaging for Windows, Linux, macOS, Docker, and cloud environments — separate native binary packages are not required.

Where PDFium wrappers fit, and where they do not

Product status

Fragmented ecosystem — multiple wrappers, no single canonical package
Community maintenance — most wrappers are individual or small-team efforts
Version drift — wrappers update their bundled PDFium binaries independently, so binaries can be incompatible across packages
API surface differs between wrappers and across major versions

Missing capabilities (relative to a full PDF toolkit)

No HTML-to-PDF generation in PDFium itself
No URL-to-PDF conversion
Document-edit operations (merge, split, insert) are limited or absent in free wrappers; Patagames Pdfium.Net.SDK exposes more
Form filling and AcroForm manipulation are limited or absent in free wrappers
Digital signatures and encryption are not exposed by the free wrappers
Text extraction may not be present in viewer-only wrappers

Technical considerations

Native binary dependency: requires the appropriate pdfium.dll / libpdfium.so / libpdfium.dylib per RID, which adds deployment steps
P/Invoke marshaling overhead on frequent native calls
Manual disposal — forgetting using statements can cause native handles to leak
Platform packaging varies — some wrappers are Windows-only, others ship per-RID native binaries you must wire up
Different wrappers use different PDFium builds and cannot be mixed in one process

Support

Free wrappers rely on GitHub issues and community channels
Documentation depth varies — some wrappers have minimal published docs and rely on IntelliSense / source
Bug-fix cadence depends on maintainer availability
Patagames Pdfium.Net.SDK is the commercial option in the family and offers paid support tiers

Architecture

Tight coupling to native binaries can complicate containerized and serverless deployments unless RID-specific layouts are explicit
Async APIs vary by wrapper; several expose synchronous-only operations
Configurability is typically narrow — wrappers tend to expose a small subset of PDFium's configuration surface

Feature Comparison Overview

Aspect	PDFium wrappers	IronPDF
Current status	Fragmented, community-maintained (free); commercial Patagames option	Active, commercial, single product
HTML support	None (PDFium has no HTML parser)	HTML5 / CSS3 / JS via Chromium
Rendering quality	Suited to rendering existing PDFs	Chromium-based output for generated PDFs
Installation	Wrapper package + per-RID native binaries	Single NuGet, multi-target
Support	Community for free wrappers; paid for Patagames	Commercial support / SLA options
Future viability	Depends on individual maintainers / vendor	.NET 10-ready, cross-platform

Code Comparison

PDFium (PdfiumViewer) — Render PDF pages to images

// NuGet: PdfiumViewer  (representative open-source PDFium wrapper)
using PdfiumViewer;
using System;
using System.Drawing;
using System.Drawing.Imaging;
using System.IO;

class Program
{
    static void Main()
    {
        // Ensure the PDFium native binary for your RID is on the load path
        try
        {
            using (var document = PdfDocument.Load("existing-report.pdf"))
            {
                for (int i = 0; i < document.PageCount; i++)
                {
                    // PdfiumViewer exposes per-page sizes via document.PageSizes
                    var size = document.PageSizes[i];
                    int width = (int)(size.Width * 2);   // 2x scale
                    int height = (int)(size.Height * 2);

                    using (var bitmap = document.Render(i, width, height, 96, 96, PdfRenderFlags.Annotations))
                    {
                        bitmap.Save($"page-{i + 1}.png", ImageFormat.Png);
                    }
                }
            }

            Console.WriteLine("PDF rendered to images successfully.");
        }
        catch (DllNotFoundException ex)
        {
            // pdfium.dll not found in output directory
            Console.WriteLine($"ERROR: {ex.Message}");
        }
        catch (BadImageFormatException ex)
        {
            // x86 / x64 mismatch between process and native binary
            Console.WriteLine($"ERROR: {ex.Message}");
        }
    }
}

Notes on this approach:

PDFium is a rendering / parsing engine; generating a PDF from HTML requires a different library
The native binary must match the process architecture and RID
Pages are not first-class objects in PdfiumViewer — per-page size lives on document.PageSizes[i]
Sequential per-page calls — batching across pages is the caller's responsibility

IronPDF — Generate PDF from HTML

// NuGet: Install-Package IronPdf
using IronPdf;

IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

var htmlContent = @"
<html>
<head>
    <style>
        body { font-family: Arial; margin: 40px; }
        table { border-collapse: collapse; width: 100%; }
        th, td { border: 1px solid #ddd; padding: 8px; }
    </style>
</head>
<body>
    <h1>Monthly Report</h1>
    <table>
        <tr><th>Metric</th><th>Value</th></tr>
        <tr><td>Revenue</td><td>$125,000</td></tr>
    </table>
</body>
</html>";

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);
pdf.SaveAs("monthly-report.pdf");

The HTML to PDF tutorial walks through modern web content rendering (CSS Grid, Flexbox, JavaScript) without manual layout calculation. Platform-specific binaries are bundled by IronPdf and resolved at runtime.

PDFium (PdfiumViewer) — Extract page count and text

// NuGet: PdfiumViewer
using PdfiumViewer;
using System;
using System.Text;

class Program
{
    static void Main()
    {
        try
        {
            using (var document = PdfDocument.Load("contract.pdf"))
            {
                int pageCount = document.PageCount;
                Console.WriteLine($"Document has {pageCount} pages.");

                // PdfiumViewer's text extraction is per-page raw text via GetPdfText(int).
                // Layout/format metadata is not exposed.
                var text = new StringBuilder();
                for (int i = 0; i < pageCount; i++)
                {
                    text.AppendLine(document.GetPdfText(i));
                }
                Console.WriteLine(text.ToString());
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"PDF error: {ex.Message}");
        }
    }
}

Notes on this approach:

Text extraction is per-page raw text via GetPdfText(i); layout / format information is minimal
AcroForm field read/write is not exposed by the open-source wrappers
Document-info access and modification depend on the wrapper; not all free wrappers expose metadata writes
Digital signature validation is not part of the free-wrapper surface

IronPDF — Extract text and metadata

// NuGet: Install-Package IronPdf
using IronPdf;

IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

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

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

// Read metadata
var metadata = pdf.MetaData;
Console.WriteLine($"Title: {metadata.Title}");
Console.WriteLine($"Pages: {pdf.PageCount}");

// Modify metadata
metadata.Author = "Legal Team";
metadata.Subject = "Updated Contract";
pdf.SaveAs("contract-updated.pdf");

IronPDF provides read/write access to metadata, form fields, and content extraction. The rendering options documentation covers watermarking, headers/footers, and custom page sizes.

PDFium (PDFiumCore) — Render pages in parallel

// NuGet: PDFiumCore  (Dtronix, .NET Standard 2.1 P/Invoke bindings)
// The exact API surface varies between PDFiumCore releases — verify method names
// against your installed version.
using PDFiumCore;
using System;
using System.IO;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        try
        {
            // PDFiumCore uses .NET Standard 2.1 — target .NET Core 3.1+ or .NET 5+.
            using (var document = new PdfDocument("large-manual.pdf"))
            {
                int pageCount = document.PageCount;
                var renderTasks = new Task[pageCount];

                for (int i = 0; i < pageCount; i++)
                {
                    int pageIndex = i;  // Capture for closure
                    renderTasks[i] = Task.Run(() =>
                    {
                        using (var page = document.GetPage(pageIndex))
                        {
                            // Page width/height are in points (1/72 inch).
                            double widthPts  = page.Width;
                            double heightPts = page.Height;

                            // Convert to pixels at 150 DPI.
                            int pixelWidth  = (int)(widthPts  * 150.0 / 72.0);
                            int pixelHeight = (int)(heightPts * 150.0 / 72.0);

                            using (var bitmap = new PDFiumBitmap(pixelWidth, pixelHeight, false))
                            {
                                page.Render(bitmap);
                                // Bitmap conversion / save APIs vary by version.
                            }
                        }
                    });
                }

                await Task.WhenAll(renderTasks);
                Console.WriteLine($"Rendered {pageCount} pages.");
            }
        }
        catch (FileNotFoundException ex)
        {
            Console.WriteLine($"ERROR: {ex.Message}");
        }
    }
}

Notes on this approach:

Manual conversion from points to pixels at the target DPI
Type conversion between PDFiumBitmap and System.Drawing.Bitmap adds a copy
Thread safety of PdfDocument instances depends on the wrapper — verify against your version's documentation
Output is rasterized images; rendered images cannot be re-inserted into the source PDF without another library

IronPDF — Generate multi-page PDF from an HTML file

// NuGet: Install-Package IronPdf
using IronPdf;
using System.Threading.Tasks;

IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

var renderer = new ChromePdfRenderer();

// Render HTML file; page breaks come from CSS print media rules.
var pdf = await Task.Run(() =>
    renderer.RenderHtmlFileAsPdf("product-catalog.html"));

// Add page numbers
pdf.AddPageNumbers("Page {page} of {total-pages}");

pdf.SaveAs("catalog-with-page-numbers.pdf");

The HTML file to PDF guide covers external CSS, JavaScript execution timing, and responsive layouts.

PDFium (generic wrapper) — native binary placement

using System;
using System.IO;
using System.Reflection;

class Program
{
    static void Main()
    {
        // Most PDFium wrappers load pdfium.dll / libpdfium.so / libpdfium.dylib
        // from a runtimes/<rid>/native folder or from the application directory.
        // Container / cloud deploys typically need the runtimes folder included.

        bool isWindows = Environment.OSVersion.Platform == PlatformID.Win32NT;
        bool is64Bit = Environment.Is64BitProcess;

        string dllName = isWindows
            ? (is64Bit ? "pdfium_x64.dll" : "pdfium_x86.dll")
            : "libpdfium.so";

        string dllPath = Path.Combine(
            Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location)!,
            "runtimes",
            isWindows ? "win" : "linux",
            dllName);

        if (!File.Exists(dllPath))
        {
            // Without the expected native binary the wrapper cannot initialise.
            Console.WriteLine($"PDFium native binary not found at {dllPath}");
            return;
        }

        Console.WriteLine($"PDFium native binary located at {dllPath}");
    }
}

Notes on this approach:

Native binary discovery is the application's responsibility per RID
Missing or misplaced binaries surface as DllNotFoundException at first use
Containerized builds need the runtimes/ folder explicitly included in the publish output
There is no in-process fallback if the native binary fails to load

IronPDF — single-package deployment

// NuGet: Install-Package IronPdf
using IronPdf;

IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Deployed Successfully</h1>");
pdf.SaveAs("deployment-test.pdf");

IronPDF bundles platform-specific binaries inside its NuGet package and resolves them at runtime. The same package is used on Windows, Linux, macOS, Docker, Azure Functions, and AWS Lambda; whether each scenario is a fit for your project should still be validated against your environment.

API Mapping Reference

PDFium wrapper concept	IronPDF equivalent	Notes
`PdfDocument.Load(path)`	`PdfDocument.FromFile(path)`	Load from file
`PdfDocument.Load(stream)`	`PdfDocument.FromStream(stream)`	Load from stream
(wrap bytes in MemoryStream)	`PdfDocument.FromBinaryData(bytes)`	Load from bytes
`document.Render(page, w, h, dpi, dpi, flags)`	`pdf.RasterizeToImageFiles(path, DPI)`	Rasterize pages
Native DLL management	Bundled in IronPdf NuGet	Embedded Chromium / per-RID payload
`document.PageCount`	`pdf.PageCount`	Same
`document.PageSizes[i].Width/Height`	`pdf.Pages[i].Width/Height`	Per-page size in points
`document.GetPdfText(i)`	`pdf.Pages[i].Text` / `pdf.ExtractAllText()`	Per-page or whole-document
`document.Save(stream)`	`pdf.SaveAs(path)` / `pdf.Stream` / `pdf.BinaryData`	Save variants
(not available in PDFium)	`ChromePdfRenderer.RenderHtmlAsPdf`	Generate from HTML
(not available in PDFium)	`ChromePdfRenderer.RenderUrlAsPdf`	Generate from URL
(not available in free wrappers)	`PdfDocument.Merge`	Combine PDFs
(not available in free wrappers)	`pdf.Form`	AcroForm read/write
(not available in free wrappers)	`pdf.SignWithDigitalSignature`	Digital signatures
(not available in free wrappers)	`pdf.SecuritySettings`	Password / permissions

Comprehensive Feature Comparison

Feature	PDFium wrappers	IronPDF
Status
Maintenance	Community-maintained (free); commercial Patagames	Commercial, active
Breaking changes	Vary by wrapper / version	Versioned releases with migration notes
Platform support	Varies by wrapper	Cross-platform NuGet
Support
Documentation	Varies by wrapper	Documentation + API reference
Channels	GitHub issues (free); paid tiers for Patagames	Commercial support options
Enterprise SLA	Available via Patagames	Available
Content creation
HTML to PDF	None	Yes
URL to PDF	None	Yes
Generate from scratch	None	Yes
Merge PDFs	Free wrappers: no; Patagames: partial	Yes
Split PDFs	Free wrappers: no; Patagames: partial	Yes
PDF operations
Render to bitmap	Yes (core capability)	Yes (via rasterization)
Extract text	Per page (free wrappers)	Full document or per page
Extract images	SDK-dependent	Yes
Form filling	Free wrappers: no; Patagames: yes	Full AcroForm support
Digital signatures	Free wrappers: no; Patagames: yes	Yes (X.509)
Encryption	Free wrappers: no; Patagames: yes	Yes (AES 128 / 256)
Watermarks	Not built-in	Yes
Headers/footers	Not built-in	Yes
Security
Password protection	Free wrappers: read-only; Patagames: read/write	Read and write
Certificate signatures	Free wrappers: no	Yes
Redaction	Not exposed	Yes
Operational
Native binary deployment	Required (per RID)	Bundled in NuGet
x86 / x64 conflicts	Possible if process / binary mismatch	N/A
Thread safety	Verify per wrapper	Documented
Memory management	Manual disposal of native handles	Managed
Docker support	Manual native binary placement	Built-in
Development
Async / await	Wrapper-dependent	Async APIs
Dependency injection	Wrapper-dependent	Supported
Unit testing	Native dependency may complicate mocking	Standard mocking works
NuGet packages	Wrapper + per-RID native	Single, multi-target

Installation Comparison

PDFium (PdfiumViewer example):

Install-Package PdfiumViewer
# On Linux, obtain libpdfium.so (e.g. from pdfium-binaries) and place under
# runtimes/linux-x64/native/ in the publish output.

using PdfiumViewer;
// Ensure the native pdfium binary for your RID is on the load path.

IronPDF:

Install-Package IronPdf  # Single package, multi-target

using IronPdf;
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
// No additional configuration required.

Conclusion

PDFium wrappers fit a specific niche: rendering existing PDFs to bitmaps for display in viewer controls or thumbnail generation, plus per-page raw text extraction. For teams building custom PDF viewers in WinForms, WPF, or desktop apps — and willing to manage native binaries per RID — wrappers like PdfiumViewer, PdfiumViewer.Updated, PDFiumCore, or the commercial Pdfium.Net.SDK can be a good fit.

Migration to a fuller toolkit tends to make sense when:

HTML-to-PDF generation is required (reports, invoices, dynamic content)
PDF manipulation is needed beyond viewing (merge, split, forms, signatures)
Cross-platform deployment is on the roadmap (Docker, Linux, macOS) and per-RID native binary management is unwelcome
Commercial support and SLA are business requirements

IronPDF complements PDFium's strength in rendering with comprehensive PDF generation from HTML, URLs, and other sources through a Chromium rendering engine. The library covers document manipulation (merge, split, forms, encryption, signatures) and text / image extraction, and packages platform-specific binaries inside a single NuGet so consuming projects do not need to place native binaries by hand.

Have you hit "Unable to load DLL 'pdfium.dll'" errors in production? Share your PDFium wrapper troubleshooting stories in the comments.

Related resources: