How to Migrate from ExpertPdf to IronPDF in C#

The ExpertPdf Problems

1. Sparse documentation, slow cadence: Reference docs exist on html-to-pdf.net, but tutorials, feature articles, and changelog entries are infrequent. Release notes for v20.1 (April 2025) list "bug fixes and performance improvements" — no headline features.

2. Older rendering pipelines: ExpertPdf ships a Trident (IE) engine plus a "WebKit2" engine added in v12.2; modern Chromium is not the default. CSS3 features such as Flexbox, Grid, and CSS variables render best on the WebKit2 engine — verify against your target HTML before migrating large estates.

3. Premium pricing for an aging stack: Public ComponentSource listings have historically shown the HtmlToPdf Converter at roughly $550–$1,200 per tier (verify directly with the vendor — the order page on expertpdf.net was inaccessible at the time of writing).

4. Fragmented product suite: ExpertPdf sells separate packages — ExpertPdf.HtmlToPdf.NetCore / ExpertPdfHtmlToPdf, ExpertPdf.MergePdf, ExpertPdf.PdfSecurity, ExpertPdf.SplitPdf, ExpertPdf.PdfToImage, ExpertPdf.PdfCreator — each typically licensed separately.

5. No native modern .NET targets: The .NetCore packages target .NET Standard 2.0 / .NET Framework 4.6.1, so they run on .NET 5/6/7/8/9 — but you do not get native multi-target builds, trimming-friendly assemblies, or async-first APIs.

Architecture Comparison

Key Migration Benefits

1. Modern Rendering: Latest Chromium engine for pixel-perfect output
2. All-in-One Package: PDF generation, merging, security, extraction in one NuGet
3. Active Development: Monthly updates with new features and security patches
4. Better Documentation: Comprehensive tutorials and examples
5. True Cross-Platform: Windows, Linux, macOS, Docker support

Prerequisites

Ensure your environment meets these requirements:

• .NET Framework 4.6.2+ or .NET Core 3.1 / .NET 5-9
• Visual Studio 2019+ or VS Code with C# extension
• NuGet Package Manager access
• IronPDF license key (free trial available at ironpdf.com)

Audit ExpertPdf Usage

Run these commands in your solution directory to identify all ExpertPdf references:

# Find all ExpertPdf references
grep -r "ExpertPdf\|PdfConverter\|PDFMerge\|PdfSecurityManager" --include="*.cs" .

# Check NuGet packages
dotnet list package | grep -i "ExpertPdf"

# Find all ExpertPdf references
grep -r "ExpertPdf\|PdfConverter\|PDFMerge\|PdfSecurityManager" --include="*.cs" .

# Check NuGet packages
dotnet list package | grep -i "ExpertPdf"

Common ExpertPdf packages to look for (verify exact name on nuget.org — the suite uses inconsistent casing):

• ExpertPdfHtmlToPdf (.NET Framework) / ExpertPdf.HtmlToPdf.NetCore (.NET Core / 5-9) — HTML to PDF
• ExpertPdf.MergePdf — PDF merging
• ExpertPdf.PdfSecurity — encryption and passwords
• ExpertPdf.SplitPdf — PDF splitting
• ExpertPdf.PdfToImage — PDF to image conversion
• ExpertPdf.PdfCreator — full PDF SDK (drawing, forms, signatures)

Understanding the Core Pattern Change

ExpertPdf uses PdfConverter with direct byte-array return methods. IronPDF uses ChromePdfRenderer returning PdfDocument objects that provide additional manipulation capabilities before saving.

Step 1: Update NuGet Packages

Remove all ExpertPdf packages and install IronPDF:

# Remove all ExpertPdf packages (use whichever variants you have installed)
dotnet remove package ExpertPdfHtmlToPdf
dotnet remove package ExpertPdf.HtmlToPdf.NetCore
dotnet remove package ExpertPdf.MergePdf
dotnet remove package ExpertPdf.PdfSecurity
dotnet remove package ExpertPdf.SplitPdf
dotnet remove package ExpertPdf.PdfToImage
dotnet remove package ExpertPdf.PdfCreator

# Install IronPDF (includes all features)
dotnet add package IronPdf

# Remove all ExpertPdf packages (use whichever variants you have installed)
dotnet remove package ExpertPdfHtmlToPdf
dotnet remove package ExpertPdf.HtmlToPdf.NetCore
dotnet remove package ExpertPdf.MergePdf
dotnet remove package ExpertPdf.PdfSecurity
dotnet remove package ExpertPdf.SplitPdf
dotnet remove package ExpertPdf.PdfToImage
dotnet remove package ExpertPdf.PdfCreator

# Install IronPDF (includes all features)
dotnet add package IronPdf

Step 2: Update Namespace References

Replace ExpertPdf namespaces with IronPDF:

// Remove these
using ExpertPdf.HtmlToPdf;

// Add this
using IronPdf;

// Remove these
using ExpertPdf.HtmlToPdf;

// Add this
using IronPdf;

Imports IronPdf

Step 3: Configure License

ExpertPdf uses per-converter licensing. IronPDF uses a single global license:

// Add at application startup (Program.cs or Startup.cs)
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

// Add at application startup (Program.cs or Startup.cs)
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

' Add at application startup (Program.vb or Startup.vb)
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"

Core Class Mapping

Method Mapping

Options Mapping

Page Numbering Token Conversion

ExpertPdf and IronPDF use different placeholder syntax for page numbers:

HTML to PDF Conversion

The fundamental HTML to PDF conversion demonstrates the shift from ExpertPdf's byte-array pattern to IronPDF's document-object approach.

ExpertPdf Implementation:

// NuGet: Install-Package ExpertPdf.HtmlToPdf
using ExpertPdf.HtmlToPdf;
using System;

class Program
{
    static void Main()
    {
        // Create the PDF converter
        PdfConverter pdfConverter = new PdfConverter();

        // Convert HTML string to PDF
        byte[] pdfBytes = pdfConverter.GetPdfBytesFromHtmlString("<h1>Hello World</h1><p>This is a PDF document.</p>");

        // Save to file
        System.IO.File.WriteAllBytes("output.pdf", pdfBytes);

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

// NuGet: Install-Package ExpertPdf.HtmlToPdf
using ExpertPdf.HtmlToPdf;
using System;

class Program
{
    static void Main()
    {
        // Create the PDF converter
        PdfConverter pdfConverter = new PdfConverter();

        // Convert HTML string to PDF
        byte[] pdfBytes = pdfConverter.GetPdfBytesFromHtmlString("<h1>Hello World</h1><p>This is a PDF document.</p>");

        // Save to file
        System.IO.File.WriteAllBytes("output.pdf", pdfBytes);

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

Imports ExpertPdf.HtmlToPdf
Imports System

Module Program
    Sub Main()
        ' Create the PDF converter
        Dim pdfConverter As New PdfConverter()

        ' Convert HTML string to PDF
        Dim pdfBytes As Byte() = pdfConverter.GetPdfBytesFromHtmlString("<h1>Hello World</h1><p>This is a PDF document.</p>")

        ' Save to file
        System.IO.File.WriteAllBytes("output.pdf", pdfBytes)

        Console.WriteLine("PDF created successfully!")
    End Sub
End Module

IronPDF Implementation:

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

class Program
{
    static void Main()
    {
        // Create a PDF from HTML string
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1><p>This is a PDF document.</p>");

        // Save to file
        pdf.SaveAs("output.pdf");

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

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

class Program
{
    static void Main()
    {
        // Create a PDF from HTML string
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1><p>This is a PDF document.</p>");

        // Save to file
        pdf.SaveAs("output.pdf");

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

Imports IronPdf
Imports System

Class Program
    Shared Sub Main()
        ' Create a PDF from HTML string
        Dim renderer = New ChromePdfRenderer()
        Dim pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1><p>This is a PDF document.</p>")

        ' Save to file
        pdf.SaveAs("output.pdf")

        Console.WriteLine("PDF created successfully!")
    End Sub
End Class

IronPDF's approach returns a PdfDocument object, enabling additional manipulation (merging, watermarking, security) before saving. For more options, see the HTML to PDF documentation.

URL to PDF with Page Settings

ExpertPdf Implementation:

// NuGet: Install-Package ExpertPdf.HtmlToPdf
using ExpertPdf.HtmlToPdf;
using System;

class Program
{
    static void Main()
    {
        // Create the PDF converter
        PdfConverter pdfConverter = new PdfConverter();

        // Set page size and orientation
        pdfConverter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4;
        pdfConverter.PdfDocumentOptions.PdfPageOrientation = PdfPageOrientation.Portrait;

        // Convert URL to PDF
        byte[] pdfBytes = pdfConverter.GetPdfBytesFromUrl("https://www.example.com");

        // Save to file
        System.IO.File.WriteAllBytes("webpage.pdf", pdfBytes);

        Console.WriteLine("PDF from URL created successfully!");
    }
}

// NuGet: Install-Package ExpertPdf.HtmlToPdf
using ExpertPdf.HtmlToPdf;
using System;

class Program
{
    static void Main()
    {
        // Create the PDF converter
        PdfConverter pdfConverter = new PdfConverter();

        // Set page size and orientation
        pdfConverter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4;
        pdfConverter.PdfDocumentOptions.PdfPageOrientation = PdfPageOrientation.Portrait;

        // Convert URL to PDF
        byte[] pdfBytes = pdfConverter.GetPdfBytesFromUrl("https://www.example.com");

        // Save to file
        System.IO.File.WriteAllBytes("webpage.pdf", pdfBytes);

        Console.WriteLine("PDF from URL created successfully!");
    }
}

Imports ExpertPdf.HtmlToPdf
Imports System

Module Program
    Sub Main()
        ' Create the PDF converter
        Dim pdfConverter As New PdfConverter()

        ' Set page size and orientation
        pdfConverter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4
        pdfConverter.PdfDocumentOptions.PdfPageOrientation = PdfPageOrientation.Portrait

        ' Convert URL to PDF
        Dim pdfBytes As Byte() = pdfConverter.GetPdfBytesFromUrl("https://www.example.com")

        ' Save to file
        System.IO.File.WriteAllBytes("webpage.pdf", pdfBytes)

        Console.WriteLine("PDF from URL created successfully!")
    End Sub
End Module

IronPDF Implementation:

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

class Program
{
    static void Main()
    {
        // Create a PDF renderer
        var renderer = new ChromePdfRenderer();

        // Set page size and orientation
        renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;
        renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Portrait;

        // Convert URL to PDF
        var pdf = renderer.RenderUrlAsPdf("https://www.example.com");

        // Save to file
        pdf.SaveAs("webpage.pdf");

        Console.WriteLine("PDF from URL created successfully!");
    }
}

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

class Program
{
    static void Main()
    {
        // Create a PDF renderer
        var renderer = new ChromePdfRenderer();

        // Set page size and orientation
        renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;
        renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Portrait;

        // Convert URL to PDF
        var pdf = renderer.RenderUrlAsPdf("https://www.example.com");

        // Save to file
        pdf.SaveAs("webpage.pdf");

        Console.WriteLine("PDF from URL created successfully!");
    }
}

Imports IronPdf
Imports System

Class Program
    Shared Sub Main()
        ' Create a PDF renderer
        Dim renderer = New ChromePdfRenderer()

        ' Set page size and orientation
        renderer.RenderingOptions.PaperSize = PdfPaperSize.A4
        renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Portrait

        ' Convert URL to PDF
        Dim pdf = renderer.RenderUrlAsPdf("https://www.example.com")

        ' Save to file
        pdf.SaveAs("webpage.pdf")

        Console.WriteLine("PDF from URL created successfully!")
    End Sub
End Class

IronPDF's RenderingOptions provides direct property access for page configuration. For more options, see the URL to PDF documentation.

Headers and Footers with Page Numbers

This example demonstrates the critical difference in header/footer configuration—ExpertPdf uses separate PdfHeaderOptions and PdfFooterOptions classes with &p;/&P; tokens, while IronPDF uses TextHeaderFooter with {page}/{total-pages} placeholders.

ExpertPdf Implementation:

// NuGet: Install-Package ExpertPdf.HtmlToPdf
using ExpertPdf.HtmlToPdf;
using System;

class Program
{
    static void Main()
    {
        // Create the PDF converter
        PdfConverter pdfConverter = new PdfConverter();

        // Enable header
        pdfConverter.PdfHeaderOptions.ShowHeader = true;
        pdfConverter.PdfHeaderOptions.HeaderText = "Document Header";
        pdfConverter.PdfHeaderOptions.HeaderTextAlignment = HorizontalTextAlign.Center;

        // Enable footer with page numbers
        pdfConverter.PdfFooterOptions.ShowFooter = true;
        pdfConverter.PdfFooterOptions.FooterText = "Page &p; of &P;";
        pdfConverter.PdfFooterOptions.FooterTextAlignment = HorizontalTextAlign.Right;

        // Convert HTML file to PDF
        byte[] pdfBytes = pdfConverter.GetPdfBytesFromHtmlFile("input.html");

        // Save to file
        System.IO.File.WriteAllBytes("output-with-header-footer.pdf", pdfBytes);

        Console.WriteLine("PDF with headers and footers created successfully!");
    }
}

// NuGet: Install-Package ExpertPdf.HtmlToPdf
using ExpertPdf.HtmlToPdf;
using System;

class Program
{
    static void Main()
    {
        // Create the PDF converter
        PdfConverter pdfConverter = new PdfConverter();

        // Enable header
        pdfConverter.PdfHeaderOptions.ShowHeader = true;
        pdfConverter.PdfHeaderOptions.HeaderText = "Document Header";
        pdfConverter.PdfHeaderOptions.HeaderTextAlignment = HorizontalTextAlign.Center;

        // Enable footer with page numbers
        pdfConverter.PdfFooterOptions.ShowFooter = true;
        pdfConverter.PdfFooterOptions.FooterText = "Page &p; of &P;";
        pdfConverter.PdfFooterOptions.FooterTextAlignment = HorizontalTextAlign.Right;

        // Convert HTML file to PDF
        byte[] pdfBytes = pdfConverter.GetPdfBytesFromHtmlFile("input.html");

        // Save to file
        System.IO.File.WriteAllBytes("output-with-header-footer.pdf", pdfBytes);

        Console.WriteLine("PDF with headers and footers created successfully!");
    }
}

Imports ExpertPdf.HtmlToPdf
Imports System

Class Program
    Shared Sub Main()
        ' Create the PDF converter
        Dim pdfConverter As New PdfConverter()

        ' Enable header
        pdfConverter.PdfHeaderOptions.ShowHeader = True
        pdfConverter.PdfHeaderOptions.HeaderText = "Document Header"
        pdfConverter.PdfHeaderOptions.HeaderTextAlignment = HorizontalTextAlign.Center

        ' Enable footer with page numbers
        pdfConverter.PdfFooterOptions.ShowFooter = True
        pdfConverter.PdfFooterOptions.FooterText = "Page &p; of &P;"
        pdfConverter.PdfFooterOptions.FooterTextAlignment = HorizontalTextAlign.Right

        ' Convert HTML file to PDF
        Dim pdfBytes As Byte() = pdfConverter.GetPdfBytesFromHtmlFile("input.html")

        ' Save to file
        System.IO.File.WriteAllBytes("output-with-header-footer.pdf", pdfBytes)

        Console.WriteLine("PDF with headers and footers created successfully!")
    End Sub
End Class

IronPDF Implementation:

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

class Program
{
    static void Main()
    {
        // Create a PDF renderer
        var renderer = new ChromePdfRenderer();

        // Configure header
        renderer.RenderingOptions.TextHeader = new TextHeaderFooter()
        {
            CenterText = "Document Header",
            DrawDividerLine = true
        };

        // Configure footer with page numbers
        renderer.RenderingOptions.TextFooter = new TextHeaderFooter()
        {
            RightText = "Page {page} of {total-pages}",
            DrawDividerLine = true
        };

        // Convert HTML file to PDF
        var pdf = renderer.RenderHtmlFileAsPdf("input.html");

        // Save to file
        pdf.SaveAs("output-with-header-footer.pdf");

        Console.WriteLine("PDF with headers and footers created successfully!");
    }
}

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

class Program
{
    static void Main()
    {
        // Create a PDF renderer
        var renderer = new ChromePdfRenderer();

        // Configure header
        renderer.RenderingOptions.TextHeader = new TextHeaderFooter()
        {
            CenterText = "Document Header",
            DrawDividerLine = true
        };

        // Configure footer with page numbers
        renderer.RenderingOptions.TextFooter = new TextHeaderFooter()
        {
            RightText = "Page {page} of {total-pages}",
            DrawDividerLine = true
        };

        // Convert HTML file to PDF
        var pdf = renderer.RenderHtmlFileAsPdf("input.html");

        // Save to file
        pdf.SaveAs("output-with-header-footer.pdf");

        Console.WriteLine("PDF with headers and footers created successfully!");
    }
}

Imports IronPdf
Imports System

Class Program
    Shared Sub Main()
        ' Create a PDF renderer
        Dim renderer = New ChromePdfRenderer()

        ' Configure header
        renderer.RenderingOptions.TextHeader = New TextHeaderFooter() With {
            .CenterText = "Document Header",
            .DrawDividerLine = True
        }

        ' Configure footer with page numbers
        renderer.RenderingOptions.TextFooter = New TextHeaderFooter() With {
            .RightText = "Page {page} of {total-pages}",
            .DrawDividerLine = True
        }

        ' Convert HTML file to PDF
        Dim pdf = renderer.RenderHtmlFileAsPdf("input.html")

        ' Save to file
        pdf.SaveAs("output-with-header-footer.pdf")

        Console.WriteLine("PDF with headers and footers created successfully!")
    End Sub
End Class

IronPDF's TextHeaderFooter provides LeftText, CenterText, and RightText properties with optional divider lines. For HTML-based headers, use HtmlHeaderFooter. For more options, see the headers and footers documentation.

License Key Location

ExpertPdf uses per-converter licensing. IronPDF uses a single global license set once at startup:

// ExpertPdf - per converter
pdfConverter.LicenseKey = "EXPERTPDF-LICENSE";

// IronPDF - global, set once
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

// ExpertPdf - per converter
pdfConverter.LicenseKey = "EXPERTPDF-LICENSE";

// IronPDF - global, set once
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

' ExpertPdf - per converter
pdfConverter.LicenseKey = "EXPERTPDF-LICENSE"

' IronPDF - global, set once
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"

Page Numbering Token Conversion

Replace ExpertPdf tokens with IronPDF placeholders:

// ExpertPdf
"Page &p; of &P;"

// IronPDF
"Page {page} of {total-pages}"

// ExpertPdf
"Page &p; of &P;"

// IronPDF
"Page {page} of {total-pages}"

Fragmented Packages Consolidated

ExpertPdf's separate packages (PDFMerge, PDFSecurity, PDFSplit, PdfToImage) are all included in IronPDF's single package:

// ExpertPdf - requires separate ExpertPdf.MergePdf package
PDFMerge merger = new PDFMerge();
merger.AppendPDFFile("file1.pdf");
merger.AppendPDFFile("file2.pdf");
merger.SaveMergedPDFToFile("merged.pdf");

// IronPDF - included in main package
var pdf1 = PdfDocument.FromFile("file1.pdf");
var pdf2 = PdfDocument.FromFile("file2.pdf");
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("merged.pdf");

// ExpertPdf - requires separate ExpertPdf.MergePdf package
PDFMerge merger = new PDFMerge();
merger.AppendPDFFile("file1.pdf");
merger.AppendPDFFile("file2.pdf");
merger.SaveMergedPDFToFile("merged.pdf");

// IronPDF - included in main package
var pdf1 = PdfDocument.FromFile("file1.pdf");
var pdf2 = PdfDocument.FromFile("file2.pdf");
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("merged.pdf");

' ExpertPdf - requires separate ExpertPdf.MergePdf package
Dim merger As New PDFMerge()
merger.AppendPDFFile("file1.pdf")
merger.AppendPDFFile("file2.pdf")
merger.SaveMergedPDFToFile("merged.pdf")

' IronPDF - included in main package
Dim pdf1 = PdfDocument.FromFile("file1.pdf")
Dim pdf2 = PdfDocument.FromFile("file2.pdf")
Dim merged = PdfDocument.Merge(pdf1, pdf2)
merged.SaveAs("merged.pdf")

For more merging options, see the PDF merging documentation.

Custom Page Sizes

ExpertPdf uses points. IronPDF uses millimeters. Convert: points / 72 * 25.4 = mm