跳至页脚内容
迁移指南

如何用 C# 从 XFINIUM.PDF 迁移到 IronPDF

XFINIUM.PDF 是一个跨平台的 PDF 库,它为用 C# 编程创建和编辑 PDF 提供了全面的工具。 虽然它提供了两个版本--生成器和查看器--但该库对基于坐标的图形编程的依赖为开发团队构建文档繁重的应用程序带来了巨大挑战。 每个元素都必须使用像素坐标进行手动定位,这使得原本简单的文档变成了复杂的绘图练习。

本指南提供了从 XFINIUM.PDF 到IronPDF的完整迁移路径,为评估这一过渡的专业 .NET 开发人员提供了分步说明、代码比较和实用示例。

为什么要从 XFINIUM.PDF 迁移

XFINIUM.PDF 是一个低级 PDF 库,它依赖于基于坐标的图形编程,迫使开发人员手动定位页面上的每个元素。 随着需求的变化,这种方法将成为维护工作的噩梦。 开发团队考虑迁移的主要原因包括

不支持HTML: XFINIUM.PDF无法直接将HTML/CSS转换为PDF。 它侧重于使用低级绘图原语进行编程式 PDF 创建,这对于需要大量 HTML 转 PDF 功能的项目来说可能还不够。

基于坐标的 API:页面上的每个元素都需要使用像素坐标进行手动定位,例如DrawString("text", font, brush, 50, 100)

手动字体管理:必须使用PdfStandardFontPdfBrush等类显式创建和管理字体对象。

不支持 CSS 样式:不支持现代网页样式。 颜色、字体和布局必须通过程序方法调用手动处理。

不使用 JavaScript 渲染:仅显示静态内容。 XFINIUM.PDF 无法呈现动态网页内容或执行 JavaScript。

复杂文本布局:对于除简单单行文本以外的任何文本,都需要手动测量文本尺寸和换行计算。

社区资源有限:与主流解决方案相比,社区提供的资源(例如示例和教程)较少,这可能会使新用户更难入门。

核心问题:图形 API 与 HTML 的对比

XFINIUM.PDF 迫使您像图形程序员而非文档设计师那样思考:

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

IronPdf 使用熟悉的 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);
$vbLabelText   $csharpLabel

IronPDF与 XFINIUM.PDF:功能比较

了解架构差异有助于技术决策者评估迁移投资:

特征 XFINIUM.PDF IronPDF
HTML 到 PDF 有限的 HTML 支持,侧重于程序化 PDF 创建 全面支持 HTML 到 PDF 的转换
社区与支持 社区规模较小,可用在线资源较少 拥有大量文档和教程的大型社区
许可 基于开发人员的商业许可 商业翻译
跨平台支持 强大的跨平台能力 同时支持跨平台操作
CSS支持 完整的 CSS3
JavaScript语言 完整的 ES2024
Flexbox/网格
自动排版
自动分页
手册定位 要求 可选项(CSS 定位)
学习曲线 高(坐标系) 低级(HTML/CSS)
代码准确性 极高

快速入门:XFINIUM.PDF 向IronPDF迁移

迁移工作可以通过以下基本步骤立即开始。

步骤 1:替换 NuGet 软件包

移除 XFINIUM.PDF:

# Remove XFINIUM.PDF
dotnet remove package Xfinium.Pdf
# Remove XFINIUM.PDF
dotnet remove package Xfinium.Pdf
SHELL

安装 IronPDF:

# Install IronPDF
dotnet add package IronPdf
# Install IronPDF
dotnet add package IronPdf
SHELL

步骤 2:更新命名空间

用 IronPdf 命名空间替换 XFINIUM.PDF 命名空间:

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

步骤 3:初始化许可证

在应用程序启动时添加许可证初始化:

IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
$vbLabelText   $csharpLabel

代码迁移示例

将HTML转换为PDF

最基本的操作揭示了这些 .NET PDF 库之间的复杂性差异。

XFINIUM.PDF 方法:

// NuGet: Install-Package Xfinium.Pdf
using Xfinium.Pdf;
using Xfinium.Pdf.Actions;
using Xfinium.Pdf.FlowDocument;
using System.IO;

class Program
{
    static void Main()
    {
        PdfFixedDocument document = new PdfFixedDocument();
        PdfFlowDocument flowDocument = new PdfFlowDocument();

        string html = "<html><body><h1>Hello World</h1><p>This is a PDF from HTML.</p></body></html>";

        PdfFlowContent content = new PdfFlowContent();
        content.AppendHtml(html);
        flowDocument.AddContent(content);

        flowDocument.RenderDocument(document);
        document.Save("output.pdf");
    }
}
// NuGet: Install-Package Xfinium.Pdf
using Xfinium.Pdf;
using Xfinium.Pdf.Actions;
using Xfinium.Pdf.FlowDocument;
using System.IO;

class Program
{
    static void Main()
    {
        PdfFixedDocument document = new PdfFixedDocument();
        PdfFlowDocument flowDocument = new PdfFlowDocument();

        string html = "<html><body><h1>Hello World</h1><p>This is a PDF from HTML.</p></body></html>";

        PdfFlowContent content = new PdfFlowContent();
        content.AppendHtml(html);
        flowDocument.AddContent(content);

        flowDocument.RenderDocument(document);
        document.Save("output.pdf");
    }
}
$vbLabelText   $csharpLabel

IronPdf 方法:

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

XFINIUM.PDF 需要创建 PdfFixedDocument, PdfFlowDocument, PdfFlowContent 对象,调用 AppendHtml(), 添加内容到 flow 文档,渲染到固定文档,最后保存。IronPDF将此简化为三行:创建呈现器、呈现 HTML 和保存。

有关 HTML 转 PDF 的高级应用场景,请参阅 HTML 转 PDF 指南

合并多个 PDF 文件

PDF 合并清楚地展示了 API 复杂性的差异。

XFINIUM.PDF 方法:

// NuGet: Install-Package Xfinium.Pdf
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
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();
    }
}
$vbLabelText   $csharpLabel

IronPdf 方法:

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

XFINIUM.PDF 需要创建输出文档、打开文件流、加载每个文档、手动迭代页面并逐一添加、保存,然后关闭文件流。IronPDF提供了单一的 PdfDocument.Merge() 方法,可在内部处理所有复杂问题。

探索 IronPDF合并文档,了解更多合并选项。

使用文本和图像创建 PDF 文件

混合内容的文档显示了基本范式的差异。

XFINIUM.PDF 方法:

// NuGet: Install-Package Xfinium.Pdf
using Xfinium.Pdf;
using Xfinium.Pdf.Graphics;
using Xfinium.Pdf.Core;
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(PdfRgbColor.Black);

        page.Graphics.DrawString("Sample PDF Document", font, brush, 50, 50);

        FileStream imageStream = File.OpenRead("image.jpg");
        PdfJpegImage image = new PdfJpegImage(imageStream);
        page.Graphics.DrawImage(image, 50, 100, 200, 150);
        imageStream.Close();

        document.Save("output.pdf");
    }
}
// NuGet: Install-Package Xfinium.Pdf
using Xfinium.Pdf;
using Xfinium.Pdf.Graphics;
using Xfinium.Pdf.Core;
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(PdfRgbColor.Black);

        page.Graphics.DrawString("Sample PDF Document", font, brush, 50, 50);

        FileStream imageStream = File.OpenRead("image.jpg");
        PdfJpegImage image = new PdfJpegImage(imageStream);
        page.Graphics.DrawImage(image, 50, 100, 200, 150);
        imageStream.Close();

        document.Save("output.pdf");
    }
}
$vbLabelText   $csharpLabel

IronPdf 方法:

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

XFINIUM.PDF 需要创建文档、添加页面、创建字体和笔刷对象、在特定坐标处绘制文本、打开图像流、创建PdfJpegImage图像、在有尺寸的坐标处绘制图像、关闭图像流并保存。IronPDF使用标准 HTML,内嵌 base64 图像--与网络开发人员日常使用的方法相同。

XFINIUM.PDF API 到IronPDF映射参考

这种映射通过显示直接的 API 对应关系来加速迁移:

XFINIUM.PDF IronPDF 备注
PDFFixedDocument ChromePdfRenderer 创建呈现器,而不是文档
PDF 页 自动翻译 根据 HTML 内容创建的页面
page.Graphics.DrawString() HTML 文本元素 <p><h1><span>等。
page.Graphics.DrawImage() <img> 标记 HTML 图像
page.Graphics.DrawLine() CSS 边框<hr> HTML/CSS 行
page.Graphics.DrawRectangle() <div> 上的 CSS 边框 HTML 框
PDF 标准字体 CSS font-family 无需字体对象
PdfRgbColor CSS 颜色 标准 CSS 颜色
PdfBrush CSS 属性 背景、颜色等
PdfJpegImage 使用 base64 的 <img> 标记 或文件路径
document.Save(流) pdf.SaveAs()</code>或<code>pdf.BinaryData 多种输出选项
PDFFlowDocument RenderHtmlAsPdf() 完全支持 HTML
PdfFlowContent.AppendHtml() RenderHtmlAsPdf() 直接 HTML 渲染

常见迁移问题和解决方案

问题 1:基于坐标的布局

XFINIUM.PDF:所有内容都需要精确的 X、Y 坐标和手动定位。

解决方案: 使用 HTML/CSS 流程布局。 需要绝对定位时,请使用 CSS:

.positioned-element {
    position: absolute;
    top: 100px;
    left: 50px;
}

问题 2:字体对象管理

XFINIUM.PDF:为每种字体创建PDF 标准字体PdfUnicodeTrueTypeFont` 对象。

解决方案:使用 CSS 字体-family-字体自动处理:

<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>
HTML

问题 3:颜色处理

XFINIUM.PDF:为颜色创建PdfRgbColorPdfBrush对象。

解决方案:使用标准 CSS 颜色:

.header { color: navy; background-color: #f5f5f5; }
.warning { color: rgb(255, 0, 0); }
.info { color: rgba(0, 0, 255, 0.8); }

问题 4:手动分页

XFINIUM.PDF: 跟踪 Y 位置并在内容溢出时手动创建新页面。

解决方案:IronPDF可处理自动分页。 如需明确控制,请使用 CSS:

.section { page-break-after: always; }
.keep-together { page-break-inside: avoid; }

问题 5:图像加载

XFINIUM.PDF:打开文件流,创建PdfJpegImage对象,绘制坐标,关闭文件流。

解决方案:使用带有文件路径或 base64 数据的 HTML <img> 标记:

<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,..." />
HTML

XFINIUM.PDF 迁移清单

迁移前任务

审核您的代码库,确定所有 XFINIUM.PDF 的使用情况:

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" .
SHELL

记录基于坐标的布局并注明所有 X、Y 定位值。 识别字体和颜色对象(PdfStandardFont, PdfRgbColor,PdfBrush)。 使用 PdfFixedDocument.Pages.Add() 映射合并的 PDF 工作流程。

代码更新任务

1.删除 Xfinium.Pdf NuGet 软件包 2.安装 IronPdf NuGet 软件包 3.更新命名空间导入,从 Xfinium.PdfIronPdf 4.将 DrawString() 调用转换为 HTML 文本元素 5.将 DrawImage() 调用转换为 HTML <img> 标记 6.将 DrawRectangle()DrawLine() 转换为 CSS 边框 7.用CSS font-family替换 PdfStandardFont 8.用 CSS 颜色替换PdfRgbColorPdfBrush 9.用 PdfDocument.Merge() 代替页面循环合并 10.在启动时添加 IronPdf 许可证初始化功能

迁移后测试

迁移后,验证这些方面:

  • 比较视觉输出,确保外观符合预期
  • 使用新的 HTML/CSS 方法验证文本渲染
  • 使用 CSS 检查图像定位
  • 测试分页符是否按预期出现
  • 验证 PDF 安全设置是否正确应用
  • 在所有目标平台上进行测试

迁移到IronPDF的主要优势

从 XFINIUM.PDF 迁移到IronPDF有几个关键优势:

基于 HTML 的内容创建: Web 开发人员可以利用现有的 HTML 和 CSS 技能。 无需学习基于坐标的绘图 API 或管理字体和画笔对象。

自动布局:文本换行、分页和流式布局自动完成。 无需手动计算元素位置或分页符。

现代 CSS 支持:完全支持 CSS3,包括 Flexbox 和 Grid 布局。 响应式设计可直接翻译成 PDF。

简化 PDF 操作:使用单一方法调用来执行诸如PdfDocument.Merge()之类的常用操作,取代复杂的页面迭代循环。

积极开发:随着 .NET 10 和 C# 14 的普及,IronPDF 将持续更新,确保与当前和未来的 .NET 版本兼容。

丰富的文档:与 XFINIUM.PDF 较小的生态系统相比,拥有庞大的社区、全面的文档、教程和支持资源。

Curtis Chau
技术作家

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

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