How to Migrate from XFINIUM.PDF to IronPDF in C#
XFINIUM.PDF is a commercial cross-platform PDF library, developed by O2 Solutions, that offers tools for creating and editing PDFs programmatically in C#. It ships two editions — Generator (PDF generation and editing) and Viewer (Generator features plus rendering/display). The library is distributed on NuGet as Xfinium.Pdf.NetStandard and Xfinium.Pdf.NetCore. Its coordinate-based graphics programming model can create friction for teams building document-heavy applications, since most layout work involves manually positioning elements using pixel coordinates.
This guide provides a migration path from XFINIUM.PDF to IronPDF, with step-by-step instructions, code comparisons, and practical examples for .NET developers evaluating this transition.
Why Migrate from XFINIUM.PDF
XFINIUM.PDF is a low-level PDF library that relies on coordinate-based graphics programming, which means developers position most elements on the page directly. Common reasons development teams consider migration include:
No native HTML engine: XFINIUM.PDF has no built-in HTML-to-PDF converter. The vendor ships a sample XHTML walker that supports a limited tag set (p, font, b, i, u, ul, li) and does not parse CSS or execute JavaScript, which may not suffice for projects requiring full HTML-to-PDF capabilities.
Coordinate-Based API: Manual positioning with pixel coordinates like DrawString("text", font, brush, 50, 100) is required for most element placement.
Manual Font Management: Font objects must be created and managed explicitly using classes like PdfStandardFont and PdfBrush.
No CSS Styling: No support for modern web styling. Colors, fonts, and layouts are handled through programmatic method calls.
No JavaScript Rendering: Static content only. XFINIUM.PDF does not render dynamic web content or execute JavaScript.
Complex Text Layout: Manual text measurement and wrapping calculations are typically required for anything beyond simple single-line text.
Smaller community: Fewer community-provided examples and tutorials compared to mainstream solutions, which can make it harder for new users to get started.
The Core Problem: Graphics API vs HTML
XFINIUM.PDF forces you to think like a graphics programmer, not a document designer:
// XFINIUM.PDF: Position every element manually
page.Graphics.DrawString("Invoice", titleFont, titleBrush, 50, 50);
page.Graphics.DrawString("Customer:", labelFont, brush, 50, 80);
page.Graphics.DrawString(customer.Name, valueFont, brush, 120, 80);
// ... hundreds of lines for a simple document
// XFINIUM.PDF: Position every element manually
page.Graphics.DrawString("Invoice", titleFont, titleBrush, 50, 50);
page.Graphics.DrawString("Customer:", labelFont, brush, 50, 80);
page.Graphics.DrawString(customer.Name, valueFont, brush, 120, 80);
// ... hundreds of lines for a simple document
' XFINIUM.PDF: Position every element manually
page.Graphics.DrawString("Invoice", titleFont, titleBrush, 50, 50)
page.Graphics.DrawString("Customer:", labelFont, brush, 50, 80)
page.Graphics.DrawString(customer.Name, valueFont, brush, 120, 80)
' ... hundreds of lines for a simple document
IronPDF uses familiar HTML/CSS:
// IronPDF: Declarative HTML
var html = @"<h1>Invoice</h1><p><b>Customer:</b> " + customer.Name + "</p>";
var pdf = renderer.RenderHtmlAsPdf(html);
// IronPDF: Declarative HTML
var html = @"<h1>Invoice</h1><p><b>Customer:</b> " + customer.Name + "</p>";
var pdf = renderer.RenderHtmlAsPdf(html);
' IronPDF: Declarative HTML
Dim html As String = "<h1>Invoice</h1><p><b>Customer:</b> " & customer.Name & "</p>"
Dim pdf = renderer.RenderHtmlAsPdf(html)
IronPDF vs XFINIUM.PDF: Feature Comparison
Understanding the architectural differences helps technical decision-makers evaluate the migration investment:
| Feature | XFINIUM.PDF | IronPDF |
|---|---|---|
| HTML to PDF | No native engine; sample-only XHTML converter (limited tags, no CSS/JS) | Full HTML-to-PDF conversion with Chromium (CSS3 + JavaScript) |
| Community & Support | Smaller community, fewer online resources available | Large community with extensive documentation and tutorials |
| License | Commercial with developer-based licensing | Commercial |
| Cross-Platform Support | Strong cross-platform capabilities | Also supports cross-platform operations |
| CSS Support | No | Full CSS3 |
| JavaScript | No | Full ES2024 |
| Flexbox/Grid | No | Yes |
| Automatic Layout | No | Yes |
| Automatic Page Breaks | No | Yes |
| Manual Positioning | Required | Optional (CSS positioning) |
| Learning Curve | High (coordinate system) | Low (HTML/CSS) |
| Code Verbosity | Very High | Low |
Quick Start: XFINIUM.PDF to IronPDF Migration
The migration can begin immediately with these foundational steps.
Step 1: Replace NuGet Package
Remove XFINIUM.PDF (the actual NuGet IDs are platform-specific):
# Remove XFINIUM.PDF
dotnet remove package Xfinium.Pdf.NetStandard
# or: dotnet remove package Xfinium.Pdf.NetCore
# Remove XFINIUM.PDF
dotnet remove package Xfinium.Pdf.NetStandard
# or: dotnet remove package Xfinium.Pdf.NetCore
Install IronPDF:
# Install IronPDF
dotnet add package IronPdf
# Install IronPDF
dotnet add package IronPdf
Step 2: Update Namespaces
Replace XFINIUM.PDF namespaces with the IronPDF namespace:
// Before (XFINIUM.PDF)
using Xfinium.Pdf;
using Xfinium.Pdf.Graphics;
using Xfinium.Pdf.Content;
using Xfinium.Pdf.FlowDocument;
// After (IronPDF)
using IronPdf;
// Before (XFINIUM.PDF)
using Xfinium.Pdf;
using Xfinium.Pdf.Graphics;
using Xfinium.Pdf.Content;
using Xfinium.Pdf.FlowDocument;
// After (IronPDF)
using IronPdf;
Imports IronPdf
Step 3: Initialize License
Add license initialization at application startup:
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"
Code Migration Examples
Converting HTML to PDF
The most fundamental operation reveals the complexity difference between these .NET PDF libraries.
XFINIUM.PDF Approach:
// NuGet: Install-Package Xfinium.Pdf.NetStandard (or .NetCore)
// XFINIUM.PDF has no native HTML-to-PDF engine. Flow content accepts
// styled text, headings, tables and images - not HTML. The vendor sample
// converter parses limited XHTML (p, font, b, i, u, ul, li) into
// PdfFormattedContent; full CSS/JS rendering is not supported.
using Xfinium.Pdf;
using Xfinium.Pdf.FlowDocument;
using Xfinium.Pdf.Graphics;
using System.IO;
class Program
{
static void Main()
{
PdfFlowDocument flowDocument = new PdfFlowDocument();
flowDocument.AddContent(new PdfFlowHeadingContent(
"Hello World",
new PdfStandardFont(PdfStandardFontFace.HelveticaBold, 18)));
flowDocument.AddContent(new PdfFlowTextContent(
"This is a PDF generated from text content (not HTML).",
new PdfStandardFont(PdfStandardFontFace.Helvetica, 12)));
using (FileStream fs = new FileStream("output.pdf", FileMode.Create))
{
flowDocument.Save(fs);
}
}
}
// NuGet: Install-Package Xfinium.Pdf.NetStandard (or .NetCore)
// XFINIUM.PDF has no native HTML-to-PDF engine. Flow content accepts
// styled text, headings, tables and images - not HTML. The vendor sample
// converter parses limited XHTML (p, font, b, i, u, ul, li) into
// PdfFormattedContent; full CSS/JS rendering is not supported.
using Xfinium.Pdf;
using Xfinium.Pdf.FlowDocument;
using Xfinium.Pdf.Graphics;
using System.IO;
class Program
{
static void Main()
{
PdfFlowDocument flowDocument = new PdfFlowDocument();
flowDocument.AddContent(new PdfFlowHeadingContent(
"Hello World",
new PdfStandardFont(PdfStandardFontFace.HelveticaBold, 18)));
flowDocument.AddContent(new PdfFlowTextContent(
"This is a PDF generated from text content (not HTML).",
new PdfStandardFont(PdfStandardFontFace.Helvetica, 12)));
using (FileStream fs = new FileStream("output.pdf", FileMode.Create))
{
flowDocument.Save(fs);
}
}
}
Imports Xfinium.Pdf
Imports Xfinium.Pdf.FlowDocument
Imports Xfinium.Pdf.Graphics
Imports System.IO
Module Program
Sub Main()
Dim flowDocument As New PdfFlowDocument()
flowDocument.AddContent(New PdfFlowHeadingContent(
"Hello World",
New PdfStandardFont(PdfStandardFontFace.HelveticaBold, 18)))
flowDocument.AddContent(New PdfFlowTextContent(
"This is a PDF generated from text content (not HTML).",
New PdfStandardFont(PdfStandardFontFace.Helvetica, 12)))
Using fs As New FileStream("output.pdf", FileMode.Create)
flowDocument.Save(fs)
End Using
End Sub
End Module
IronPDF Approach:
// NuGet: Install-Package IronPdf
using IronPdf;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
string html = "<html><body><h1>Hello World</h1><p>This is a PDF from HTML.</p></body></html>";
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");
}
}
// NuGet: Install-Package IronPdf
using IronPdf;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
string html = "<html><body><h1>Hello World</h1><p>This is a PDF from HTML.</p></body></html>";
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");
}
}
Imports IronPdf
Class Program
Shared Sub Main()
Dim renderer = New ChromePdfRenderer()
Dim html As String = "<html><body><h1>Hello World</h1><p>This is a PDF from HTML.</p></body></html>"
Dim pdf = renderer.RenderHtmlAsPdf(html)
pdf.SaveAs("output.pdf")
End Sub
End Class
XFINIUM.PDF requires creating a PdfFlowDocument, instantiating PdfStandardFont objects for each style, building each piece of content as a PdfFlowHeadingContent or PdfFlowTextContent, adding them to the flow document, and saving via a FileStream. The flow document API accepts typed content objects, not HTML markup. IronPDF simplifies this to three lines: create a renderer, render HTML, and save.
For advanced HTML-to-PDF scenarios, see the HTML to PDF conversion guide.
Merging Multiple PDFs
PDF merging demonstrates the API complexity differences clearly.
XFINIUM.PDF Approach:
// NuGet: Install-Package Xfinium.Pdf.NetStandard (or .NetCore)
using Xfinium.Pdf;
using System.IO;
class Program
{
static void Main()
{
PdfFixedDocument output = new PdfFixedDocument();
FileStream file1 = File.OpenRead("document1.pdf");
PdfFixedDocument pdf1 = new PdfFixedDocument(file1);
FileStream file2 = File.OpenRead("document2.pdf");
PdfFixedDocument pdf2 = new PdfFixedDocument(file2);
for (int i = 0; i < pdf1.Pages.Count; i++)
{
output.Pages.Add(pdf1.Pages[i]);
}
for (int i = 0; i < pdf2.Pages.Count; i++)
{
output.Pages.Add(pdf2.Pages[i]);
}
output.Save("merged.pdf");
file1.Close();
file2.Close();
}
}
// NuGet: Install-Package Xfinium.Pdf.NetStandard (or .NetCore)
using Xfinium.Pdf;
using System.IO;
class Program
{
static void Main()
{
PdfFixedDocument output = new PdfFixedDocument();
FileStream file1 = File.OpenRead("document1.pdf");
PdfFixedDocument pdf1 = new PdfFixedDocument(file1);
FileStream file2 = File.OpenRead("document2.pdf");
PdfFixedDocument pdf2 = new PdfFixedDocument(file2);
for (int i = 0; i < pdf1.Pages.Count; i++)
{
output.Pages.Add(pdf1.Pages[i]);
}
for (int i = 0; i < pdf2.Pages.Count; i++)
{
output.Pages.Add(pdf2.Pages[i]);
}
output.Save("merged.pdf");
file1.Close();
file2.Close();
}
}
Imports Xfinium.Pdf
Imports System.IO
Module Program
Sub Main()
Dim output As New PdfFixedDocument()
Dim file1 As FileStream = File.OpenRead("document1.pdf")
Dim pdf1 As New PdfFixedDocument(file1)
Dim file2 As FileStream = File.OpenRead("document2.pdf")
Dim pdf2 As New PdfFixedDocument(file2)
For i As Integer = 0 To pdf1.Pages.Count - 1
output.Pages.Add(pdf1.Pages(i))
Next
For i As Integer = 0 To pdf2.Pages.Count - 1
output.Pages.Add(pdf2.Pages(i))
Next
output.Save("merged.pdf")
file1.Close()
file2.Close()
End Sub
End Module
IronPDF Approach:
// NuGet: Install-Package IronPdf
using IronPdf;
using System.Collections.Generic;
class Program
{
static void Main()
{
var pdf1 = PdfDocument.FromFile("document1.pdf");
var pdf2 = PdfDocument.FromFile("document2.pdf");
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("merged.pdf");
}
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System.Collections.Generic;
class Program
{
static void Main()
{
var pdf1 = PdfDocument.FromFile("document1.pdf");
var pdf2 = PdfDocument.FromFile("document2.pdf");
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("merged.pdf");
}
}
Imports IronPdf
Imports System.Collections.Generic
Class Program
Shared Sub Main()
Dim pdf1 = PdfDocument.FromFile("document1.pdf")
Dim pdf2 = PdfDocument.FromFile("document2.pdf")
Dim merged = PdfDocument.Merge(pdf1, pdf2)
merged.SaveAs("merged.pdf")
End Sub
End Class
XFINIUM.PDF requires creating an output document, opening file streams, loading each document, manually iterating through pages and adding them one by one, saving, and then closing streams. IronPDF provides a single PdfDocument.Merge() method that handles all complexity internally.
Explore the PDF merging documentation for additional merge options.
Creating PDFs with Text and Images
Documents with mixed content show the fundamental paradigm difference.
XFINIUM.PDF Approach:
// NuGet: Install-Package Xfinium.Pdf.NetStandard (or .NetCore)
using Xfinium.Pdf;
using Xfinium.Pdf.Graphics;
using System.IO;
class Program
{
static void Main()
{
PdfFixedDocument document = new PdfFixedDocument();
PdfPage page = document.Pages.Add();
PdfStandardFont font = new PdfStandardFont(PdfStandardFontFace.Helvetica, 24);
PdfBrush brush = new PdfBrush(new PdfRgbColor(0, 0, 0));
page.Graphics.DrawString("Sample PDF Document", font, brush, 50, 50);
using (FileStream imageStream = File.OpenRead("image.jpg"))
{
PdfJpegImage image = new PdfJpegImage(imageStream);
page.Graphics.DrawImage(image, 50, 100, 200, 150);
}
document.Save("output.pdf");
}
}
// NuGet: Install-Package Xfinium.Pdf.NetStandard (or .NetCore)
using Xfinium.Pdf;
using Xfinium.Pdf.Graphics;
using System.IO;
class Program
{
static void Main()
{
PdfFixedDocument document = new PdfFixedDocument();
PdfPage page = document.Pages.Add();
PdfStandardFont font = new PdfStandardFont(PdfStandardFontFace.Helvetica, 24);
PdfBrush brush = new PdfBrush(new PdfRgbColor(0, 0, 0));
page.Graphics.DrawString("Sample PDF Document", font, brush, 50, 50);
using (FileStream imageStream = File.OpenRead("image.jpg"))
{
PdfJpegImage image = new PdfJpegImage(imageStream);
page.Graphics.DrawImage(image, 50, 100, 200, 150);
}
document.Save("output.pdf");
}
}
Imports Xfinium.Pdf
Imports Xfinium.Pdf.Graphics
Imports System.IO
Class Program
Shared Sub Main()
Dim document As New PdfFixedDocument()
Dim page As PdfPage = document.Pages.Add()
Dim font As New PdfStandardFont(PdfStandardFontFace.Helvetica, 24)
Dim brush As New PdfBrush(New PdfRgbColor(0, 0, 0))
page.Graphics.DrawString("Sample PDF Document", font, brush, 50, 50)
Using imageStream As FileStream = File.OpenRead("image.jpg")
Dim image As New PdfJpegImage(imageStream)
page.Graphics.DrawImage(image, 50, 100, 200, 150)
End Using
document.Save("output.pdf")
End Sub
End Class
IronPDF Approach:
// NuGet: Install-Package IronPdf
using IronPdf;
using System.IO;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
string imageBase64 = Convert.ToBase64String(File.ReadAllBytes("image.jpg"));
string html = $@"
<html>
<body>
<h1>Sample PDF Document</h1>
<img src='data:image/jpeg;base64,{imageBase64}' width='200' height='150' />
</body>
</html>";
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");
}
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System.IO;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
string imageBase64 = Convert.ToBase64String(File.ReadAllBytes("image.jpg"));
string html = $@"
<html>
<body>
<h1>Sample PDF Document</h1>
<img src='data:image/jpeg;base64,{imageBase64}' width='200' height='150' />
</body>
</html>";
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");
}
}
Imports IronPdf
Imports System.IO
Class Program
Shared Sub Main()
Dim renderer = New ChromePdfRenderer()
Dim imageBase64 As String = Convert.ToBase64String(File.ReadAllBytes("image.jpg"))
Dim html As String = $"
<html>
<body>
<h1>Sample PDF Document</h1>
<img src='data:image/jpeg;base64,{imageBase64}' width='200' height='150' />
</body>
</html>"
Dim pdf = renderer.RenderHtmlAsPdf(html)
pdf.SaveAs("output.pdf")
End Sub
End Class
XFINIUM.PDF requires creating a document, adding a page, creating font and brush objects, drawing text at specific coordinates, opening an image stream, creating a PdfJpegImage, drawing the image at coordinates with dimensions, closing the stream, and saving. IronPDF uses standard HTML with embedded base64 images—the same approach web developers use daily.
XFINIUM.PDF API to IronPDF Mapping Reference
This mapping accelerates migration by showing direct API equivalents:
| XFINIUM.PDF | IronPDF |
|---|---|
PdfFixedDocument |
ChromePdfRenderer |
PdfPage |
Automatic |
page.Graphics.DrawString() |
HTML text elements |
page.Graphics.DrawImage() |
<img> tag |
page.Graphics.DrawLine() |
CSS border or <hr> |
page.Graphics.DrawRectangle() |
CSS border on <div> |
PdfStandardFont |
CSS font-family |
PdfRgbColor |
CSS color |
PdfBrush |
CSS properties |
PdfJpegImage |
<img> tag with base64 |
document.Save(stream) |
pdf.SaveAs() or pdf.BinaryData |
PdfFlowDocument |
RenderHtmlAsPdf() |
| Vendor sample XHTML converter | RenderHtmlAsPdf() |
Common Migration Issues and Solutions
Issue 1: Coordinate-Based Layout
XFINIUM.PDF: Everything requires exact X,Y coordinates with manual positioning.
Solution: Use HTML/CSS flow layout. For absolute positioning when needed, use CSS:
.positioned-element {
position: absolute;
top: 100px;
left: 50px;
}
Issue 2: Font Object Management
XFINIUM.PDF: Create PdfStandardFont or PdfUnicodeTrueTypeFont objects for each font.
Solution: Use CSS font-family—fonts are handled automatically:
<style>
body { font-family: Arial, sans-serif; }
h1 { font-family: 'Times New Roman', serif; font-size: 24px; }
</style>
<style>
body { font-family: Arial, sans-serif; }
h1 { font-family: 'Times New Roman', serif; font-size: 24px; }
</style>
Issue 3: Color Handling
XFINIUM.PDF: Create PdfRgbColor and PdfBrush objects for colors.
Solution: Use standard CSS colors:
.header { color: navy; background-color: #f5f5f5; }
.warning { color: rgb(255, 0, 0); }
.info { color: rgba(0, 0, 255, 0.8); }
Issue 4: Manual Page Breaks
XFINIUM.PDF: Track Y position and create new pages manually when content overflows.
Solution: IronPDF handles automatic page breaks. For explicit control, use CSS:
.section { page-break-after: always; }
.keep-together { page-break-inside: avoid; }
Issue 5: Image Loading
XFINIUM.PDF: Open file streams, create PdfJpegImage objects, draw at coordinates, close streams.
Solution: Use HTML <img> tags with file paths or base64 data:
<img src="image.jpg" width="200" height="150" />
<img src="data:image/jpeg;base64,..." />
<img src="image.jpg" width="200" height="150" />
<img src="data:image/jpeg;base64,..." />
XFINIUM.PDF Migration Checklist
Pre-Migration Tasks
Audit your codebase to identify all XFINIUM.PDF usage:
grep -r "using Xfinium.Pdf" --include="*.cs" .
grep -r "Graphics.DrawString\|Graphics.DrawImage\|Graphics.DrawLine" --include="*.cs" .
grep -r "using Xfinium.Pdf" --include="*.cs" .
grep -r "Graphics.DrawString\|Graphics.DrawImage\|Graphics.DrawLine" --include="*.cs" .
Document coordinate-based layouts and note all X,Y positioning values. Identify font and color objects (PdfStandardFont, PdfRgbColor, PdfBrush). Map merged PDF workflows using PdfFixedDocument.Pages.Add().
Code Update Tasks
- Remove Xfinium.Pdf NuGet package
- Install IronPDF NuGet package
- Update namespace imports from
Xfinium.PdftoIronPdf - Convert
DrawString()calls to HTML text elements - Convert
DrawImage()calls to HTML<img>tags - Convert
DrawRectangle()andDrawLine()to CSS borders - Replace
PdfStandardFontwith CSSfont-family - Replace
PdfRgbColorandPdfBrushwith CSS colors - Replace page loop merging with
PdfDocument.Merge() - Add IronPDF license initialization at startup
Post-Migration Testing
After migration, verify these aspects:
- Compare visual output to ensure appearance matches expectations
- Verify text rendering with the new HTML/CSS approach
- Check image positioning using CSS
- Test page breaks occur as expected
- Verify PDF security settings are correctly applied
- Test on all target platforms
Key Benefits of Migrating to IronPDF
Moving from XFINIUM.PDF to IronPDF provides several critical advantages:
HTML-Based Content Creation: Web developers can leverage existing HTML and CSS skills. No need to learn coordinate-based drawing APIs or manage font and brush objects.
Automatic Layout: Text wrapping, pagination, and flow layout happen automatically. No manual calculation of element positions or page breaks.
Modern CSS Support: Full CSS3 including Flexbox and Grid layouts. Responsive designs translate directly to PDF.
Simplified PDF Operations: Single-method calls for common operations like PdfDocument.Merge() replace complex page iteration loops.
Active Development: IronPDF's regular updates keep pace with current .NET versions and C# language releases.
Extensive Documentation: Large community with comprehensive documentation, tutorials, and support resources compared to XFINIUM.PDF's smaller ecosystem.

