跳至页脚内容
迁移指南

如何用 C# 从 Easy PDF SDK 迁移到 IronPDF

Easy PDF SDK 依赖于一些传统技术,这些技术在现代开发环境中给部署和维护带来了巨大挑战。

常见的Easy PDF SDK部署问题

开发人员在使用Easy PDF SDK时经常会遇到这些问题:

  • bcl.easypdf.interop.easypdfprinter.dll 加载错误
  • 不能使用已与其底层 RCW 分离的 COM 对象
  • 等待打印作业完成超时
  • 打印机操作失败,因为服务未运行
  • `错误:拒绝访问(需要交互会话)
  • `找不到打印机:BCL easyPDF 打印机

这些错误源于Easy PDF SDK的基本架构--它需要虚拟打印机驱动程序、COM 互操作和交互式 Windows 会话,而这些在现代服务器环境中根本不存在。

Easy PDF SDK与 IronPDF:主要区别

特征 Easy PDF SDK IronPDF
平台 仅限 Windows Windows、Linux、macOS、Docker
办公依赖性 要求
安装 复杂的 MSI + 打印机驱动程序 + COM 简单的 NuGet 软件包
服务器支持 需要互动环节 无头运行
HTML 渲染 基础(基于办公室) 完整的 Chromium(CSS3、JS)
.NET支持 有限的 .NET Core 完整的 .NET 5/6/7/8/9
同步模式 基于回调 本地 async/await
容器支持 不能运行 完整的 Docker/Kubernetes

平台限制

Easy PDF SDK 完全依赖 Windows 系统,需要安装 Microsoft Office 才能进行转换,因此不支持 Linux、macOS 或 Docker 等容器环境。 这种依赖性使服务器设置变得繁琐,并限制了服务在 Windows 环境中的采用--这对于实践多平台 DevOps 或使用容器进行部署的团队来说是一个重大限制。

迁移前准备

前提条件

确保您的环境符合这些要求:

  • .NET Framework 4.6.2+ 或 .NET Core 3.1 / .NET 5-9
  • Visual Studio 2019+ 或带有 C# 扩展的 VS Code
  • 访问 NuGet 包管理器 -IronPDF许可证密钥(可在ironpdf.com免费试用)

AuditEasy PDF SDK的使用

在您的解决方案目录中运行这些命令,以识别所有Easy PDF SDK引用:

# Find all BCL using statements
grep -r "using BCL" --include="*.cs" .

# Find Printer/PDFDocument usage
grep -r "Printer\|PDFDocument\|PDFConverter\|HTMLConverter" --include="*.cs" .

# Find COM interop references
grep -r "easyPDF\|BCL.easyPDF" --include="*.csproj" .

# Find configuration settings
grep -r "PageOrientation\|TimeOut\|PrintOffice" --include="*.cs" .
# Find all BCL using statements
grep -r "using BCL" --include="*.cs" .

# Find Printer/PDFDocument usage
grep -r "Printer\|PDFDocument\|PDFConverter\|HTMLConverter" --include="*.cs" .

# Find COM interop references
grep -r "easyPDF\|BCL.easyPDF" --include="*.csproj" .

# Find configuration settings
grep -r "PageOrientation\|TimeOut\|PrintOffice" --include="*.cs" .
SHELL

值得期待的重大变化

简易 PDF SDK 模式 更改要求
new 打印机()|使用ChromePdfRenderer`
PrintOfficeDocToPDF() 以不同方式处理办公室转换
RenderHTMLToPDF() RenderHtmlAsPdf()
COM 互操作参考 完全删除
打印机驱动程序配置 不需要
`BeginPrintToFile()回调 本地 async/await
互动环节要求 无头运行
1 基于页面索引 基于 0 的索引
超时(秒 超时(毫秒

逐步迁移过程

第 1 步:删除 Easy PDF SDK.

Easy PDF SDK 通常通过 MSI 安装程序、手动 DLL 引用或 GAC 注册进行安装。 删除所有引用:

1.从 "程序和功能 "中卸载 BCL EasyPDF SDK 2.删除项目中的 DLL 引用 3.删除 COM 交互引用 4.清理 GAC 条目(如果存在

步骤2:安装IronPDF

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

或通过软件包管理器控制台:

Install-Package IronPdf

步骤 3:更新命名空间引用

用IronPDF替换Easy PDF SDK命名空间:

// Remove these
using BCL.easyPDF;
using BCL.easyPDF.Interop;
using BCL.easyPDF.PDFConverter;
using BCL.easyPDF.Printer;

// Add these
using IronPdf;
using IronPdf.Rendering;
// Remove these
using BCL.easyPDF;
using BCL.easyPDF.Interop;
using BCL.easyPDF.PDFConverter;
using BCL.easyPDF.Printer;

// Add these
using IronPdf;
using IronPdf.Rendering;
$vbLabelText   $csharpLabel

完整的 API 迁移参考

核心类映射

简易 PDF SDK 类 IronPdf 同等产品 备注
打印机|ChromePdfRenderer` 主要转换类
PDF 文档 PDF 文档 文档处理
HTMLConverter ChromePdfRenderer HTML 转换
打印机配置 ChromePdfRenderOptions 渲染选项
页面方向 PdfPaperOrientation 页面方向
页面大小 PdfPaperSize 纸张大小
安全处理程序 PdfDocument.SecuritySettings 安全选项

PDF 创建方法

简易 PDF SDK 方法 IronPdf 方法 备注
printer.RenderHTMLToPDF(html,路径) renderer.RenderHtmlAsPdf(html).SaveAs(path) HTML 字符串
printer.RenderUrlToPDF(url, path) renderer.RenderUrlAsPdf(url).SaveAs(path) URL 转换
htmlConverter.ConvertHTML(html, doc) renderer.RenderHtmlAsPdf(html) HTML 至 PDF
htmlConverter.ConvertURL(url, doc) renderer.RenderUrlAsPdf(url) URL 至 PDF

PDF 操作方法

简易 PDF SDK 方法 IronPdf 方法 备注
doc.Append(doc2) PdfDocument.Merge(pdf1, pdf2) Merge PDFs
doc.ExtractPages(start, end) pdf.CopyPages(start, end) 提取页面
doc.DeletePage(index) pdf.RemovePage(index) 删除页面
doc.GetPageCount() pdf.PageCount 页数
doc.Save(路径) pdf.SaveAs(路径) 保存 PDF
doc.Close() pdf.Dispose()</code>或<code>使用 清理
doc.ExtractText() pdf.ExtractAllText() 文本提取

配置选项

简易 PDF SDK 选项 IronPdf 选项 备注
config.TimeOut RenderingOptions.超时 超时(毫秒)
config.PageOrientation = Landscape RenderingOptions.PaperOrientation = Landscape 定位
config.PageSize = A4 RenderingOptions.PaperSize = PdfPaperSize.A4 纸张大小
config.MarginTop/Bottom/Left/Right RenderingOptions.MarginTop 等。 边距

代码迁移示例

HTML字符串到PDF

轻松实现 PDF SDK:

// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf = new PDFDocument();
        var htmlConverter = new HTMLConverter();
        htmlConverter.ConvertHTML("<h1>Hello World</h1>", pdf);
        pdf.Save("output.pdf");
        pdf.Close();
    }
}
// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf = new PDFDocument();
        var htmlConverter = new HTMLConverter();
        htmlConverter.ConvertHTML("<h1>Hello World</h1>", pdf);
        pdf.Save("output.pdf");
        pdf.Close();
    }
}
$vbLabelText   $csharpLabel

IronPDF 实现:

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

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");
        pdf.SaveAs("output.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");
        pdf.SaveAs("output.pdf");
    }
}
$vbLabelText   $csharpLabel

IronPdf 消除了单独的HTMLConverter类和手动Close()` 调用--从而使代码更简洁、更易维护。

URL到PDF转换

轻松实现 PDF SDK:

// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf = new PDFDocument();
        var htmlConverter = new HTMLConverter();
        htmlConverter.ConvertURL("https://example.com", pdf);
        pdf.Save("webpage.pdf");
        pdf.Close();
    }
}
// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf = new PDFDocument();
        var htmlConverter = new HTMLConverter();
        htmlConverter.ConvertURL("https://example.com", pdf);
        pdf.Save("webpage.pdf");
        pdf.Close();
    }
}
$vbLabelText   $csharpLabel

IronPDF 实现:

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

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderUrlAsPdf("https://example.com");
        pdf.SaveAs("webpage.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderUrlAsPdf("https://example.com");
        pdf.SaveAs("webpage.pdf");
    }
}
$vbLabelText   $csharpLabel

合并多个 PDF 文件

轻松实现 PDF SDK:

// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf1 = new PDFDocument("document1.pdf");
        var pdf2 = new PDFDocument("document2.pdf");
        pdf1.Append(pdf2);
        pdf1.Save("merged.pdf");
        pdf1.Close();
        pdf2.Close();
    }
}
// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf1 = new PDFDocument("document1.pdf");
        var pdf2 = new PDFDocument("document2.pdf");
        pdf1.Append(pdf2);
        pdf1.Save("merged.pdf");
        pdf1.Close();
        pdf2.Close();
    }
}
$vbLabelText   $csharpLabel

IronPDF 实现:

// NuGet: Install-Package IronPdf
using IronPdf;
using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var pdfs = new List<PdfDocument>
        {
            PdfDocument.FromFile("document1.pdf"),
            PdfDocument.FromFile("document2.pdf")
        };
        var merged = PdfDocument.Merge(pdfs);
        merged.SaveAs("merged.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var pdfs = new List<PdfDocument>
        {
            PdfDocument.FromFile("document1.pdf"),
            PdfDocument.FromFile("document2.pdf")
        };
        var merged = PdfDocument.Merge(pdfs);
        merged.SaveAs("merged.pdf");
    }
}
$vbLabelText   $csharpLabel

IronPdf 的静态 Merge 方法可直接接受多个文档,省去了手动 Append 循环模式。

密码保护

IronPDF 实现:

using IronPdf;

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

// Set security
pdf.SecuritySettings.UserPassword = "user123";
pdf.SecuritySettings.OwnerPassword = "owner456";
pdf.SecuritySettings.AllowUserPrinting = PdfPrintSecurity.NoPrint;
pdf.SecuritySettings.AllowUserCopyPasteContent = false;
pdf.SecuritySettings.AllowUserEdits = PdfEditSecurity.NoEdit;

pdf.SaveAs("protected.pdf");
using IronPdf;

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

// Set security
pdf.SecuritySettings.UserPassword = "user123";
pdf.SecuritySettings.OwnerPassword = "owner456";
pdf.SecuritySettings.AllowUserPrinting = PdfPrintSecurity.NoPrint;
pdf.SecuritySettings.AllowUserCopyPasteContent = false;
pdf.SecuritySettings.AllowUserEdits = PdfEditSecurity.NoEdit;

pdf.SaveAs("protected.pdf");
$vbLabelText   $csharpLabel

页眉和页脚

Easy PDF SDK 不支持本地页眉/页脚--页眉和页脚必须包含在源 HTML 中。 IronPdf 提供专用功能:

using IronPdf;

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='text-align:center; font-size:12px; font-family:Arial;'>
            Company Name - Confidential
        </div>",
    DrawDividerLine = true,
    MaxHeight = 30
};

renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='text-align:center; font-size:10px;'>
            Page {page} of {total-pages}
        </div>",
    DrawDividerLine = true,
    MaxHeight = 25
};

var pdf = renderer.RenderHtmlAsPdf("<h1>Content</h1>");
pdf.SaveAs("with_headers.pdf");
using IronPdf;

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='text-align:center; font-size:12px; font-family:Arial;'>
            Company Name - Confidential
        </div>",
    DrawDividerLine = true,
    MaxHeight = 30
};

renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='text-align:center; font-size:10px;'>
            Page {page} of {total-pages}
        </div>",
    DrawDividerLine = true,
    MaxHeight = 25
};

var pdf = renderer.RenderHtmlAsPdf("<h1>Content</h1>");
pdf.SaveAs("with_headers.pdf");
$vbLabelText   $csharpLabel

有关更多选项,请参阅页眉和页脚文档

异步 PDF 生成

Easy PDF SDK 使用基于回调的异步模式。 IronPdf 支持本地 async/await:

轻松实现 PDF SDK:

using BCL.easyPDF;

Printer printer = new Printer();

// BCL uses callback-based async
printer.BeginPrintToFile(
    "https://example.com",
    "output.pdf",
    OnPrintComplete,
    OnPrintError
);

Console.ReadLine();
printer.Dispose();
using BCL.easyPDF;

Printer printer = new Printer();

// BCL uses callback-based async
printer.BeginPrintToFile(
    "https://example.com",
    "output.pdf",
    OnPrintComplete,
    OnPrintError
);

Console.ReadLine();
printer.Dispose();
$vbLabelText   $csharpLabel

IronPDF 实现:

using IronPdf;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var renderer = new ChromePdfRenderer();

        // Native async/await
        var pdf = await renderer.RenderUrlAsPdfAsync("https://example.com");
        await pdf.SaveAsAsync("output.pdf");

        Console.WriteLine("PDF created: output.pdf");
    }
}
using IronPdf;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var renderer = new ChromePdfRenderer();

        // Native async/await
        var pdf = await renderer.RenderUrlAsPdfAsync("https://example.com");
        await pdf.SaveAsAsync("output.pdf");

        Console.WriteLine("PDF created: output.pdf");
    }
}
$vbLabelText   $csharpLabel

关键迁移说明

页面索引更改

Easy PDF SDK 使用基于 1 的索引。 IronPdf 使用基于 0 的索引:

// Easy PDF SDK: 1-based
doc.ExtractPages(1, 5);

// IronPDF: 0-based
pdf.CopyPages(0, 4);
// Easy PDF SDK: 1-based
doc.ExtractPages(1, 5);

// IronPDF: 0-based
pdf.CopyPages(0, 4);
$vbLabelText   $csharpLabel

超时(毫秒)

Easy PDF SDK 使用秒作为超时值。 IronPdf 使用毫秒:

// Easy PDF SDK: seconds
config.TimeOut = 120;

// IronPDF: milliseconds
renderer.RenderingOptions.Timeout = 120000;
// Easy PDF SDK: seconds
config.TimeOut = 120;

// IronPDF: milliseconds
renderer.RenderingOptions.Timeout = 120000;
$vbLabelText   $csharpLabel

ASP.NET Core 集成

由于交互式会话的要求,Easy PDF SDK 在网络环境中很难发挥作用。

IronPdf模式:

[ApiController]
[Route("[controller]")]
public class PdfController : ControllerBase
{
    [HttpGet("generate")]
    public IActionResult GeneratePdf()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Report</h1>");

        return File(pdf.BinaryData, "application/pdf", "report.pdf");
    }

    [HttpGet("generate-async")]
    public async Task<IActionResult> GeneratePdfAsync()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = await renderer.RenderHtmlAsPdfAsync("<h1>Report</h1>");

        return File(pdf.Stream, "application/pdf", "report.pdf");
    }
}
[ApiController]
[Route("[controller]")]
public class PdfController : ControllerBase
{
    [HttpGet("generate")]
    public IActionResult GeneratePdf()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Report</h1>");

        return File(pdf.BinaryData, "application/pdf", "report.pdf");
    }

    [HttpGet("generate-async")]
    public async Task<IActionResult> GeneratePdfAsync()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = await renderer.RenderHtmlAsPdfAsync("<h1>Report</h1>");

        return File(pdf.Stream, "application/pdf", "report.pdf");
    }
}
$vbLabelText   $csharpLabel

Docker 部署

Easy PDF SDK 无法在 Docker 容器中运行--它需要 Windows 容器、Microsoft Office、虚拟打印机驱动程序和交互式桌面会话。 这从根本上与容器化不相容。

IronPDF Docker 配置:

FROM mcr.microsoft.com/dotnet/aspnet:8.0

# Install Chromium dependencies
RUN apt-get update && apt-get install -y \
    libc6 libgdiplus libx11-6 libxcomposite1 \
    libxdamage1 libxrandr2 libxss1 libxtst6 \
    libnss3 libatk-bridge2.0-0 libgtk-3-0 \
    libgbm1 libasound2 fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY . .
ENTRYPOINT ["dotnet", "MyApp.dll"]

常见迁移问题的故障排除

问题:未找到打印机

症状: 无法找到打印机:BCL easyPDF 打印机

解决方案:IronPDF 不需要打印机驱动程序:

// Just use the renderer directly
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
// Just use the renderer directly
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
$vbLabelText   $csharpLabel

问题:COM 互操作错误

症状: DLL 加载错误RCW 错误

解决方案:删除所有 COM 引用,使用IronPDF的托管 API。

问题:服务器超时

症状:PDF 生成在网络服务器上挂起

解决方案:IronPDF可无头运行,无需交互会话:

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.Timeout = 60000; // Reliable timeout
var pdf = renderer.RenderHtmlAsPdf(html);
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.Timeout = 60000; // Reliable timeout
var pdf = renderer.RenderHtmlAsPdf(html);
$vbLabelText   $csharpLabel

问题:背景未打印

症状:CSS 背景丢失

解决方案:启用背景打印:

renderer.RenderingOptions.PrintHtmlBackgrounds = true;
renderer.RenderingOptions.PrintHtmlBackgrounds = true;
$vbLabelText   $csharpLabel

迁移后核对表

完成代码迁移后,请验证以下内容:

  • 使用IronPDF的 Chromium 引擎验证 PDF 输出质量
  • 使用复杂的 HTML/CSS 测试所有极端情况
  • 验证服务器部署在没有交互式会话的情况下是否正常工作
  • 测试 Docker/容器部署
  • 从部署中移除 BCL EasyPDF 安装程序
  • 从服务器上移除 Office 安装(不再需要)
  • 使用新的 NuGet 包更新 CI/CD 管道

未来保护您的 PDF 基础架构

随着 .NET 10 即将推出,C# 14 也将引入新的语言特性,选择跨平台的 PDF 库可以确保与不断发展的部署模式兼容。 IronPdf.Linux 支持 Linux、Docker 和云原生架构,这意味着当项目扩展到 2025 年和 2026 年时,您的迁移投资将获得回报--而不会受到Easy PDF SDK仅支持 Windows 系统的限制。

其他资源


从Easy PDF SDK迁移到 IronPDF,可以消除虚拟打印机依赖性、COM 互操作问题和仅适用于 Windows 的限制。 过渡到基于 Chromium 的渲染提供了卓越的 CSS3 和 JavaScript 支持,同时还能部署到 Docker、Kubernetes 和云环境,而以前Easy PDF SDK的传统架构是不可能实现这些功能的。

Curtis Chau
技术作家

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

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