如何在 C# 中將 Easy PDF SDK 遷移到 IronPDF
Easy PDF SDK 依賴多種傳統技術,這為現代開發環境中的部署和維護帶來了重大挑戰。
簡易 PDF SDK 部署常見問題
開發人員在使用 簡易 PDF SDK 時經常會遇到以下問題:
bcl.easypdf.interop.easypdfprinter.dll error loadingCOM object that has been separated from its underlying RCW cannot be usedTimeout expired waiting for print job to completeThe printer operation failed because the service is not runningError: 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" .需要預見的重大變化
| 簡易 PDF SDK 模式 | 需要更改 |
|---|---|
new Printer() | 使用ChromePdfRenderer |
PrintOfficeDocToPDF() | 辦公轉換的處理方式不同 |
RenderHTMLToPDF() | RenderHtmlAsPdf() |
| COM 互通引用 | 完全移除 |
| 印表機驅動程式配置 | 不需要 |
BeginPrintToFile()回呼 | 原生 async/await |
| 互動環節要求 | 無頭模式運行 |
| 基於 1 的頁面索引 | 基於 0 的索引 |
| 超時時間(秒) | 超時時間(毫秒) |
逐步遷移過程
步驟 1:移除 Easy PDF SDK
Easy PDF SDK 通常透過 MSI 安裝程式、手動 DLL 引用或 GAC 註冊進行安裝。 刪除所有引用:
- 從"程式和功能"中卸載 BCL EasyPDF SDK
- 從項目中移除 DLL 引用
- 刪除 COM 互通引用
- 如有 GAC 條目,請清理。
步驟 2:安裝 IronPDF
# Install IronPDF
dotnet add package IronPdf# Install IronPDF
dotnet add package IronPdf或透過軟體包管理器控制台:
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;完整的 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();
}
}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");
}
}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();
}
}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");
}
}合併多個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();
}
}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");
}
}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");頁首和頁尾
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");更多選項請參閱頁首和頁尾文件。
異步 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();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");
}
}關鍵遷移說明
頁面索引更改
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);超時時間(毫秒)
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;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");
}
}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);問題:COM 互通錯誤
症狀: DLL error loading或RCW錯誤
解決方案:移除所有 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);問題:背景未列印。
症狀: CSS 背景缺失
解決方案:啟用背景列印:
renderer.RenderingOptions.PrintHtmlBackgrounds = true;renderer.RenderingOptions.PrintHtmlBackgrounds = true;遷移後檢查清單
程式碼遷移完成後,請驗證以下內容:
- 使用 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 的限制。
其他資源
從 簡易 PDF SDK 遷移到 IronPDF 可以消除對虛擬印表機的依賴、COM 互通問題以及僅限 Windows 的限制。 過渡到基於 Chromium 的渲染方式,可提供更強大的 CSS3 和 JavaScript 支持,同時能夠部署到 Docker、Kubernetes 和雲端環境,而這在 簡易 PDF SDK 的傳統架構中是無法實現的。






