如何在 C# 中將 GemBox PDF 遷移到 IronPDF
從 GemBox PDF 遷移到 IronPDF 會將您的 .NET PDF 工作流程從基於座標的程式化文件建置轉變為基於現代 HTML/CSS 的渲染。 本指南提供了一個全面的、逐步的遷移路徑,消除了段落限制,簡化了專業 .NET 開發人員的文件建立。
為什麼要從 GemBox PDF 遷移到 IronPDF
GemBox PDF挑戰
GemBox PDF 是一個功能強大的 .NET PDF 元件,但它存在一些重大局限性,會影響實際開發:
1.免費版 20 段限制:免費版限制您只能寫 20 段,表格儲存格也計入此限制。 一個簡單的 10 行 5 列的表格需要 50 個"段落",這使得免費版本甚至無法用於基本的商業文件。
2.不支援 HTML 轉 PDF: GemBox PDF 需要透過程式設計建立文件。 您必須計算座標並手動定位每個元素——沒有簡單的"渲染此 HTML"功能。
3.基於座標的佈局:與 HTML/CSS 的佈局自然流暢不同,GemBox PDF 要求您計算每個文字元素、圖像和形狀的精確 X/Y 位置。
4.功能集有限:與全面的 PDF 庫相比,GemBox PDF 專注於基本操作——讀取、寫入、合併、拆分——而沒有 HTML 渲染或現代 CSS 支援等高級功能。
5.僅限程式化:任何設計變更都需要程式碼變更。 想調整間距嗎? 重新計算座標。 想要不同的字體大小?調整它下面的所有 Y 軸位置。
6.表格儲存格計數:段落限制會計算表格儲存格的數量,而不僅僅是可見段落的數量。這使得免費版本對於包含表格的文件來說幾乎毫無用處。
7.設計學習曲線:開發人員必須以座標而非文件流程來思考,這使得像"新增段落"這樣的簡單任務變得異常複雜。
GemBox PDF 與 IronPDF 對比
| 方面 | GemBox PDF | IronPDF |
|---|---|---|
| 免費版限制 | 20 段(包含表格儲存格) | 僅添加浮水印,無內容限制 |
| HTML 轉 PDF | 不支援 | 全鉻發動機 |
| 佈局方法 | 基於座標的手動 | HTML/CSS流程佈局 |
| 表格 | 計入段落限制 | 無限量,使用 HTML 表格 |
| 現代 CSS | 不適用 | Flexbox、Grid、CSS3動畫 |
| JavaScript 支援 | 不適用 | 完整的 JavaScript 執行 |
| 設計變更 | 重新計算座標 | 編輯 HTML/CSS |
| 學習曲線 | PDF座標系 | HTML/CSS(熟悉網頁設計) |
對於計劃在 2025 年和 2026 年採用 .NET 10 和 C# 14 的團隊,IronPDF 提供了一個面向未來的基礎,利用熟悉的 Web 技術來產生 PDF。
遷移複雜度評估
各功能預計工作量
| 特徵 | 遷移複雜性 | 筆記 |
|---|---|---|
| 載入/儲存PDF文件 | 非常低 | 直接方法映射 |
| 合併PDF | 非常低 | 直接方法映射 |
| 拆分PDF | 低的 | 頁面索引處理 |
| 文字擷取 | 非常低 | 直接方法映射 |
| 新增文字 | 中等的 | 座標 → HTML |
| 表格 | 低的 | 手動 → HTML 表格 |
| 圖片 | 低的 | 座標 → HTML |
| 水印 | 低的 | 不同的API |
| 密碼保護 | 中等的 | 不同的結構 |
| 表單字段 | 中等的 | API差異 |
範式轉移
GemBox PDF 遷移的最大變化是從基於座標的佈局轉變為HTML/CSS 佈局:
GemBox PDF:"在位置 (100, 700) 繪製文字"
IronPDF:"使用 CSS 樣式渲染此 HTML"對於熟悉 Web 技術的開發人員來說,這種範式轉移通常更容易,但需要以不同的方式思考 PDF 文件。
開始之前
先決條件
- .NET 版本: IronPDF 支援 .NET Framework 4.6.2+ 和 .NET Core 2.0+ / .NET 5/6/7/8/9+ 2.許可證密鑰:從ironpdf.com取得您的 IronPDF 許可證密鑰。 3.備份:建立一個用於遷移工作的分支
- HTML/CSS知識:具備基本知識會有幫助,但並非必要。
識別所有 GemBox PDF 使用情況
# Find all GemBox PDF references
grep -r "GemBox\.Pdf\|PdfDocument\|PdfPage\|PdfFormattedText\|ComponentInfo\.SetLicense" --include="*.cs" .
# Find package references
grep -r "GemBox\.Pdf" --include="*.csproj" .# Find all GemBox PDF references
grep -r "GemBox\.Pdf\|PdfDocument\|PdfPage\|PdfFormattedText\|ComponentInfo\.SetLicense" --include="*.cs" .
# Find package references
grep -r "GemBox\.Pdf" --include="*.csproj" .NuGet 套件變更
# Remove GemBox PDF
dotnet remove package GemBox.Pdf
# Install IronPDF
dotnet add package IronPdf# Remove GemBox PDF
dotnet remove package GemBox.Pdf
# Install IronPDF
dotnet add package IronPdf快速入門遷移
步驟 1:更新許可證配置
之前(GemBox PDF):
// Must call before any GemBox PDF operations
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
// Or for professional:
ComponentInfo.SetLicense("YOUR-PROFESSIONAL-LICENSE");// Must call before any GemBox PDF operations
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
// Or for professional:
ComponentInfo.SetLicense("YOUR-PROFESSIONAL-LICENSE");(IronPDF 之後):
// Set once at application startup
IronPdf.License.LicenseKey = "YOUR-IRONPDF-LICENSE-KEY";
// Or in appsettings.json:
// { "IronPdf.License.LicenseKey": "YOUR-LICENSE-KEY" }// Set once at application startup
IronPdf.License.LicenseKey = "YOUR-IRONPDF-LICENSE-KEY";
// Or in appsettings.json:
// { "IronPdf.License.LicenseKey": "YOUR-LICENSE-KEY" }步驟 2:更新命名空間導入
// Before (GemBox PDF)
using GemBox.Pdf;
using GemBox.Pdf.Content;
// After (IronPDF)
using IronPdf;
using IronPdf.Editing;// Before (GemBox PDF)
using GemBox.Pdf;
using GemBox.Pdf.Content;
// After (IronPDF)
using IronPdf;
using IronPdf.Editing;步驟 3:基本轉換模式
之前(GemBox PDF):
using GemBox.Pdf;
using GemBox.Pdf.Content;
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
using (var document = new PdfDocument())
{
var page = document.Pages.Add();
var formattedText = new PdfFormattedText()
{
Text = "Hello World",
FontSize = 24
};
page.Content.DrawText(formattedText, new PdfPoint(100, 700));
document.Save("output.pdf");
}using GemBox.Pdf;
using GemBox.Pdf.Content;
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
using (var document = new PdfDocument())
{
var page = document.Pages.Add();
var formattedText = new PdfFormattedText()
{
Text = "Hello World",
FontSize = 24
};
page.Content.DrawText(formattedText, new PdfPoint(100, 700));
document.Save("output.pdf");
}(IronPDF 之後):
using IronPdf;
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1 style='font-size:24px;'>Hello World</h1>");
pdf.SaveAs("output.pdf");using IronPdf;
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1 style='font-size:24px;'>Hello World</h1>");
pdf.SaveAs("output.pdf");主要區別: 無需進行座標計算 使用 HTML/CSS 而非程式化佈局
- 無段落限制 更簡潔、更易讀的程式碼
完整 API 參考
命名空間映射
| GemBox PDF | IronPDF |
|---|---|
GemBox.Pdf | IronPdf |
GemBox.Pdf.Content | IronPdf (內容為HTML) |
GemBox.Pdf.Security | IronPdf (安全設定) |
GemBox.Pdf.Forms | IronPdf.Forms |
核心類別映射
| GemBox PDF | IronPDF | 描述 |
|---|---|---|
PdfDocument | PdfDocument | 主 PDF 文件類 |
PdfPage | PdfDocument.Pages[i] | 頁面表示 |
PdfContent | 不適用(請使用 HTML) | 頁面內容 |
PdfFormattedText | 不適用(請使用 HTML) | 格式化文字 |
PdfPoint | 不適用(使用 CSS 定位) | 座標定位 |
ComponentInfo.SetLicense() | IronPdf.License.LicenseKey | 許可證管理 |
文檔操作
| GemBox PDF | IronPDF | 筆記 |
|---|---|---|
new PdfDocument() | new PdfDocument() | 建立新文檔 |
PdfDocument.Load(path) | PdfDocument.FromFile(path) | 從檔案載入 |
PdfDocument.Load(stream) | PdfDocument.FromStream(stream) | 從串流中載入 |
document.Save(path) | pdf.SaveAs(path) | 儲存到文件 |
document.Save(stream) | pdf.Stream或pdf.BinaryData | 取得流/位元組 |
頁面操作
| GemBox PDF | IronPDF | 筆記 |
|---|---|---|
document.Pages.Add() | 透過 HTML 渲染創建 | 新增頁面 |
document.Pages.Count | pdf.PageCount | 頁數 |
document.Pages[index] | pdf.Pages[index] | 造訪頁面(均從 0 開始索引) |
document.Pages.AddClone(pages) | PdfDocument.Merge() | 克隆/合併頁面 |
文字和內容操作
| GemBox PDF | IronPDF | 筆記 |
|---|---|---|
new PdfFormattedText() | HTML字串 | 文字內容 |
formattedText.FontSize = 12 | CSS font-size: 12pt | 字體大小 |
formattedText.Font = ... | CSS font-family: ... | 字體系列 |
page.Content.DrawText(text, point) | renderer.RenderHtmlAsPdf(html) | 渲染文字 |
page.Content.GetText() | pdf.ExtractTextFromPage(i) | 提取文字 |
程式碼遷移範例
範例 1:HTML 轉 PDF
之前(GemBox PDF):
// NuGet: Install-Package GemBox.Pdf
using GemBox.Pdf;
using GemBox.Pdf.Content;
class Program
{
static void Main()
{
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
var document = PdfDocument.Load("input.html");
document.Save("output.pdf");
}
}// NuGet: Install-Package GemBox.Pdf
using GemBox.Pdf;
using GemBox.Pdf.Content;
class Program
{
static void Main()
{
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
var document = PdfDocument.Load("input.html");
document.Save("output.pdf");
}
}(IronPDF 之後):
// NuGet: Install-Package IronPdf
using IronPdf;
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;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");
pdf.SaveAs("output.pdf");
}
}IronPDF 的ChromePdfRenderer使用現代 Chromium 引擎進行精確的 HTML/CSS/JavaScript 渲染。 與 GemBox PDF 有限的 HTML 支援不同,IronPDF 可以渲染任何 HTML 內容,並完全支援 CSS3 和 JavaScript。 如需更多渲染選項,請參閱HTML 轉 PDF 文件。
範例 2:合併 PDF 文件
之前(GemBox PDF):
// NuGet: Install-Package GemBox.Pdf
using GemBox.Pdf;
using System.Linq;
class Program
{
static void Main()
{
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
using (var document = new PdfDocument())
{
var source1 = PdfDocument.Load("document1.pdf");
var source2 = PdfDocument.Load("document2.pdf");
document.Pages.AddClone(source1.Pages);
document.Pages.AddClone(source2.Pages);
document.Save("merged.pdf");
}
}
}// NuGet: Install-Package GemBox.Pdf
using GemBox.Pdf;
using System.Linq;
class Program
{
static void Main()
{
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
using (var document = new PdfDocument())
{
var source1 = PdfDocument.Load("document1.pdf");
var source2 = PdfDocument.Load("document2.pdf");
document.Pages.AddClone(source1.Pages);
document.Pages.AddClone(source2.Pages);
document.Save("merged.pdf");
}
}
}(IronPDF 之後):
// NuGet: Install-Package IronPdf
using IronPdf;
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;
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");
}
}IronPDF 的靜態Merge方法簡化了操作—無需建立空白文檔並單獨複製頁面。 了解更多關於合併和拆分PDF的資訊。
範例 3:為 PDF 新增文本
之前(GemBox PDF):
// NuGet: Install-Package GemBox.Pdf
using GemBox.Pdf;
using GemBox.Pdf.Content;
class Program
{
static void Main()
{
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
using (var document = new PdfDocument())
{
var page = document.Pages.Add();
var formattedText = new PdfFormattedText()
{
Text = "Hello World",
FontSize = 24
};
page.Content.DrawText(formattedText, new PdfPoint(100, 700));
document.Save("output.pdf");
}
}
}// NuGet: Install-Package GemBox.Pdf
using GemBox.Pdf;
using GemBox.Pdf.Content;
class Program
{
static void Main()
{
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
using (var document = new PdfDocument())
{
var page = document.Pages.Add();
var formattedText = new PdfFormattedText()
{
Text = "Hello World",
FontSize = 24
};
page.Content.DrawText(formattedText, new PdfPoint(100, 700));
document.Save("output.pdf");
}
}
}(IronPDF 之後):
// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Editing;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<p>Original Content</p>");
var stamper = new TextStamper()
{
Text = "Hello World",
FontSize = 24,
HorizontalOffset = 100,
VerticalOffset = 700
};
pdf.ApplyStamp(stamper);
pdf.SaveAs("output.pdf");
}
}// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Editing;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<p>Original Content</p>");
var stamper = new TextStamper()
{
Text = "Hello World",
FontSize = 24,
HorizontalOffset = 100,
VerticalOffset = 700
};
pdf.ApplyStamp(stamper);
pdf.SaveAs("output.pdf");
}
}IronPDF 提供了TextStamper類,用於為現有 PDF 添加文本,該類提供精確的定位控制。 對於新文檔,只需將文字新增至 HTML 範本即可。 有關其他選項,請參閱沖壓文件。
範例 4:建立表格(最大的改進!)
(GemBox PDF 格式) - 每個儲存格都計入 20 段的限制:
using GemBox.Pdf;
using GemBox.Pdf.Content;
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
using (var document = new PdfDocument())
{
var page = document.Pages.Add();
double y = 700;
double[] xPositions = { 50, 200, 300, 400 };
// Headers (4 paragraphs)
var headers = new[] { "Product", "Price", "Qty", "Total" };
for (int i = 0; i < headers.Length; i++)
{
var text = new PdfFormattedText { Text = headers[i], FontSize = 12 };
page.Content.DrawText(text, new PdfPoint(xPositions[i], y));
}
y -= 20;
// Data rows (4 paragraphs per row!)
// Can only add a few rows before hitting 20-paragraph limit!
document.Save("products.pdf");
}using GemBox.Pdf;
using GemBox.Pdf.Content;
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
using (var document = new PdfDocument())
{
var page = document.Pages.Add();
double y = 700;
double[] xPositions = { 50, 200, 300, 400 };
// Headers (4 paragraphs)
var headers = new[] { "Product", "Price", "Qty", "Total" };
for (int i = 0; i < headers.Length; i++)
{
var text = new PdfFormattedText { Text = headers[i], FontSize = 12 };
page.Content.DrawText(text, new PdfPoint(xPositions[i], y));
}
y -= 20;
// Data rows (4 paragraphs per row!)
// Can only add a few rows before hitting 20-paragraph limit!
document.Save("products.pdf");
}(IronPDF)之後 - 無限制,支援規範的 HTML 表格:
using IronPdf;
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
var html = @"
<html>
<head>
<style>
table { border-collapse: collapse; width: 100%; }
th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
th { background-color: #4CAF50; color: white; }
tr:nth-child(even) { background-color: #f2f2f2; }
</style>
</head>
<body>
<table>
<thead>
<tr>
<th>Product</th>
<th>Price</th>
<th>Qty</th>
<th>Total</th>
</tr>
</thead>
<tbody>
<tr><td>Widget A</td><td>$19.99</td><td>5</td><td>$99.95</td></tr>
<tr><td>Widget B</td><td>$29.99</td><td>3</td><td>$89.97</td></tr>
<!-- Add hundreds or thousands of rows - no limit! -->
</tbody>
</table>
</body>
</html>";
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("products.pdf");using IronPdf;
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
var html = @"
<html>
<head>
<style>
table { border-collapse: collapse; width: 100%; }
th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
th { background-color: #4CAF50; color: white; }
tr:nth-child(even) { background-color: #f2f2f2; }
</style>
</head>
<body>
<table>
<thead>
<tr>
<th>Product</th>
<th>Price</th>
<th>Qty</th>
<th>Total</th>
</tr>
</thead>
<tbody>
<tr><td>Widget A</td><td>$19.99</td><td>5</td><td>$99.95</td></tr>
<tr><td>Widget B</td><td>$29.99</td><td>3</td><td>$89.97</td></tr>
<!-- Add hundreds or thousands of rows - no limit! -->
</tbody>
</table>
</body>
</html>";
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("products.pdf");這是 GemBox PDF 遷移中最顯著的改進。 GemBox PDF 免費版無法實現的表格,在 IronPDF 中可以完美運行,並支援完整的 CSS 樣式。
關鍵遷移說明
協調 CSS 定位
如果您需要像素級精確定位(類似 GemBox PDF 的座標系),請使用 CSS 絕對定位:
<div style="position:absolute; left:50px; top:750px; font-size:24px;">
Text positioned at specific coordinates
</div><div style="position:absolute; left:50px; top:750px; font-size:24px;">
Text positioned at specific coordinates
</div>頁面索引
GemBox PDF 和 IronPDF 都使用從 0 開始索引的頁面,因此遷移的這一部分非常簡單:
// GemBox PDF
var page = document.Pages[0];
// IronPDF
var page = pdf.Pages[0];// GemBox PDF
var page = document.Pages[0];
// IronPDF
var page = pdf.Pages[0];安全設定
// GemBox PDF
document.SaveOptions.SetPasswordEncryption(userPassword, ownerPassword);
// IronPDF
pdf.SecuritySettings.UserPassword = "userPassword";
pdf.SecuritySettings.OwnerPassword = "ownerPassword";// GemBox PDF
document.SaveOptions.SetPasswordEncryption(userPassword, ownerPassword);
// IronPDF
pdf.SecuritySettings.UserPassword = "userPassword";
pdf.SecuritySettings.OwnerPassword = "ownerPassword";故障排除
問題 1:未找到 PdfFormattedText
問題: IronPDF 中不存在PdfFormattedText 。
解決方案:使用 HTML 和 CSS 樣式:
// GemBox PDF
var text = new PdfFormattedText { Text = "Hello", FontSize = 24 };
// IronPDF
var html = "<p style='font-size:24px;'>Hello</p>";
var pdf = renderer.RenderHtmlAsPdf(html);// GemBox PDF
var text = new PdfFormattedText { Text = "Hello", FontSize = 24 };
// IronPDF
var html = "<p style='font-size:24px;'>Hello</p>";
var pdf = renderer.RenderHtmlAsPdf(html);問題 2:找不到 DrawText 方法
問題: page.Content.DrawText()不可用。
解決方案:透過 HTML 渲染建立內容或使用圖章:
// For new documents - render HTML
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Content</h1>");
// For existing documents - use stampers
var stamper = new TextStamper() { Text = "Added Text" };
pdf.ApplyStamp(stamper);// For new documents - render HTML
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Content</h1>");
// For existing documents - use stampers
var stamper = new TextStamper() { Text = "Added Text" };
pdf.ApplyStamp(stamper);問題 3:文檔載入差異
問題:未找到PdfDocument.Load() 。
解決方案:使用PdfDocument.FromFile()或FromStream() :
// GemBox PDF
var doc = PdfDocument.Load("input.pdf");
// IronPDF
var pdf = PdfDocument.FromFile("input.pdf");// GemBox PDF
var doc = PdfDocument.Load("input.pdf");
// IronPDF
var pdf = PdfDocument.FromFile("input.pdf");問題 4:保存方法差異
問題: document.Save()方法簽章不同。
解決方法:使用SaveAs() :
// GemBox PDF
document.Save("output.pdf");
// IronPDF
pdf.SaveAs("output.pdf");// GemBox PDF
document.Save("output.pdf");
// IronPDF
pdf.SaveAs("output.pdf");遷移清單
遷移前
- 清點程式碼庫中所有 GemBox PDF 的使用情況
- 識別需要轉換為 HTML 的基於座標的佈局
- 評估目前影響代碼的段落限制
- 取得 IronPDF 許可證密鑰
- 在版本控制系統中建立遷移分支
程式碼遷移
- 移除 GemBox PDF NuGet 套件:
dotnet remove package GemBox.Pdf安裝 IronPdf NuGet 套件:dotnet add package IronPdf - 更新命名空間匯入
- 將
ComponentInfo.SetLicense()替換為IronPdf.License.LicenseKey將PdfDocument.Load()轉換為PdfDocument.FromFile() - 將
document.Save()轉換為pdf.SaveAs() - 將基於座標的文字替換為 HTML 內容
- 將
PdfFormattedText轉換為帶有 CSS 樣式的 HTML - 更新合併操作,使用
PdfDocument.Merge()
測試
- 核實所有文件是否正確生成
- 驗證文檔外觀是否符合預期
- 測試表產生(之前受 20 段規則限制)
- 驗證文字擷取功能是否正常
- 測試合併和拆分操作
- 驗證安全性/加密功能
移民後
- 移除 GemBox PDF 授權金鑰
- 更新文檔
- 培訓團隊使用 HTML/CSS 方法製作 PDF 文件
- 暢享無段落限制的無限內容!






