跳過到頁腳內容
MIGRATION GUIDES

How to Migrate from Easy PDF SDK to IronPDF in C#

Easy PDF SDK 依賴多種傳統技術,這為現代開發環境中的部署和維護帶來了重大挑戰。

簡易 PDF SDK 部署常見問題

開發人員在使用 簡易 PDF SDK 時經常會遇到以下問題:

  • bcl.easypdf.interop.easypdfprinter.dll error loading
  • COM object that has been separated from its underlying RCW cannot be used Timeout expired waiting for print job to complete The printer operation failed because the service is not running Error: Access denied (需要互動式會話) Cannot find printer: BCL easyPDF Printer

這些錯誤源自於 簡易 PDF SDK 的基本架構——它需要虛擬印表機驅動程式、COM 互通性和互動式 Windows 會話,而這些在現代伺服器環境中根本不存在。

簡易 PDF SDK 與 IronPDF:主要區別

特徵 簡易 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提供免費試用)

審核簡易PDF SDK使用情形

在解決方案目錄中執行以下命令,以識別所有 簡易 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 Printer() 使用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:更新命名空間引用

將 簡易 PDF SDK 命名空間替換為 IronPDF:

// 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當量 筆記
Printer ChromePdfRenderer 主轉換類
PDFDocument PdfDocument 文檔操作
HTMLConverter ChromePdfRenderer HTML轉換
PrinterConfiguration ChromePdfRenderOptions 渲染選項
PageOrientation PdfPaperOrientation 頁面方向
PageSize PdfPaperSize 紙張尺寸
SecurityHandler PdfDocument.SecuritySettings 安全選項

PDF 建立方法

簡易 PDF SDK 方法 IronPDF 方法 筆記
printer.RenderHTMLToPDF(html, path) 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) PDF檔案的URL

PDF 處理方法

簡易 PDF SDK 方法 IronPDF 方法 筆記
doc.Append(doc2) PdfDocument.Merge(pdf1, pdf2) 合併PDF
doc.ExtractPages(start, end) pdf.CopyPages(start, end) 提取頁面
doc.DeletePage(index) pdf.RemovePage(index) 移除頁面
doc.GetPageCount() pdf.PageCount 頁數
doc.Save(path) pdf.SaveAs(path) 儲存PDF
doc.Close() pdf.Dispose()using 清理
doc.ExtractText() pdf.ExtractAllText() 文字擷取

配置選項

簡易 PDF SDK 選項 IronPDF選項 筆記
config.TimeOut RenderingOptions.Timeout 超時時間(毫秒)
config.PageOrientation = Landscape RenderingOptions.PaperOrientation = Landscape 方向
config.PageSize = A4 RenderingOptions.PaperSize = PdfPaperSize.A4 紙張尺寸
config.MarginTop/Bottom/Left/Right RenderingOptions.MarginTop等。 邊際

程式碼遷移範例

轉換為 PDF 的 HTML 字串

簡易的 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 在 Web 環境中表現不佳。

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"]

解決常見遷移問題

問題:未找到印表機

症狀: Cannot find printer: BCL easyPDF Printer

解決方案: 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 error loadingRCW錯誤

解決方案:移除所有 COM 引用,並使用 IronPDF 的託管 API。

問題:伺服器逾時

症狀: Web 伺服器上的 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、Docker 和雲端原生架構,這意味著隨著專案擴展到 2025 年和 2026 年,您的遷移投資將獲得回報——而且沒有 簡易 PDF SDK 僅限 Windows 的限制。

其他資源

IronPDF 文件


從 簡易 PDF SDK 遷移到 IronPDF 可以消除對虛擬印表機的依賴、COM 互通問題以及僅限 Windows 的限制。 過渡到基於 Chromium 的渲染方式,可提供更強大的 CSS3 和 JavaScript 支持,同時能夠部署到 Docker、Kubernetes 和雲端環境,而這在 簡易 PDF SDK 的傳統架構中是無法實現的。

Curtis Chau
技術撰稿人

Curtis Chau 擁有電腦科學學士學位(卡爾頓大學),專長於前端開發,精通 Node.js、TypeScript、JavaScript 和 React。Curtis 對製作直覺且美觀的使用者介面充滿熱情,他喜歡使用現代化的架構,並製作結構良好且視覺上吸引人的手冊。

除了開發之外,Curtis 對物聯網 (IoT) 也有濃厚的興趣,他喜歡探索整合硬體與軟體的創新方式。在空閒時間,他喜歡玩遊戲和建立 Discord bots,將他對技術的熱愛與創意結合。