How to Migrate from PrinceXML to IronPDF in C#

Understanding PrinceXML

PrinceXML is a sophisticated tool designed to excel at converting HTML content into print-perfect PDF documents through its dedicated support for CSS Paged Media specifications. This specialization allows PrinceXML to render documents with high fidelity to intended print designs—a valuable attribute for industries requiring detailed print styling, like publishing or legal documentation.

However, PrinceXML is not a .NET library and operates as a separate command-line tool, which may complicate integration for environments that prefer pure .NET solutions. Its reliance on a separate server process involves additional system resource management and potentially increased complexity for project deployments.

The External Process Problem

PrinceXML operates as a separate command-line executable that creates significant architectural challenges for .NET applications:

1. Process Management Overhead: Must spawn, monitor, and terminate external processes.

2. No Native .NET Integration: Communicate via stdin/stdout or temporary files.

3. Deployment Complexity: Requires Prince installation on every server.

4. Licensing Per Server: Each deployment needs a separate license ($495+).

5. Error Handling Difficulty: Parse text output for error detection.

6. No Async/Await: Blocking calls or complex async wrappers required.

7. Path Dependencies: Must locate Prince executable on PATH or absolute path.

PrinceXML vs IronPDF Comparison

IronPDF provides an alternative with its .NET native capabilities, extending beyond mere HTML-to-PDF conversion to include advanced PDF manipulation tasks, such as editing, merging, and digital signatures. IronPDF's API is designed for simplicity and ease of use, letting developers perform conversions and manipulations with minimal boilerplate code.

For teams planning .NET 10 and C# 14 adoption through 2025 and 2026, IronPDF's seamless deployment requires no external dependencies or server processes and thus eases the burden of integration into the .NET framework.

Prerequisites

1. .NET Environment: .NET Framework 4.6.2+ or .NET Core 3.1+ / .NET 5/6/7/8/9+
2. NuGet Access: Ability to install NuGet packages
3. IronPDF License: Obtain your license key from ironpdf.com

NuGet Package Changes

# Install IronPDF
dotnet add package IronPdf

# Remove Prince wrapper if using one
dotnet remove package PrinceXMLWrapper

# Install IronPDF
dotnet add package IronPdf

# Remove Prince wrapper if using one
dotnet remove package PrinceXMLWrapper

License Configuration

// Add at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

// Add at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

' Add at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"

Search for PrinceXML Usage

# Find Prince process calls
grep -r "prince" --include="*.cs" .
grep -r "Process.Start" --include="*.cs" . | grep -i prince
grep -r "@page" --include="*.css" .
grep -r "prince-" --include="*.css" .

# Find Prince process calls
grep -r "prince" --include="*.cs" .
grep -r "Process.Start" --include="*.cs" . | grep -i prince
grep -r "@page" --include="*.css" .
grep -r "prince-" --include="*.css" .

Namespace Changes

// Before: PrinceXML
using PrinceXMLWrapper;
using System.Diagnostics;
using System.IO;

// After: IronPDF
using IronPdf;

// Before: PrinceXML
using PrinceXMLWrapper;
using System.Diagnostics;
using System.IO;

// After: IronPDF
using IronPdf;

' Before: PrinceXML
Imports PrinceXMLWrapper
Imports System.Diagnostics
Imports System.IO

' After: IronPDF
Imports IronPdf

Command-Line to Method Mapping

CSS @page to RenderingOptions Mapping

Page Size Conversions

Example 1: HTML File to PDF Conversion

Before (PrinceXML):

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

class Program
{
    static void Main()
    {
        Prince prince = new Prince("C:\\Program Files\\Prince\\engine\\bin\\prince.exe");
        prince.Convert("input.html", "output.pdf");
        Console.WriteLine("PDF created successfully");
    }
}

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

class Program
{
    static void Main()
    {
        Prince prince = new Prince("C:\\Program Files\\Prince\\engine\\bin\\prince.exe");
        prince.Convert("input.html", "output.pdf");
        Console.WriteLine("PDF created successfully");
    }
}

Imports PrinceXMLWrapper
Imports System

Module Program
    Sub Main()
        Dim prince As New Prince("C:\Program Files\Prince\engine\bin\prince.exe")
        prince.Convert("input.html", "output.pdf")
        Console.WriteLine("PDF created successfully")
    End Sub
End Module

After (IronPDF):

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

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlFileAsPdf("input.html");
        pdf.SaveAs("output.pdf");
        Console.WriteLine("PDF created successfully");
    }
}

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

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlFileAsPdf("input.html");
        pdf.SaveAs("output.pdf");
        Console.WriteLine("PDF created successfully");
    }
}

Imports IronPdf
Imports System

Class Program
    Shared Sub Main()
        Dim renderer = New ChromePdfRenderer()
        Dim pdf = renderer.RenderHtmlFileAsPdf("input.html")
        pdf.SaveAs("output.pdf")
        Console.WriteLine("PDF created successfully")
    End Sub
End Class

This example demonstrates the fundamental architectural difference. PrinceXML requires instantiating a Prince object with the full path to the executable ("C:\\Program Files\\Prince\\engine\\bin\\prince.exe"), then calling Convert() with input and output paths.

IronPDF eliminates path dependencies entirely: create a ChromePdfRenderer, call RenderHtmlFileAsPdf() with the HTML file path, and SaveAs() to write the result. No executable paths, no process management, no path dependencies. See the HTML to PDF documentation for comprehensive examples.

Example 2: URL to PDF Conversion with Options

Before (PrinceXML):

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

class Program
{
    static void Main()
    {
        Prince prince = new Prince("C:\\Program Files\\Prince\\engine\\bin\\prince.exe");
        prince.SetJavaScript(true);
        prince.SetEncrypt(true);
        prince.SetPDFTitle("Website Export");
        prince.Convert("https://example.com", "webpage.pdf");
        Console.WriteLine("URL converted to PDF");
    }
}

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

class Program
{
    static void Main()
    {
        Prince prince = new Prince("C:\\Program Files\\Prince\\engine\\bin\\prince.exe");
        prince.SetJavaScript(true);
        prince.SetEncrypt(true);
        prince.SetPDFTitle("Website Export");
        prince.Convert("https://example.com", "webpage.pdf");
        Console.WriteLine("URL converted to PDF");
    }
}

Imports PrinceXMLWrapper
Imports System

Class Program
    Shared Sub Main()
        Dim prince As New Prince("C:\Program Files\Prince\engine\bin\prince.exe")
        prince.SetJavaScript(True)
        prince.SetEncrypt(True)
        prince.SetPDFTitle("Website Export")
        prince.Convert("https://example.com", "webpage.pdf")
        Console.WriteLine("URL converted to PDF")
    End Sub
End Class

After (IronPDF):

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

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.EnableJavaScript = true;
        renderer.RenderingOptions.PdfTitle = "Website Export";

        var pdf = renderer.RenderUrlAsPdf("https://example.com");
        pdf.Encrypt("password");
        pdf.SaveAs("webpage.pdf");
        Console.WriteLine("URL converted to PDF");
    }
}

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

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.EnableJavaScript = true;
        renderer.RenderingOptions.PdfTitle = "Website Export";

        var pdf = renderer.RenderUrlAsPdf("https://example.com");
        pdf.Encrypt("password");
        pdf.SaveAs("webpage.pdf");
        Console.WriteLine("URL converted to PDF");
    }
}

Imports IronPdf
Imports System

Class Program
    Shared Sub Main()
        Dim renderer = New ChromePdfRenderer()
        renderer.RenderingOptions.EnableJavaScript = True
        renderer.RenderingOptions.PdfTitle = "Website Export"

        Dim pdf = renderer.RenderUrlAsPdf("https://example.com")
        pdf.Encrypt("password")
        pdf.SaveAs("webpage.pdf")
        Console.WriteLine("URL converted to PDF")
    End Sub
End Class

This example shows how PrinceXML options map to IronPDF properties. PrinceXML uses setter methods (SetJavaScript(), SetEncrypt(), SetPDFTitle()) before conversion. IronPDF uses RenderingOptions properties for pre-render settings, and post-render methods like Encrypt() on the PdfDocument object.

Key mappings:

• prince.SetJavaScript(true) → renderer.RenderingOptions.EnableJavaScript = true
• prince.SetPDFTitle("...") → renderer.RenderingOptions.PdfTitle = "..."
• prince.SetEncrypt(true) → pdf.Encrypt("password") (IronPDF requires a password)

Learn more in our tutorials.

Example 3: HTML String to PDF Conversion

Before (PrinceXML):

// NuGet: Install-Package PrinceXMLWrapper
using PrinceXMLWrapper;
using System;
using System.IO;

class Program
{
    static void Main()
    {
        string html = "<html><head><style>body { font-family: Arial; color: blue; }</style></head><body><h1>Hello World</h1></body></html>";
        File.WriteAllText("temp.html", html);

        Prince prince = new Prince("C:\\Program Files\\Prince\\engine\\bin\\prince.exe");
        prince.Convert("temp.html", "styled-output.pdf");
        Console.WriteLine("Styled PDF created");
    }
}

// NuGet: Install-Package PrinceXMLWrapper
using PrinceXMLWrapper;
using System;
using System.IO;

class Program
{
    static void Main()
    {
        string html = "<html><head><style>body { font-family: Arial; color: blue; }</style></head><body><h1>Hello World</h1></body></html>";
        File.WriteAllText("temp.html", html);

        Prince prince = new Prince("C:\\Program Files\\Prince\\engine\\bin\\prince.exe");
        prince.Convert("temp.html", "styled-output.pdf");
        Console.WriteLine("Styled PDF created");
    }
}

Imports PrinceXMLWrapper
Imports System
Imports System.IO

Module Program
    Sub Main()
        Dim html As String = "<html><head><style>body { font-family: Arial; color: blue; }</style></head><body><h1>Hello World</h1></body></html>"
        File.WriteAllText("temp.html", html)

        Dim prince As New Prince("C:\Program Files\Prince\engine\bin\prince.exe")
        prince.Convert("temp.html", "styled-output.pdf")
        Console.WriteLine("Styled PDF created")
    End Sub
End Module

After (IronPDF):

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

class Program
{
    static void Main()
    {
        string html = "<html><head><style>body { font-family: Arial; color: blue; }</style></head><body><h1>Hello World</h1></body></html>";

        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("styled-output.pdf");
        Console.WriteLine("Styled PDF created");
    }
}

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

class Program
{
    static void Main()
    {
        string html = "<html><head><style>body { font-family: Arial; color: blue; }</style></head><body><h1>Hello World</h1></body></html>";

        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("styled-output.pdf");
        Console.WriteLine("Styled PDF created");
    }
}

Imports IronPdf
Imports System

Class Program
    Shared Sub Main()
        Dim html As String = "<html><head><style>body { font-family: Arial; color: blue; }</style></head><body><h1>Hello World</h1></body></html>"

        Dim renderer = New ChromePdfRenderer()
        Dim pdf = renderer.RenderHtmlAsPdf(html)
        pdf.SaveAs("styled-output.pdf")
        Console.WriteLine("Styled PDF created")
    End Sub
End Class

This example highlights a critical difference: PrinceXML requires file input, so you must create a temporary file (File.WriteAllText("temp.html", html)) before conversion. IronPDF's RenderHtmlAsPdf() accepts HTML strings directly—no temporary files, no cleanup code, no disk I/O overhead.

Common CSS Migration Issues

Issue 1: CSS @page Not Working

IronPDF uses Chromium, which has limited @page support. Convert CSS rules to RenderingOptions.

Issue 2: Page Margin Boxes Missing

CSS margin boxes (@top-center, @bottom-right) are Prince-specific. Use HtmlHeader/HtmlFooter instead.

Issue 3: string-set/content Not Working

The string-set CSS property is Prince-specific. Use {html-title} placeholder from the <title> tag:

<title>Chapter 1: Introduction</title>

<title>Chapter 1: Introduction</title>

renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = "<div>{html-title}</div>"
};

renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = "<div>{html-title}</div>"
};

Issue 4: counter(pages) Incorrect

Use IronPDF's {total-pages} placeholder instead of CSS counters.

PDF Merging

var pdf1 = PdfDocument.FromFile("chapter1.pdf");
var pdf2 = PdfDocument.FromFile("chapter2.pdf");
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("complete_book.pdf");

var pdf1 = PdfDocument.FromFile("chapter1.pdf");
var pdf2 = PdfDocument.FromFile("chapter2.pdf");
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("complete_book.pdf");

Dim pdf1 = PdfDocument.FromFile("chapter1.pdf")
Dim pdf2 = PdfDocument.FromFile("chapter2.pdf")
Dim merged = PdfDocument.Merge(pdf1, pdf2)
merged.SaveAs("complete_book.pdf")

Watermarks

pdf.ApplyWatermark("<h1 style='color:red; opacity:0.3;'>DRAFT</h1>");

pdf.ApplyWatermark("<h1 style='color:red; opacity:0.3;'>DRAFT</h1>");

IRON VB CONVERTER ERROR developers@ironsoftware.com

Digital Signatures

var signature = new PdfSignature("certificate.pfx", "password");
pdf.Sign(signature);

var signature = new PdfSignature("certificate.pfx", "password");
pdf.Sign(signature);

Dim signature = New PdfSignature("certificate.pfx", "password")
pdf.Sign(signature)

Form Filling

var pdf = PdfDocument.FromFile("form.pdf");
pdf.Form.GetFieldByName("Name").Value = "John Doe";
pdf.SaveAs("filled_form.pdf");

var pdf = PdfDocument.FromFile("form.pdf");
pdf.Form.GetFieldByName("Name").Value = "John Doe";
pdf.SaveAs("filled_form.pdf");

Dim pdf = PdfDocument.FromFile("form.pdf")
pdf.Form.GetFieldByName("Name").Value = "John Doe"
pdf.SaveAs("filled_form.pdf")

Pre-Migration

• Identify all Prince command-line invocations
• Document CSS @page rules used
• List Prince-specific CSS properties (prince-*, string-set)
• Note any Prince JavaScript functions
• Identify PDF features used (encryption, metadata)
• Obtain IronPDF license key from ironpdf.com

Code Changes

• Remove PrinceXMLWrapper NuGet package
• Install IronPdf NuGet package
• Update namespace imports
• Replace Prince instantiation with ChromePdfRenderer
• Replace prince.Convert() with RenderHtmlFileAsPdf() or RenderHtmlAsPdf()
• Convert setter methods to RenderingOptions properties
• Migrate @page CSS to RenderingOptions
• Replace margin boxes with HtmlHeader/HtmlFooter
• Convert CSS counters to {page}/{total-pages} placeholders
• Remove temporary file handling for HTML strings
• Add license initialization at application startup

Post-Migration

• Test HTML file conversion
• Test HTML string conversion
• Test URL conversion
• Verify page sizes match
• Verify margins match
• Test headers and footers
• Verify page numbers
• Test encryption/security
• Remove Prince installation from servers
• Update deployment scripts