How to Migrate from PDFSharp to IronPDF in C#

Understanding PDFSharp

PDFSharp is renowned as a low-level PDF creation library, allowing developers to generate PDF documents through a programmatic approach. Released under the MIT license, PDFSharp grants the developer community freedom in usage and modification. PDFSharp primarily functions as a tool for drawing and compiling PDFs from scratch, which can both be beneficial and restrictive depending on the project's nature.

PDFSharp is sometimes mistakenly assumed to be an HTML-to-PDF converter, which it is not. Its purpose is dedicated to programmatic PDF document creation only. While there is an add-on, HtmlRenderer.PdfSharp, intended to provide HTML rendering capabilities, it only supports CSS 2.1, with no support for modern CSS features like flexbox and grid.

The Coordinate Calculation Problem

PDFSharp's GDI+ approach means you must:

• Calculate exact X,Y positions for every element
• Manually track content height for page overflow
• Handle line wrapping and text measurement yourself
• Draw tables cell by cell with border calculations
• Manage multi-page documents with manual page breaks

PDFSharp's architecture requires a deep understanding of positioning using coordinates, often posing challenges in creating complex layouts.

PDFSharp vs IronPDF Comparison

IronPDF shines in scenarios where HTML documents need conversion to PDFs with full fidelity. This .NET library supports HTML5 and CSS3, ensuring modern web standards are met. Its native HTML-to-PDF capabilities mean developers can take advantage of existing web content or templates designed with contemporary web tools.

For teams planning .NET 10 and C# 14 adoption through 2025 and 2026, IronPDF provides a modern approach that eliminates coordinate calculations while leveraging web development skills.

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

# Remove PDFSharp
dotnet remove package PdfSharp
dotnet remove package PdfSharp-wpf
dotnet remove package PdfSharp.Charting

# Add IronPDF
dotnet add package IronPdf

# Remove PDFSharp
dotnet remove package PdfSharp
dotnet remove package PdfSharp-wpf
dotnet remove package PdfSharp.Charting

# Add IronPDF
dotnet add package IronPdf

License Configuration

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

Identify PDFSharp Usage

# Find all PDFSharp usages in your codebase
grep -r "PdfSharp\|XGraphics\|XFont\|XBrush\|XPen" --include="*.cs" .

# Find all PDFSharp usages in your codebase
grep -r "PdfSharp\|XGraphics\|XFont\|XBrush\|XPen" --include="*.cs" .

Namespace Changes

// Before: PDFSharp
using PdfSharp.Pdf;
using PdfSharp.Drawing;
using PdfSharp.Pdf.IO;

// After: IronPDF
using IronPdf;
using IronPdf.Editing;

// Before: PDFSharp
using PdfSharp.Pdf;
using PdfSharp.Drawing;
using PdfSharp.Pdf.IO;

// After: IronPDF
using IronPdf;
using IronPdf.Editing;

Core API Mappings

Example 1: HTML to PDF Conversion

Before (PDFSharp):

// NuGet: Install-Package PdfSharp
using PdfSharp.Pdf;
using PdfSharp.Drawing;
using System;

class Program
{
    static void Main()
    {
        // PDFSharp does not have built-in HTML to PDF conversion
        // You need to manually parse HTML and render content
        PdfDocument document = new PdfDocument();
        PdfPage page = document.AddPage();
        XGraphics gfx = XGraphics.FromPdfPage(page);
        XFont font = new XFont("Arial", 12);

        // Manual text rendering (no HTML support)
        gfx.DrawString("Hello from PDFSharp", font, XBrushes.Black,
            new XRect(0, 0, page.Width, page.Height),
            XStringFormats.TopLeft);

        document.Save("output.pdf");
    }
}

// NuGet: Install-Package PdfSharp
using PdfSharp.Pdf;
using PdfSharp.Drawing;
using System;

class Program
{
    static void Main()
    {
        // PDFSharp does not have built-in HTML to PDF conversion
        // You need to manually parse HTML and render content
        PdfDocument document = new PdfDocument();
        PdfPage page = document.AddPage();
        XGraphics gfx = XGraphics.FromPdfPage(page);
        XFont font = new XFont("Arial", 12);

        // Manual text rendering (no HTML support)
        gfx.DrawString("Hello from PDFSharp", font, XBrushes.Black,
            new XRect(0, 0, page.Width, page.Height),
            XStringFormats.TopLeft);

        document.Save("output.pdf");
    }
}

After (IronPDF):

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

class Program
{
    static void Main()
    {
        // IronPDF has native HTML to PDF rendering
        var renderer = new ChromePdfRenderer();

        string html = "<h1>Hello from IronPDF</h1><p>Easy HTML to PDF conversion</p>";
        var pdf = renderer.RenderHtmlAsPdf(html);

        pdf.SaveAs("output.pdf");
    }
}

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

class Program
{
    static void Main()
    {
        // IronPDF has native HTML to PDF rendering
        var renderer = new ChromePdfRenderer();

        string html = "<h1>Hello from IronPDF</h1><p>Easy HTML to PDF conversion</p>";
        var pdf = renderer.RenderHtmlAsPdf(html);

        pdf.SaveAs("output.pdf");
    }
}

This example highlights the most significant difference between the two libraries. PDFSharp explicitly states it "does not have built-in HTML to PDF conversion"—you must manually create a PdfDocument, add a PdfPage, get an XGraphics object, create an XFont, and use DrawString() with XRect coordinates.

IronPDF provides native HTML to PDF rendering through ChromePdfRenderer. The RenderHtmlAsPdf() method accepts HTML strings and converts them using a Chromium engine internally. IronPDF easily converts HTML files to PDF, preserving all styles defined in HTML5 and CSS3, eliminating the need for coordinate calculations. See the HTML to PDF documentation for comprehensive examples.

Example 2: Adding Text/Watermark to Existing PDF

Before (PDFSharp):

// NuGet: Install-Package PdfSharp
using PdfSharp.Pdf;
using PdfSharp.Pdf.IO;
using PdfSharp.Drawing;
using System;

class Program
{
    static void Main()
    {
        // Open existing PDF
        PdfDocument document = PdfReader.Open("existing.pdf", PdfDocumentOpenMode.Modify);
        PdfPage page = document.Pages[0];

        // Get graphics object
        XGraphics gfx = XGraphics.FromPdfPage(page);
        XFont font = new XFont("Arial", 20, XFontStyle.Bold);

        // Draw text at specific position
        gfx.DrawString("Watermark Text", font, XBrushes.Red,
            new XPoint(200, 400));

        document.Save("modified.pdf");
    }
}

// NuGet: Install-Package PdfSharp
using PdfSharp.Pdf;
using PdfSharp.Pdf.IO;
using PdfSharp.Drawing;
using System;

class Program
{
    static void Main()
    {
        // Open existing PDF
        PdfDocument document = PdfReader.Open("existing.pdf", PdfDocumentOpenMode.Modify);
        PdfPage page = document.Pages[0];

        // Get graphics object
        XGraphics gfx = XGraphics.FromPdfPage(page);
        XFont font = new XFont("Arial", 20, XFontStyle.Bold);

        // Draw text at specific position
        gfx.DrawString("Watermark Text", font, XBrushes.Red,
            new XPoint(200, 400));

        document.Save("modified.pdf");
    }
}

After (IronPDF):

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

class Program
{
    static void Main()
    {
        // Open existing PDF
        var pdf = PdfDocument.FromFile("existing.pdf");

        // Add text stamp/watermark
        var textStamper = new TextStamper()
        {
            Text = "Watermark Text",
            FontSize = 20,
            Color = IronSoftware.Drawing.Color.Red,
            VerticalAlignment = VerticalAlignment.Middle,
            HorizontalAlignment = HorizontalAlignment.Center
        };

        pdf.ApplyStamp(textStamper);
        pdf.SaveAs("modified.pdf");
    }
}

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

class Program
{
    static void Main()
    {
        // Open existing PDF
        var pdf = PdfDocument.FromFile("existing.pdf");

        // Add text stamp/watermark
        var textStamper = new TextStamper()
        {
            Text = "Watermark Text",
            FontSize = 20,
            Color = IronSoftware.Drawing.Color.Red,
            VerticalAlignment = VerticalAlignment.Middle,
            HorizontalAlignment = HorizontalAlignment.Center
        };

        pdf.ApplyStamp(textStamper);
        pdf.SaveAs("modified.pdf");
    }
}

PDFSharp requires opening the PDF with PdfReader.Open() specifying PdfDocumentOpenMode.Modify, accessing a page, creating an XGraphics object, creating an XFont with style, and using DrawString() with an XPoint specifying exact X,Y coordinates (200, 400).

IronPDF simplifies this with PdfDocument.FromFile(), a TextStamper object with declarative properties (Text, FontSize, Color, VerticalAlignment, HorizontalAlignment), and ApplyStamp(). No coordinate calculations needed—just specify alignment and IronPDF handles positioning. Note the IronPdf.Editing namespace is required for stamping functionality.

Example 3: Creating PDF with Images

Before (PDFSharp):

// NuGet: Install-Package PdfSharp
using PdfSharp.Pdf;
using PdfSharp.Drawing;
using System;

class Program
{
    static void Main()
    {
        // Create new PDF document
        PdfDocument document = new PdfDocument();
        PdfPage page = document.AddPage();
        XGraphics gfx = XGraphics.FromPdfPage(page);

        // Load and draw image
        XImage image = XImage.FromFile("image.jpg");

        // Calculate size to fit page
        double width = 200;
        double height = 200;

        gfx.DrawImage(image, 50, 50, width, height);

        // Add text
        XFont font = new XFont("Arial", 16);
        gfx.DrawString("Image in PDF", font, XBrushes.Black,
            new XPoint(50, 270));

        document.Save("output.pdf");
    }
}

// NuGet: Install-Package PdfSharp
using PdfSharp.Pdf;
using PdfSharp.Drawing;
using System;

class Program
{
    static void Main()
    {
        // Create new PDF document
        PdfDocument document = new PdfDocument();
        PdfPage page = document.AddPage();
        XGraphics gfx = XGraphics.FromPdfPage(page);

        // Load and draw image
        XImage image = XImage.FromFile("image.jpg");

        // Calculate size to fit page
        double width = 200;
        double height = 200;

        gfx.DrawImage(image, 50, 50, width, height);

        // Add text
        XFont font = new XFont("Arial", 16);
        gfx.DrawString("Image in PDF", font, XBrushes.Black,
            new XPoint(50, 270));

        document.Save("output.pdf");
    }
}

After (IronPDF):

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

class Program
{
    static void Main()
    {
        // Create PDF from HTML with image
        var renderer = new ChromePdfRenderer();

        string html = @"
            <h1>Image in PDF</h1>
            <img src='image.jpg' style='width:200px; height:200px;' />
            <p>Easy image embedding with HTML</p>";

        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("output.pdf");

        // Alternative: Add image to existing PDF
        var existingPdf = new ChromePdfRenderer().RenderHtmlAsPdf("<h1>Document</h1>");
        var imageStamper = new IronPdf.Editing.ImageStamper(new Uri("image.jpg"))
        {
            VerticalAlignment = IronPdf.Editing.VerticalAlignment.Top
        };
        existingPdf.ApplyStamp(imageStamper);
    }
}

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

class Program
{
    static void Main()
    {
        // Create PDF from HTML with image
        var renderer = new ChromePdfRenderer();

        string html = @"
            <h1>Image in PDF</h1>
            <img src='image.jpg' style='width:200px; height:200px;' />
            <p>Easy image embedding with HTML</p>";

        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("output.pdf");

        // Alternative: Add image to existing PDF
        var existingPdf = new ChromePdfRenderer().RenderHtmlAsPdf("<h1>Document</h1>");
        var imageStamper = new IronPdf.Editing.ImageStamper(new Uri("image.jpg"))
        {
            VerticalAlignment = IronPdf.Editing.VerticalAlignment.Top
        };
        existingPdf.ApplyStamp(imageStamper);
    }
}

PDFSharp requires creating a new PdfDocument, adding a PdfPage, getting XGraphics, loading an XImage from file, calculating width and height, using DrawImage() with exact coordinates (50, 50, 200, 200), then separately adding text with DrawString().

IronPDF uses standard HTML with an <img> tag and CSS styling (style='width:200px; height:200px;'). No coordinate calculations needed—CSS handles layout. IronPDF also provides ImageStamper for adding images to existing PDFs with declarative alignment properties. Learn more in our tutorials.

Paradigm Shift: Coordinates to HTML/CSS

The most significant change is moving from coordinate-based drawing to HTML/CSS:

// PDFSharp: Manual positioning nightmare
gfx.DrawString("Invoice", titleFont, XBrushes.Black, new XPoint(50, 50));
gfx.DrawString("Customer: John", bodyFont, XBrushes.Black, new XPoint(50, 80));

// IronPDF: Let CSS handle layout
var html = @"
<div style='padding: 50px;'>
    <h1>Invoice</h1>
    <p>Customer: John</p>
</div>";
var pdf = renderer.RenderHtmlAsPdf(html);

// PDFSharp: Manual positioning nightmare
gfx.DrawString("Invoice", titleFont, XBrushes.Black, new XPoint(50, 50));
gfx.DrawString("Customer: John", bodyFont, XBrushes.Black, new XPoint(50, 80));

// IronPDF: Let CSS handle layout
var html = @"
<div style='padding: 50px;'>
    <h1>Invoice</h1>
    <p>Customer: John</p>
</div>";
var pdf = renderer.RenderHtmlAsPdf(html);

Font Migration

// PDFSharp: XFont objects
var titleFont = new XFont("Arial", 24, XFontStyle.Bold);
var bodyFont = new XFont("Times New Roman", 12);

// IronPDF: CSS font properties
var html = @"
<style>
    h1 { font-family: Arial, sans-serif; font-size: 24px; font-weight: bold; }
    p { font-family: 'Times New Roman', serif; font-size: 12px; }
</style>";

// PDFSharp: XFont objects
var titleFont = new XFont("Arial", 24, XFontStyle.Bold);
var bodyFont = new XFont("Times New Roman", 12);

// IronPDF: CSS font properties
var html = @"
<style>
    h1 { font-family: Arial, sans-serif; font-size: 24px; font-weight: bold; }
    p { font-family: 'Times New Roman', serif; font-size: 12px; }
</style>";

Document Loading Change

// PDFSharp: PdfReader.Open()
PdfDocument document = PdfReader.Open("existing.pdf", PdfDocumentOpenMode.Modify);

// IronPDF: PdfDocument.FromFile()
var pdf = PdfDocument.FromFile("existing.pdf");

// PDFSharp: PdfReader.Open()
PdfDocument document = PdfReader.Open("existing.pdf", PdfDocumentOpenMode.Modify);

// IronPDF: PdfDocument.FromFile()
var pdf = PdfDocument.FromFile("existing.pdf");

Save Method Change

// PDFSharp: document.Save()
document.Save("output.pdf");

// IronPDF: pdf.SaveAs()
pdf.SaveAs("output.pdf");

// PDFSharp: document.Save()
document.Save("output.pdf");

// IronPDF: pdf.SaveAs()
pdf.SaveAs("output.pdf");

Page Access Change

// PDFSharp: document.Pages[0]
PdfPage page = document.Pages[0];

// IronPDF: Automatic page handling or pdf.Pages[0]
// Pages are created automatically from HTML content

// PDFSharp: document.Pages[0]
PdfPage page = document.Pages[0];

// IronPDF: Automatic page handling or pdf.Pages[0]
// Pages are created automatically from HTML content

Native HTML to PDF

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Modern Web Content</h1>");

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Modern Web Content</h1>");

URL to PDF

var pdf = renderer.RenderUrlAsPdf("https://example.com");

var pdf = renderer.RenderUrlAsPdf("https://example.com");

PDF Merging

var pdf1 = PdfDocument.FromFile("document1.pdf");
var pdf2 = PdfDocument.FromFile("document2.pdf");
var merged = PdfDocument.Merge(pdf1, pdf2);

var pdf1 = PdfDocument.FromFile("document1.pdf");
var pdf2 = PdfDocument.FromFile("document2.pdf");
var merged = PdfDocument.Merge(pdf1, pdf2);

Watermarks with HTML

pdf.ApplyWatermark("<h2 style='color:red;'>CONFIDENTIAL</h2>");

pdf.ApplyWatermark("<h2 style='color:red;'>CONFIDENTIAL</h2>");

Pre-Migration

• Inventory all PDFSharp usage in codebase
• Identify document types being generated (reports, invoices, certificates)
• Note any custom graphics or drawing operations
• Plan IronPDF license key storage (environment variables recommended)
• Test with IronPDF trial license first

Package Changes

• Remove PdfSharp NuGet package
• Remove PdfSharp-wpf NuGet package if used
• Remove PdfSharp.Charting NuGet package if used
• Install IronPdf NuGet package: dotnet add package IronPdf

Code Changes

• Update namespace imports (using PdfSharp.Pdf; → using IronPdf;)
• Add using IronPdf.Editing; for stamping functionality
• Convert coordinate-based layouts to HTML/CSS
• Replace XFont with CSS font properties
• Replace XBrush/XPen with CSS colors/borders
• Replace XGraphics.DrawString() with HTML text elements
• Replace XGraphics.DrawImage() with HTML <img> tags
• Replace PdfReader.Open() with PdfDocument.FromFile()
• Replace document.Save() with pdf.SaveAs()
• Convert table drawing code to HTML tables

Post-Migration

• Visual comparison of generated PDFs
• Test multi-page documents
• Verify font rendering
• Add new capabilities (HTML to PDF, merging, watermarks) as needed