如何使用 C# 將 Telerik 文件處理遷移到 IronPDF
Telerik Document Processing 作為 DevCraft 套件的一部分,為 .NET 生態系統提供服務,為開發人員提供 PDF 生成功能以及 Word、Excel 和 PowerPoint 處理功能。 然而,隨著現代網頁標準的演進,專案需要完全支援 CSS3、Flexbox 和 Bootstrap,許多開發團隊發現 Telerik 的 HTML 到 PDF 渲染架構有根本性的限制。
本指南提供了從 Telerik 文件處理到 IronPDF 的完整遷移路徑,包括逐步說明、程式碼比較以及直接取自真實遷移場景的實用範例。
為什麼要從 Telerik 文件處理遷移
從 Telerik 文件處理遷移的決定通常源自於處理現代 Web 內容時顯現出的技術限制。 了解這些限制有助於證明遷移工作的合理性,並設定對 IronPDF 能夠解決的問題的期望。
關鍵技術限制
Telerik 文件處理在處理現代 HTML 和 CSS 時存在根本性問題:
| 問題 | 影響 | IronPDF解決方案 |
|---|---|---|
| CSS解析限制 | 像 Bootstrap 這樣的現代 CSS 框架失敗了 | 完全支持 Chromium CSS |
| div 到段落的轉換 | HTML結構扁平化,佈局錯亂 | 直接 HTML 渲染 |
| 流程文件模型 | 中間轉換力 | 原生 HTML 轉 PDF |
| 外部 CSS 問題 | 複雜選擇器被忽略 | 完全支援 CSS 文件 |
| 記憶體問題 | 大型文件出現 OutOfMemoryException 異常 | 高效能串流媒體 |
核心問題:HTML渲染不正確
Telerik 文件處理在產生 PDF 之前,會將 HTML 轉換為中間的"流文檔"模型。 這種建築設計決策會引發一連串連鎖問題:
1.簡化 HTML 結構—<div>元素變成段落 2.完全忽略現代 CSS -Flexbox 和 Grid 佈局完全失效 3.破壞 Bootstrap-列系統無法正確渲染為列。 4.格式遺失-複雜的 CSS 選擇器會被忽略
請看以下使用標準 CSS 佈局的現代 HTML 程式碼:
<!-- This modern HTML/CSS BREAKS in Telerik 文件處理 -->
<div class="container">
<div class="row">
<div class="col-md-6">Column 1</div>
<div class="col-md-6">Column 2</div>
</div>
</div>
<div style="display: flex; gap: 20px;">
<div style="flex: 1;">Flex Item 1</div>
<div style="flex: 1;">Flex Item 2</div>
</div>
<div style="display: grid; grid-template-columns: repeat(3, 1fr);">
<div>Grid Item 1</div>
<div>Grid Item 2</div>
<div>Grid Item 3</div>
</div><!-- This modern HTML/CSS BREAKS in Telerik 文件處理 -->
<div class="container">
<div class="row">
<div class="col-md-6">Column 1</div>
<div class="col-md-6">Column 2</div>
</div>
</div>
<div style="display: flex; gap: 20px;">
<div style="flex: 1;">Flex Item 1</div>
<div style="flex: 1;">Flex Item 2</div>
</div>
<div style="display: grid; grid-template-columns: repeat(3, 1fr);">
<div>Grid Item 1</div>
<div>Grid Item 2</div>
<div>Grid Item 3</div>
</div>在 Telerik 文件處理中,所有這些佈局都會渲染成連續的段落。雙欄 Bootstrap 版面配置會顯示為兩行文字。 彈性盒子中的元素垂直堆疊。 CSS Grid 元素會依序顯示。
Telerik 文件處理中失效的 CSS 功能
開發人員已記錄了大量 CSS 相容性問題:
/* ❌ These CSS features DON'T WORK in Telerik 文件處理 */
/* Flexbox - 不支援 */
.container { display: flex; }
.item { flex: 1; }
/* CSS Grid - 不支援 */
.grid { display: grid; grid-template-columns: repeat(3, 1fr); }
/* Bootstrap columns - Converted to paragraphs */
.col-md-6 { /* Ignored, becomes linear text */ }
/* CSS Variables - 不支援 */
:root { --primary: #007bff; }
.btn { color: var(--primary); }
/* Complex selectors - Often ignored */
.container > .row:first-child { }
.item:hover { }
.content::before { }
/* Modern units - Limited support */
.box { width: calc(100% - 20px); }
.text { font-size: 1.2rem; }處理大型文件時的效能問題
除了 CSS 的限制之外,Telerik Document Processing 在處理大型檔案時也記錄了OutOfMemoryException錯誤。 開發團隊在處理大量文件產生時遇到了穩定性問題,而其他程式庫可以更有效地處理這些問題。
IronPDF 與 Telerik 文件處理:功能對比
了解功能差異有助於技術決策者評估遷移投資:
| 特徵 | Telerik 文件處理 | IronPDF |
|---|---|---|
| HTML渲染 | 流程文件轉換 | 直接鉻渲染 |
| CSS3 支持 | 功能有限,許多功能失效 | 完整的 CSS3 |
| Flexbox | 不支援 | 全力支持 |
| CSS Grid | 不支援 | 全力支持 |
| Bootstrap | 損壞(div 扁平化) | 全面支持,包括 Bootstrap 5 |
| 外部 CSS | 部分的 | 全力支持 |
| JavaScript | 不支援 | 完全支援 ES2024 |
| 大型文檔 | 記憶體問題 | 高效能串流媒體 |
| API複雜度 | 複雜(提供者、模型) | 簡單(單類) |
| 許可模式 | 商業用途,隸屬於 DevCraft | 簡易獨立許可 |
快速入門遷移:5 分鐘即可產生您的第一個 PDF 文件
從 Telerik 文件處理 遷移到 IronPDF 可以立即開始。 以下是使用 IronPDF 產生您的第一個 PDF 的最快方法。
步驟 1:更新 NuGet 套件
移除所有 Telerik 文件處理軟體包:
# Remove Telerik packages
dotnet remove package Telerik.Documents.Core
dotnet remove package Telerik.Documents.Flow
dotnet remove package Telerik.Documents.Flow.FormatProviders.Pdf
dotnet remove package Telerik.Documents.Fixed# Remove Telerik packages
dotnet remove package Telerik.Documents.Core
dotnet remove package Telerik.Documents.Flow
dotnet remove package Telerik.Documents.Flow.FormatProviders.Pdf
dotnet remove package Telerik.Documents.Fixed安裝 IronPDF:
# Install IronPDF
dotnet add package IronPdf# Install IronPDF
dotnet add package IronPdf步驟 2:更新 Using 語句
將 Telerik 命名空間替換為 IronPdf 命名空間:
// Before (Telerik Document Processing)
using Telerik.Windows.Documents.Flow.FormatProviders.Html;
using Telerik.Windows.Documents.Flow.FormatProviders.Pdf;
using Telerik.Windows.Documents.Flow.Model;
using Telerik.Documents.Primitives;
// After (IronPDF)
using IronPdf;// Before (Telerik Document Processing)
using Telerik.Windows.Documents.Flow.FormatProviders.Html;
using Telerik.Windows.Documents.Flow.FormatProviders.Pdf;
using Telerik.Windows.Documents.Flow.Model;
using Telerik.Documents.Primitives;
// After (IronPDF)
using IronPdf;步驟 3:新增許可證密鑰
應用程式啟動時初始化您的許可證:
// Add at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";// Add at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";步驟 4:更新您的 PDF 產生程式碼
從 Telerik 文件處理系統遷移到 IronPDF 系統,可以顯著簡化您的程式碼庫。
(Telerik 文件處理之前):
using Telerik.Windows.Documents.Flow.FormatProviders.Html;
using Telerik.Windows.Documents.Flow.FormatProviders.Pdf;
using Telerik.Windows.Documents.Flow.Model;
HtmlFormatProvider htmlProvider = new HtmlFormatProvider();
RadFlowDocument document = htmlProvider.Import(htmlContent);
PdfFormatProvider pdfProvider = new PdfFormatProvider();
byte[] pdfBytes = pdfProvider.Export(document);
File.WriteAllBytes("output.pdf", pdfBytes);using Telerik.Windows.Documents.Flow.FormatProviders.Html;
using Telerik.Windows.Documents.Flow.FormatProviders.Pdf;
using Telerik.Windows.Documents.Flow.Model;
HtmlFormatProvider htmlProvider = new HtmlFormatProvider();
RadFlowDocument document = htmlProvider.Import(htmlContent);
PdfFormatProvider pdfProvider = new PdfFormatProvider();
byte[] pdfBytes = pdfProvider.Export(document);
File.WriteAllBytes("output.pdf", pdfBytes);(IronPDF 之後):
using IronPdf;
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);
pdf.SaveAs("output.pdf");using IronPdf;
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);
pdf.SaveAs("output.pdf");差異顯而易見:3 行 IronPDF 程式碼取代了 15 行以上的 Telerik 文件處理程式碼。 更重要的是,IronPDF 版本能夠正確渲染 Telerik 的 Flow Document 模型無法處理的現代 CSS。
程式碼遷移範例
將 HTML 轉換為 PDF
這是PDF產生最常見的應用場景。 透過此比較,Telerik Document Processing 和 IronPDF 之間的架構差異將變得清晰明了。
Telerik 文件處理方法:
// NuGet: Install-Package Telerik.Documents.Flow
// NuGet: Install-Package Telerik.Documents.Flow.FormatProviders.Pdf
using Telerik.Windows.Documents.Flow.FormatProviders.Html;
using Telerik.Windows.Documents.Flow.FormatProviders.Pdf;
using Telerik.Windows.Documents.Flow.Model;
using System.IO;
string html = "<html><body><h1>Hello World</h1><p>This is a PDF document.</p></body></html>";
HtmlFormatProvider htmlProvider = new HtmlFormatProvider();
RadFlowDocument document = htmlProvider.Import(html);
PdfFormatProvider pdfProvider = new PdfFormatProvider();
using (FileStream output = File.OpenWrite("output.pdf"))
{
pdfProvider.Export(document, output);
}// NuGet: Install-Package Telerik.Documents.Flow
// NuGet: Install-Package Telerik.Documents.Flow.FormatProviders.Pdf
using Telerik.Windows.Documents.Flow.FormatProviders.Html;
using Telerik.Windows.Documents.Flow.FormatProviders.Pdf;
using Telerik.Windows.Documents.Flow.Model;
using System.IO;
string html = "<html><body><h1>Hello World</h1><p>This is a PDF document.</p></body></html>";
HtmlFormatProvider htmlProvider = new HtmlFormatProvider();
RadFlowDocument document = htmlProvider.Import(html);
PdfFormatProvider pdfProvider = new PdfFormatProvider();
using (FileStream output = File.OpenWrite("output.pdf"))
{
pdfProvider.Export(document, output);
}IronPDF 方法:
// NuGet: Install-Package IronPdf
using IronPdf;
string html = "<html><body><h1>Hello World</h1><p>This is a PDF document.</p></body></html>";
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");// NuGet: Install-Package IronPdf
using IronPdf;
string html = "<html><body><h1>Hello World</h1><p>This is a PDF document.</p></body></html>";
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");Telerik 版本需要建立HtmlFormatProvider ,匯入到RadFlowDocument ,建立PdfFormatProvider ,並手動管理檔案流。 IronPDF 的ChromePdfRenderer透過一次方法呼叫即可處理整個過程。
如需更進階的 HTML 轉 PDF 場景,請參閱HTML 轉 PDF 轉換指南。
將 URL 轉換為 PDF
將網頁捕獲為 PDF 會揭示這些庫之間的另一個顯著差異。
Telerik 文件處理方法:
// NuGet: Install-Package Telerik.Documents.Flow
// NuGet: Install-Package Telerik.Documents.Flow.FormatProviders.Pdf
using Telerik.Windows.Documents.Flow.FormatProviders.Html;
using Telerik.Windows.Documents.Flow.FormatProviders.Pdf;
using Telerik.Windows.Documents.Flow.Model;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;
string url = "https://example.com";
using HttpClient client = new HttpClient();
string html = await client.GetStringAsync(url);
HtmlFormatProvider htmlProvider = new HtmlFormatProvider();
RadFlowDocument document = htmlProvider.Import(html);
PdfFormatProvider pdfProvider = new PdfFormatProvider();
using (FileStream output = File.OpenWrite("webpage.pdf"))
{
pdfProvider.Export(document, output);
}// NuGet: Install-Package Telerik.Documents.Flow
// NuGet: Install-Package Telerik.Documents.Flow.FormatProviders.Pdf
using Telerik.Windows.Documents.Flow.FormatProviders.Html;
using Telerik.Windows.Documents.Flow.FormatProviders.Pdf;
using Telerik.Windows.Documents.Flow.Model;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;
string url = "https://example.com";
using HttpClient client = new HttpClient();
string html = await client.GetStringAsync(url);
HtmlFormatProvider htmlProvider = new HtmlFormatProvider();
RadFlowDocument document = htmlProvider.Import(html);
PdfFormatProvider pdfProvider = new PdfFormatProvider();
using (FileStream output = File.OpenWrite("webpage.pdf"))
{
pdfProvider.Export(document, output);
}IronPDF 方法:
// NuGet: Install-Package IronPdf
using IronPdf;
string url = "https://example.com";
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderUrlAsPdf(url);
pdf.SaveAs("webpage.pdf");// NuGet: Install-Package IronPdf
using IronPdf;
string url = "https://example.com";
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderUrlAsPdf(url);
pdf.SaveAs("webpage.pdf");Telerik 文件處理系統本身不具備 URL 轉 PDF 功能。 您必須使用HttpClient手動取得 HTML 內容,在此過程中會遺失外部 CSS、JavaScript 執行和動態內容。 IronPDF 的RenderUrlAsPdf方法可以完全捕捉渲染後的頁面,就像它在瀏覽器中顯示的那樣。
查看PDF 文件的 URL,以了解更多選項,包括身份驗證和自訂標頭。
合併多個PDF文件
PDF 合併展示了這些 .NET PDF 函式庫在冗長程度上的差異。
Telerik 文件處理方法:
// NuGet: Install-Package Telerik.Documents.Fixed
using Telerik.Windows.Documents.Fixed.FormatProviders.Pdf;
using Telerik.Windows.Documents.Fixed.Model;
using System.IO;
PdfFormatProvider provider = new PdfFormatProvider();
RadFixedDocument document1;
using (FileStream input = File.OpenRead("document1.pdf"))
{
document1 = provider.Import(input);
}
RadFixedDocument document2;
using (FileStream input = File.OpenRead("document2.pdf"))
{
document2 = provider.Import(input);
}
RadFixedDocument mergedDocument = new RadFixedDocument();
foreach (var page in document1.Pages)
{
mergedDocument.Pages.Add(page);
}
foreach (var page in document2.Pages)
{
mergedDocument.Pages.Add(page);
}
using (FileStream output = File.OpenWrite("merged.pdf"))
{
provider.Export(mergedDocument, output);
}// NuGet: Install-Package Telerik.Documents.Fixed
using Telerik.Windows.Documents.Fixed.FormatProviders.Pdf;
using Telerik.Windows.Documents.Fixed.Model;
using System.IO;
PdfFormatProvider provider = new PdfFormatProvider();
RadFixedDocument document1;
using (FileStream input = File.OpenRead("document1.pdf"))
{
document1 = provider.Import(input);
}
RadFixedDocument document2;
using (FileStream input = File.OpenRead("document2.pdf"))
{
document2 = provider.Import(input);
}
RadFixedDocument mergedDocument = new RadFixedDocument();
foreach (var page in document1.Pages)
{
mergedDocument.Pages.Add(page);
}
foreach (var page in document2.Pages)
{
mergedDocument.Pages.Add(page);
}
using (FileStream output = File.OpenWrite("merged.pdf"))
{
provider.Export(mergedDocument, output);
}IronPDF 方法:
// NuGet: Install-Package IronPdf
using IronPdf;
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;
var pdf1 = PdfDocument.FromFile("document1.pdf");
var pdf2 = PdfDocument.FromFile("document2.pdf");
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("merged.pdf");Telerik 版本需要分別匯入每個文檔,手動遍歷頁面,將它們新增到新文檔中,並管理多個文件流程。 IronPDF 的PdfDocument.Merge()方法只需一次呼叫即可處理所有操作。
對於包含選擇性頁面擷取在內的進階合併場景,請參閱合併和分割 PDF 指南。
Telerik 文件處理 API 到 IronPDF 的映射
此參考表透過顯示直接對應的 API 來加快遷移速度:
| Telerik 文件處理 | IronPDF | 筆記 |
|---|---|---|
HtmlFormatProvider | ChromePdfRenderer | 建立用於生成 PDF 的渲染器 |
RadFlowDocument | 不需要 | IronPDF 直接渲染 HTML |
PdfFormatProvider | pdf.SaveAs() | 直接保存,無需服務提供者 |
RadFlowDocumentEditor | HTML 操作 | 在渲染之前編輯 HTML |
Section | HTML<section> | 使用語義化 HTML |
Paragraph | HTML<p> | 標準 HTML 元素 |
PdfExportSettings | RenderingOptions | 配置輸出設定 |
RadFixedDocument | PdfDocument | 處理現有PDF文件 |
| 手動頁面迭代 | PdfDocument.Merge() | 內建合併方法 |
處理頁首和頁尾
Telerik 文件處理採用程式化模型來處理頁首和頁尾。 IronPDF 提供基於 HTML 的動態佔位符標題。
Telerik 文件處理:
section.Headers.Default.Blocks.AddParagraph().Inlines.AddRun("Header Text");
section.Footers.Default.Blocks.AddParagraph().Inlines.AddRun("Footer Text");section.Headers.Default.Blocks.AddParagraph().Inlines.AddRun("Header Text");
section.Footers.Default.Blocks.AddParagraph().Inlines.AddRun("Footer Text");IronPDF:
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
HtmlFragment = "<div style='text-align:center;'>Header Text</div>",
MaxHeight = 25
};
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter()
{
HtmlFragment = "<div style='text-align:center;'>Footer Text</div>",
MaxHeight = 25
};renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
HtmlFragment = "<div style='text-align:center;'>Header Text</div>",
MaxHeight = 25
};
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter()
{
HtmlFragment = "<div style='text-align:center;'>Footer Text</div>",
MaxHeight = 25
};IronPDF 以 HTML 為基礎的方法允許在頁首和頁尾中使用完整的 CSS 樣式,以及頁碼和日期的動態佔位符。 更多資訊請參閱頁首和頁尾文件。
單位換算:DIP封裝到毫米
Telerik 文件處理採用與裝置無關的像素 (DIP) 進行測量。 IronPDF 使用毫米作為單位。 這需要在遷移過程中進行轉換:
// Telerik uses DIPs (device-independent pixels)
// IronPDF uses millimeters
// 1 inch = 25.4mm
renderer.RenderingOptions.MarginTop = 25.4; // 1 inch
renderer.RenderingOptions.MarginBottom = 25.4;
// Or use the helper method for paper size
renderer.RenderingOptions.SetCustomPaperSizeInInches(8.5, 11);// Telerik uses DIPs (device-independent pixels)
// IronPDF uses millimeters
// 1 inch = 25.4mm
renderer.RenderingOptions.MarginTop = 25.4; // 1 inch
renderer.RenderingOptions.MarginBottom = 25.4;
// Or use the helper method for paper size
renderer.RenderingOptions.SetCustomPaperSizeInInches(8.5, 11);Telerik 文件處理遷移清單
遷移前任務
審核您的程式碼庫,找出所有 Telerik 文件處理 的使用情況:
grep -r "using Telerik.Windows.Documents" --include="*.cs" .
grep -r "RadFlowDocument\|HtmlFormatProvider\|PdfFormatProvider" --include="*.cs" .grep -r "using Telerik.Windows.Documents" --include="*.cs" .
grep -r "RadFlowDocument\|HtmlFormatProvider\|PdfFormatProvider" --include="*.cs" .記錄現有實現,包括使用的格式提供者、頁首/頁尾配置、自訂頁面設定以及任何流程文件模型修改。
遷徙期間
- 刪除 Telerik NuGet 套件
- 安裝 IronPdf NuGet 套件
- 使用
Telerik.Windows.Documents中的語句更新IronPdf - 新增啟動時許可證金鑰初始化功能
- 將
HtmlFormatProvider替換為ChromePdfRenderer - 刪除
RadFlowDocument中間步驟 - 將
PdfFormatProvider導出替換為直接的SaveAs()調用 - 更新頁首/頁尾,使用
HtmlHeaderFooter - 將頁面設定轉換為
RenderingOptions - 將邊際單位從DIP更新為毫米
遷移後驗證
遷移完成後,請先驗證以下改進:
CSS渲染效果應該會顯著提升。
- Bootstrap佈局應該能夠正確渲染(但在Telerik中無法正確渲染)。
- Flexbox 和 Grid 佈局應該可以正常工作(但在 Telerik 中不行)
- JavaScript 執行功能應能處理動態內容
- 大型文件產生過程應順利完成,不應出現記憶體異常。
遷移到 IronPDF 的主要優勢
從 Telerik 文件處理系統遷移到 IronPDF 可立即帶來以下優勢:
現代 Chromium 渲染引擎: IronPDF 使用與 Google Chrome 相同的渲染引擎,確保 PDF 檔案能夠像在現代瀏覽器中一樣準確地渲染。 這樣就消除了 Telerik 的 Flow Document 模型中固有的 CSS 相容性問題。
完全支援 CSS3 和 JavaScript: Flexbox、Grid、Bootstrap 5、CSS 變數和現代 JavaScript 均可正常運作。 隨著 .NET 10 和 C# 14 的普及,IronPDF 的現代渲染技術確保了與當代 Web 標準的兼容性。
更簡單的 API:更少的程式碼行數、沒有中間文件模型以及直覺的方法名稱,可減少開發時間和維護負擔。
獨立許可: IronPDF 提供簡單的許可方式,無需購買完整的套件,為只需要 PDF 功能的團隊提供了經濟高效的解決方案。
積極開發:定期更新確保與目前和未來的 .NET 版本、安全性修補程式和功能增強功能相容。






