跳過到頁腳內容
MIGRATION GUIDES

How to Migrate from Telerik Document Processing to IronPDF in C#

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 程式碼:


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

<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>
HTML

在 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
SHELL

安裝 IronPDF:

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

步驟 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;
$vbLabelText   $csharpLabel

步驟 3:新增許可證密鑰

應用程式啟動時初始化您的許可證:

// Add at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
// Add at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
$vbLabelText   $csharpLabel

步驟 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);
$vbLabelText   $csharpLabel

(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");
$vbLabelText   $csharpLabel

差異顯而易見: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);
}
$vbLabelText   $csharpLabel

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");
$vbLabelText   $csharpLabel

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);
}
$vbLabelText   $csharpLabel

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");
$vbLabelText   $csharpLabel

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);
}
$vbLabelText   $csharpLabel

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");
$vbLabelText   $csharpLabel

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");
$vbLabelText   $csharpLabel

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
};
$vbLabelText   $csharpLabel

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);
$vbLabelText   $csharpLabel

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" .
SHELL

記錄現有實現,包括使用的格式提供者、頁首/頁尾配置、自訂頁面設定以及任何流程文件模型修改。

遷徙期間

  1. 刪除 Telerik NuGet 套件
  2. 安裝 IronPdf NuGet 套件
  3. 使用Telerik.Windows.Documents中的語句更新IronPdf
  4. 新增啟動時許可證金鑰初始化功能
  5. HtmlFormatProvider替換為ChromePdfRenderer
  6. 刪除RadFlowDocument中間步驟
  7. PdfFormatProvider導出替換為直接的SaveAs()調用
  8. 更新頁首/頁尾,使用HtmlHeaderFooter
  9. 將頁面設定轉換為RenderingOptions
  10. 將邊際單位從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 版本、安全性修補程式和功能增強功能相容。

Curtis Chau
技術撰稿人

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

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