跳至页脚内容
迁移指南

如何用 C# 从 PDFSharp 迁移到 IronPDF

从PDFSharp迁移到IronPDF可将您的 PDF 生成工作流程从基于坐标的手动绘制转变为现代 HTML/CSS 模板。 本指南提供了一个完整的、循序渐进的迁移路径,用网络技术取代了繁琐的 GDI+ 样式定位,大大缩短了开发时间,并使 PDF 生成可通过标准的 HTML/CSS 技能进行维护。

为什么要从PDFSharp迁移到 IronPDF.

了解 PDFSharp.

PDFSharp 是著名的底层 PDF 创建库,允许开发人员通过编程方式生成 PDF 文档。PDFSharp根据 MIT 许可发布,允许开发人员自由使用和修改。PDFSharp主要用作从头开始绘制和编译 PDF 的工具,根据项目的性质,这既可能是有益的,也可能是限制性的。

PDFSharp 有时会被误认为是 HTML 到 PDF 的转换器,其实不然。 其目的仅限于编程式 PDF 文档创建。 虽然有一个插件 HtmlRenderer.PdfSharp 可以提供 HTML 渲染功能,但它只支持 CSS 2.1,不支持 flexbox 和 grid 等现代 CSS 功能。

坐标计算问题

PDFSharp 的 GDI+ 方法意味着您必须

  • 为每个元素计算精确的 X、Y 位置
  • 手动跟踪页面溢出的内容高度
  • 自行处理换行和文本测量
  • 通过边框计算逐格绘制表格
  • 使用手动分页功能管理多页文档

PDFSharp 的架构要求对使用坐标定位有深刻的理解,这往往给创建复杂布局带来挑战。

PDFSharp与IronPDF对比

特征 PDFSharp IronPDF
许可 麻省理工学院(免费) 商业翻译
HTML 转 PDF 支持 是(支持 HTML5/CSS3)
现代 CSS 支持 否(仅限 CSS 2.1) 是(全 CSS3)
文档创建 基于坐标的绘图 HTML/CSS 模板
布局系统 手动 X、Y 定位 CSS Flow/Flexbox/Grid
分页符 手工计算 自动 + CSS 控制
表格 单独绘制单元格 HTML <table>
样式 基于代码的字体/颜色 CSS 样式表
文档应用程序接口 低级(需要坐标) 高级(简化 API)
更新 不经常 常规翻译

IronPDF 在需要将 HTML 文档完全忠实地转换为 PDF 的场景中大显身手。 该 .NET 库支持 HTML5 和 CSS3,确保符合现代网络标准。 其本地 HTML 转 PDF 功能意味着开发人员可以利用现有的网页内容或使用当代网络工具设计的模板。

对于计划在 2025 年和 2026 年之前采用 .NET 10 和 C# 14 的团队来说,IronPDF 提供了一种现代化的方法,在充分利用网络开发技能的同时,消除了坐标计算。


开始之前

前提条件

  1. .NET 环境: .NET Framework 4.6.2+ 或 .NET Core 3.1+ / .NET 5/6/7/8/9+
  2. NuGet 访问权限:能够安装 NuGet 包
  3. IronPDF 许可证:请从ironpdf.com获取您的许可证密钥。

NuGet 软件包变更

# 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
SHELL

许可配置

// 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";
$vbLabelText   $csharpLabel

确定PDFSharp的用法

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

完整的 API 参考

命名空间变更

// 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;
$vbLabelText   $csharpLabel

核心 API 映射

PDFSharp API IronPdf API 备注
new PdfDocument() ChromePdfRenderer.RenderHtmlAsPdf() 从 HTML 创建
document.AddPage() 自动翻译 根据 HTML 内容创建的页面
XGraphics.FromPdfPage() 不需要 使用 HTML 元素
XGraphics.DrawString() HTML <p>, <h1> 等。 使用 CSS 定位
XGraphics.DrawImage() HTML <img> 标记 使用 CSS 定位
XFont CSS font-family, font-size 标准 CSS
XBrush</code>,XPen|CSS 颜色/边框|颜色, 背景颜色`
document.Save() pdf.SaveAs() 类似功能
PdfReader.Open() PdfDocument.FromFile() 打开现有 PDF

代码迁移示例

示例 1:HTML 到 PDF 的转换

之前 (PDFSharp):

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

class Program
{
    static void Main()
    {
        //PDFSharpdoes not have built-inHTML 至 PDFconversion
        // 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);

        // 手册 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()
    {
        //PDFSharpdoes not have built-inHTML 至 PDFconversion
        // 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);

        // 手册 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");
    }
}
$vbLabelText   $csharpLabel

After (IronPDF):

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

class Program
{
    static void Main()
    {
        //IronPDFhas nativeHTML 至 PDFrendering
        var renderer = new ChromePdfRenderer();

        string html = "<h1>Hello from IronPDF</h1><p>EasyHTML 至 PDFconversion</p>";
        var pdf = renderer.RenderHtmlAsPdf(html);

        pdf.SaveAs("output.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        //IronPDFhas nativeHTML 至 PDFrendering
        var renderer = new ChromePdfRenderer();

        string html = "<h1>Hello from IronPDF</h1><p>EasyHTML 至 PDFconversion</p>";
        var pdf = renderer.RenderHtmlAsPdf(html);

        pdf.SaveAs("output.pdf");
    }
}
$vbLabelText   $csharpLabel

这个例子突出了两个库之间最显著的区别。PDFSharp明确指出它 "没有内置 HTML 到 PDF 的转换功能"--您必须手动创建一个 PdfDocument 文件,添加一个 PdfPage 页面,获取一个 XGraphics 对象,创建一个XFont字体,并使用DrawString()XRect` 坐标。

IronPDF 通过 ChromePdfRenderer 提供本地 HTML 到 PDF 的渲染。 RenderHtmlAsPdf() 方法接受 HTML 字符串,并在内部使用 Chromium 引擎进行转换。IronPDF可轻松将 HTML 文件转换为 PDF,保留 HTML5 和 CSS3 中定义的所有样式,无需进行坐标计算。 请参阅 HTML 转 PDF 文档,了解全面的示例。

示例 2:在现有 PDF 中添加文本/水印

之前 (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");
    }
}
$vbLabelText   $csharpLabel

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");
    }
}
$vbLabelText   $csharpLabel

PDFSharp 要求使用PdfReader.Open()指定 PdfDocumentOpenMode.Modify 打开 PDF,访问页面,创建 XGraphics 对象,创建具有样式的XFont并使用 DrawString() 指定精确的 X、Y 坐标(200, 400)的 XPoint

IronPDF 通过PdfDocument.FromFile()、具有声明属性(TextFontSizeColorVerticalAlignmentHorizontalAlignment)的TextStamper对象和ApplyStamp()简化了这一过程。 无需坐标计算--只需指定对齐方式,IronPDF 即可处理定位。 请注意,IronPdf.Editing 名称空间是实现盖章功能所必需的。

示例 3:使用图像创建 PDF.

之前 (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");
    }
}
$vbLabelText   $csharpLabel

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);
    }
}
$vbLabelText   $csharpLabel

PDFSharp 要求创建一个新的 PdfDocument, 添加一个 PdfPage, 获取 XGraphics, 从文件中加载一个 XImage, 计算宽度和高度, 使用 DrawImage() 精确坐标(50, 50, 200, 200), 然后使用 DrawString() 分别添加文本。

IronPdf 使用标准 HTML,带有 <img> 标记和 CSS 样式(style='width:200px; 高度:200px;&#39;)。 无需进行坐标计算--由 CSS 处理布局。IronPDF还提供 ImageStamper 用于将图像添加到具有声明对齐属性的现有 PDF 中。 在我们的教程中了解更多信息。


关键迁移说明

范式转换:坐标到 HTML/CSS.

最大的变化是从基于坐标的绘图转向 HTML/CSS:

// PDFSharp: 手册 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: 手册 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);
$vbLabelText   $csharpLabel

字体迁移

// 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>";
$vbLabelText   $csharpLabel

文档加载更改

// 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");
$vbLabelText   $csharpLabel

保存方法更改

// 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");
$vbLabelText   $csharpLabel

页面访问更改

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

// IronPDF:自动翻译page handling or pdf.Pages[0]
// Pages are created automatically from HTML content
// PDFSharp: document.Pages[0]
PdfPage page = document.Pages[0];

// IronPDF:自动翻译page handling or pdf.Pages[0]
// Pages are created automatically from HTML content
$vbLabelText   $csharpLabel

迁移后的新功能

迁移到IronPDF后,您将获得PDFSharp无法提供的功能:

将原生 HTML 转换为 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>");
$vbLabelText   $csharpLabel

URL到PDF

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

PDF 合并

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);
$vbLabelText   $csharpLabel

使用 HTML 的水印

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

功能对比摘要

特征 PDFSharp IronPDF
基于坐标的绘图 ✗(使用 HTML)
HTML 至 PDF
CSS3 支持
Flexbox/Grid 布局
文本冲压 手册 XGraphics TextStamper
图像冲压 手册 XImage ImageStamper
合并 PDF 手册
URL 至 PDF
现代网络渲染 Chromium 引擎
自动分页

迁移清单

迁移前

  • 清点代码库中所有PDFSharp的使用情况
  • 识别正在生成的文档类型(报告、发票、证书)
  • 注意任何自定义图形或绘图操作
  • 规划IronPDF许可证密钥存储(建议使用环境变量)
  • 先使用IronPDF试用许可证进行测试

软件包变更

  • 删除PdfSharp NuGet 包
  • 如果已使用,请移除PdfSharp-wpf NuGet 包
  • 如果已使用,请移除PdfSharp.Charting NuGet 包。 安装IronPdf NuGet 包: dotnet add package IronPdf

代码更改

  • 更新命名空间导入( using PdfSharp.Pdf;using IronPdf;
  • 添加using IronPdf.Editing;以实现盖章功能
  • 将基于坐标的布局转换为 HTML/CSS
  • XFont替换为 CSS 字体属性
  • XBrush / XPen替换为 CSS 颜色/边框。
  • XGraphics.DrawString()替换为 HTML 文本元素
  • XGraphics.DrawImage()替换为 HTML<img>标签
  • PdfReader.Open()替换为PdfDocument.FromFile()
  • document.Save()替换为pdf.SaveAs() 将表格绘制代码转换为 HTML 表格

后迁移

  • 生成PDF文件的可视化比较
  • 测试多页文档
  • 验证字体渲染
  • 根据需要添加新功能(HTML 转 PDF、合并、水印)

Curtis Chau
技术作家

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

除了开发之外,Curtis 对物联网 (IoT) 有浓厚的兴趣,探索将硬件和软件集成的新方法。在空闲时间,他喜欢玩游戏和构建 Discord 机器人,将他对技术的热爱与创造力相结合。