DEV Community

IronSoftware
IronSoftware

Posted on

From pdforge to IronPDF: what actually changes in your code

#dotnet #csharp

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

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

Troubleshooting: security patch version pins

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

Step 1: Understand what changed in the newer version 

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

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

# Alternatively:
# Browse https://www.nuget.org/packages/pdforge
Enter fullscreen mode Exit fullscreen mode

Step 2: Assess the breaking change scope in your codebase 

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

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

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

Step 3: Make the upgrade vs migrate decision

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

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

Why migrate (without drama)

Eight neutral reasons the version pin analysis tips toward migration:

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

Comparison table

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

Migration complexity assessment

Effort by feature

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

Decision matrix

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

Before you start

Prerequisites

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

Find pdforge references in your codebase 

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

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

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

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

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

Remove pdforge, install IronPDF 

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

# Install IronPDF
dotnet add package IronPdf
dotnet restore
Enter fullscreen mode Exit fullscreen mode

Quick start migration (3 steps)

Step 1: License configuration

Before (pdforge — verify license setup):

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

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

After (IronPDF):

using IronPdf;

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

Step 2: Namespace imports

Before:

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

After:

using IronPdf;
using IronPdf.Rendering;
using IronPdf.Editing;
using IronPdf.Security;
Enter fullscreen mode Exit fullscreen mode

Step 3: Basic HTML-to-PDF

Before (pdforge — verify all API names):

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

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

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

        Console.WriteLine("Replace with verified pdforge API");
    }
}
Enter fullscreen mode Exit fullscreen mode

After (IronPDF):

using IronPdf;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

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

Troubleshooting: the watermark breaking change specifically

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

IronPDF watermark API (stable) 

using IronPdf;
using IronPdf.Editing;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

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

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

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

Apply to specific pages only 

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

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

Troubleshooting: API surface mapping when pdforge docs are unclear

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

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

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

Map each call site systematically before writing migration code:

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

API mapping tables

Namespace mapping

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

Core class mapping

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

Document loading methods

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

Page operations

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

Merge/split operations

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

Four complete before/after migrations

1. HTML to PDF

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

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

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

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

        Console.WriteLine("Replace with verified pdforge API");
    }
}
Enter fullscreen mode Exit fullscreen mode

After (IronPDF):

using IronPdf;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

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

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

2. Merge PDFs

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

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

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

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

        output.Save("merged.pdf");
        Console.WriteLine("Merged.");
    }
}
Enter fullscreen mode Exit fullscreen mode

After (IronPDF):

using IronPdf;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

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

3. Watermark (the breaking-change module)

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

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

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

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

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

After (IronPDF — stable watermark API):

using IronPdf;
using IronPdf.Editing;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

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

4. Password protection

Before (pdforge — verify security API):

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

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

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

        Console.WriteLine("Replace with verified pdforge security API");
    }
}
Enter fullscreen mode Exit fullscreen mode

After (IronPDF):

using IronPdf;
using IronPdf.Security;

IronPdf.License.LicenseKey = "YOUR_LICENSE_KEY";

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

Critical migration notes

Page indexing

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

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

Output model

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

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

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

Error handling

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

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

Performance considerations

Renderer reuse 

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

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

Async 

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

Edge cases worth flagging

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

Migration checklist

Pre-migration

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

Code migration

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

Testing

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

Post-migration

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

Wrapping Up

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

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

Top comments (0)