跳過到頁腳內容
MIGRATION GUIDES

How to Migrate from HiQPdf to IronPDF in C#

HiQPdf 是一個商業化的 HTML 轉 PDF 庫,但它存在一些令人擔憂的局限性,會影響其在生產環境中的應用:

1.限制性"免費"版本:免費版本限制為 3 頁,並帶有侵入性浮水印——對於需要完整生成文件的生產工作負載來說,基本上無法使用。

2.較舊的 WebKit 引擎: HiQPdf 使用的是較舊的基於 WebKit 的渲染引擎,該引擎難以處理 React、Angular 和 Vue 等現代 JavaScript 框架。

  1. .NET Core 支援不明確:文件沒有明確說明 .NET Core / .NET 5+ 支援情況,為現代應用程式開發帶來了不確定性。

4.分散的套件:針對不同平台的多個 NuGet 套件(HiQPdf、HiQPdf.Free、HiQPdf.NetCore、HiQPdf.NetCore.x64、HiQPdf.Client)使依賴項管理變得複雜。

  1. API 複雜:需要透過DocumentHeaderFooter屬性鏈進行冗長的配置,而不是流暢、直覺的方法。

  2. JavaScript 支援有限: WebKit 引擎在渲染現代 JavaScript 框架和複雜動態佈局產生的內容方面有挑戰。

HiQPDF 與 IronPDF 的比較

方面 HiQPdf IronPDF
渲染引擎 基於 WebKit 的(舊版) 現代鉻
免費套餐 3頁限制 + 浮水印 30 天完整試用期
現代 JS 支持 有限的 完整(React、Angular、Vue)
支援 .NET Core/5+ 需要多個包裹 單一統一包裝
API設計 複雜的產權鏈 簡潔流暢的 API
CSS3 支持 部分的 全力支持
文件 碎片化的 綜合的
NuGet 套件 多種變體 單包裝

對於計劃在 2025 年和 2026 年採用 .NET 10 和 C# 14 的團隊,IronPDF 提供了一個面向未來的基礎,它對最新的 .NET 版本和現代 Chromium 渲染引擎提供了文件支援。


遷移複雜度評估

各功能預計工作量

特徵 遷移複雜性 筆記
HTML 轉 PDF 非常低 直接替代法
PDF檔案的URL 非常低 直接替代法
合併PDF 低的 不同的合併方法
頁首/頁尾 中等的 佔位符語法更改
頁面尺寸/頁邊距 低的 單位相同(毫米)
觸發模式/延遲 低的 屬性映射

範式轉移

HiQPdf 遷移的根本轉變在於從屬性鏈配置轉向流暢的渲染選項:

HiQPdf: converter.Document.Header.Height = 50;
          converter.Document.Header.Add(new HtmlToPdfVariableElement(...));

IronPDF:renderer.RenderingOptions.TextHeader = new TextHeaderFooter() { ... };

開始之前

先決條件

  1. .NET 版本: IronPDF 支援 .NET Framework 4.6.2+ 和 .NET Core 3.1+ / .NET 5/6/7/8/9+ 2.許可證密鑰:ironpdf.com取得您的 IronPDF 許可證密鑰。 3.移除 HiQPdf:計畫移除所有 HiQPdf NuGet 套件變體。

識別所有 HiQPDF 使用情況

# Find HiQPdf namespace usage
grep -r "using HiQPdf\|HtmlToPdf\|PdfDocument" --include="*.cs" .

# Find header/footer usage
grep -r "\.Header\.\|\.Footer\.\|HtmlToPdfVariableElement" --include="*.cs" .

# Find placeholder syntax
grep -r "CrtPage\|PageCount" --include="*.cs" .

# Find NuGet references
grep -r "HiQPdf" --include="*.csproj" .
# Find HiQPdf namespace usage
grep -r "using HiQPdf\|HtmlToPdf\|PdfDocument" --include="*.cs" .

# Find header/footer usage
grep -r "\.Header\.\|\.Footer\.\|HtmlToPdfVariableElement" --include="*.cs" .

# Find placeholder syntax
grep -r "CrtPage\|PageCount" --include="*.cs" .

# Find NuGet references
grep -r "HiQPdf" --include="*.csproj" .
SHELL

NuGet 套件變更

# Remove all HiQPdf variants
dotnet remove package HiQPdf
dotnet remove package HiQPdf.Free
dotnet remove package HiQPdf.NetCore
dotnet remove package HiQPdf.NetCore.x64
dotnet remove package HiQPdf.Client

# Install IronPDF (single package for all platforms)
dotnet add package IronPdf
# Remove all HiQPdf variants
dotnet remove package HiQPdf
dotnet remove package HiQPdf.Free
dotnet remove package HiQPdf.NetCore
dotnet remove package HiQPdf.NetCore.x64
dotnet remove package HiQPdf.Client

# Install IronPDF (single package for all platforms)
dotnet add package IronPdf
SHELL

快速入門遷移

步驟 1:更新許可證配置

之前(HiQPdf):

HtmlToPdf converter = new HtmlToPdf();
converter.SerialNumber = "HIQPDF-SERIAL-NUMBER";
HtmlToPdf converter = new HtmlToPdf();
converter.SerialNumber = "HIQPDF-SERIAL-NUMBER";
$vbLabelText   $csharpLabel

(IronPDF 之後):

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

步驟 2:更新命名空間導入

// Before (HiQPdf)
using HiQPdf;

// After (IronPDF)
using IronPdf;
using IronPdf.Rendering;
// Before (HiQPdf)
using HiQPdf;

// After (IronPDF)
using IronPdf;
using IronPdf.Rendering;
$vbLabelText   $csharpLabel

完整 API 參考

主類別映射

HiQPdf 類 IronPDF 類 筆記
HtmlToPdf ChromePdfRenderer 主轉換器類
PdfDocument PdfDocument 同名,不同命名空間
HtmlToPdfVariableElement TextHeaderFooterHtmlHeaderFooter 頁首/頁尾內容

轉換方法映射

HiQPdf 方法 IronPDF 方法 筆記
ConvertHtmlToMemory(html, baseUrl) RenderHtmlAsPdf(html) 返回PdfDocument
ConvertUrlToMemory(url) RenderUrlAsPdf(url) 返回PdfDocument
File.WriteAllBytes(path, bytes) pdf.SaveAs(path) 直接保存方法

PDF文檔方法映射

HiQPdf 方法 IronPDF 方法 筆記
PdfDocument.FromFile(path) PdfDocument.FromFile(path) 相同的方法名稱
document1.AddDocument(document2) PdfDocument.Merge(pdf1, pdf2) 靜態合併方法
document.WriteToFile(path) pdf.SaveAs(path) 不同的方法名稱

頁首/頁尾佔位符映射

HiQPDF佔位符 IronPDF佔位符 描述
{CrtPage} {page} 目前頁碼
{PageCount} {total-pages} 總頁數

程式碼遷移範例

範例 1:HTML 轉 PDF

之前(HiQPdf):

// NuGet: Install-Package HiQPdf
using HiQPdf;
using System;

class Program
{
    static void Main()
    {
        HtmlToPdf htmlToPdfConverter = new HtmlToPdf();
        byte[] pdfBuffer = htmlToPdfConverter.ConvertUrlToMemory("https://example.com");
        System.IO.File.WriteAllBytes("output.pdf", pdfBuffer);

        // Convert HTML string
        string html = "<h1>Hello World</h1><p>This is a PDF document.</p>";
        byte[] pdfFromHtml = htmlToPdfConverter.ConvertHtmlToMemory(html, "");
        System.IO.File.WriteAllBytes("fromhtml.pdf", pdfFromHtml);
    }
}
// NuGet: Install-Package HiQPdf
using HiQPdf;
using System;

class Program
{
    static void Main()
    {
        HtmlToPdf htmlToPdfConverter = new HtmlToPdf();
        byte[] pdfBuffer = htmlToPdfConverter.ConvertUrlToMemory("https://example.com");
        System.IO.File.WriteAllBytes("output.pdf", pdfBuffer);

        // Convert HTML string
        string html = "<h1>Hello World</h1><p>This is a PDF document.</p>";
        byte[] pdfFromHtml = htmlToPdfConverter.ConvertHtmlToMemory(html, "");
        System.IO.File.WriteAllBytes("fromhtml.pdf", pdfFromHtml);
    }
}
$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("output.pdf");

        // Convert HTML string
        string html = "<h1>Hello World</h1><p>This is a PDF document.</p>";
        var pdfFromHtml = renderer.RenderHtmlAsPdf(html);
        pdfFromHtml.SaveAs("fromhtml.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("output.pdf");

        // Convert HTML string
        string html = "<h1>Hello World</h1><p>This is a PDF document.</p>";
        var pdfFromHtml = renderer.RenderHtmlAsPdf(html);
        pdfFromHtml.SaveAs("fromhtml.pdf");
    }
}
$vbLabelText   $csharpLabel

HiQPdf 的方法需要建立一個HtmlToPdf實例,呼叫ConvertUrlToMemory()ConvertHtmlToMemory()取得位元組數組,然後手動將位元組寫入檔案。 IronPDF 的ChromePdfRenderer返回一個帶有直接SaveAs()方法的PdfDocument對象,省去了手動寫入文件的步驟。現代 Chromium 引擎還能更能渲染複雜的 HTML/CSS/JavaScript 內容。 有關其他渲染選項,請參閱HTML 轉 PDF 文件

範例 2:合併多個 PDF 文件

之前(HiQPdf):

// NuGet: Install-Package HiQPdf
using HiQPdf;
using System;

class Program
{
    static void Main()
    {
        // Create first PDF
        HtmlToPdf converter1 = new HtmlToPdf();
        byte[] pdf1 = converter1.ConvertHtmlToMemory("<h1>First Document</h1>", "");
        System.IO.File.WriteAllBytes("doc1.pdf", pdf1);

        // Create second PDF
        HtmlToPdf converter2 = new HtmlToPdf();
        byte[] pdf2 = converter2.ConvertHtmlToMemory("<h1>Second Document</h1>", "");
        System.IO.File.WriteAllBytes("doc2.pdf", pdf2);

        // Merge PDFs
        PdfDocument document1 = PdfDocument.FromFile("doc1.pdf");
        PdfDocument document2 = PdfDocument.FromFile("doc2.pdf");
        document1.AddDocument(document2);
        document1.WriteToFile("merged.pdf");
    }
}
// NuGet: Install-Package HiQPdf
using HiQPdf;
using System;

class Program
{
    static void Main()
    {
        // Create first PDF
        HtmlToPdf converter1 = new HtmlToPdf();
        byte[] pdf1 = converter1.ConvertHtmlToMemory("<h1>First Document</h1>", "");
        System.IO.File.WriteAllBytes("doc1.pdf", pdf1);

        // Create second PDF
        HtmlToPdf converter2 = new HtmlToPdf();
        byte[] pdf2 = converter2.ConvertHtmlToMemory("<h1>Second Document</h1>", "");
        System.IO.File.WriteAllBytes("doc2.pdf", pdf2);

        // Merge PDFs
        PdfDocument document1 = PdfDocument.FromFile("doc1.pdf");
        PdfDocument document2 = PdfDocument.FromFile("doc2.pdf");
        document1.AddDocument(document2);
        document1.WriteToFile("merged.pdf");
    }
}
$vbLabelText   $csharpLabel

(IronPDF 之後):

// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();

        // Create first PDF
        var pdf1 = renderer.RenderHtmlAsPdf("<h1>First Document</h1>");
        pdf1.SaveAs("doc1.pdf");

        // Create second PDF
        var pdf2 = renderer.RenderHtmlAsPdf("<h1>Second Document</h1>");
        pdf2.SaveAs("doc2.pdf");

        // Merge PDFs
        var merged = PdfDocument.Merge(pdf1, pdf2);
        merged.SaveAs("merged.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();

        // Create first PDF
        var pdf1 = renderer.RenderHtmlAsPdf("<h1>First Document</h1>");
        pdf1.SaveAs("doc1.pdf");

        // Create second PDF
        var pdf2 = renderer.RenderHtmlAsPdf("<h1>Second Document</h1>");
        pdf2.SaveAs("doc2.pdf");

        // Merge PDFs
        var merged = PdfDocument.Merge(pdf1, pdf2);
        merged.SaveAs("merged.pdf");
    }
}
$vbLabelText   $csharpLabel

HiQPdf 方法需要使用PdfDocument.FromFile()從文件中載入文檔,對第一個文檔呼叫AddDocument()以追加第二個文檔,然後使用WriteToFile()儲存。 IronPDF 提供了一個更簡潔的靜態PdfDocument.Merge()方法,直接接受多個PdfDocument物件-無需中間文件操作。 了解更多關於合併和拆分PDF的資訊

範例 3:帶有頁碼的 PDF 頁首和頁尾

之前(HiQPdf):

// NuGet: Install-Package HiQPdf
using HiQPdf;
using System;

class Program
{
    static void Main()
    {
        HtmlToPdf htmlToPdfConverter = new HtmlToPdf();

        // Add header
        htmlToPdfConverter.Document.Header.Height = 50;
        HtmlToPdfVariableElement headerHtml = new HtmlToPdfVariableElement("<div style='text-align:center'>Page Header</div>", "");
        htmlToPdfConverter.Document.Header.Add(headerHtml);

        // Add footer with page number
        htmlToPdfConverter.Document.Footer.Height = 50;
        HtmlToPdfVariableElement footerHtml = new HtmlToPdfVariableElement("<div style='text-align:center'>Page {CrtPage} of {PageCount}</div>", "");
        htmlToPdfConverter.Document.Footer.Add(footerHtml);

        byte[] pdfBuffer = htmlToPdfConverter.ConvertHtmlToMemory("<h1>Document with Headers and Footers</h1>", "");
        System.IO.File.WriteAllBytes("header-footer.pdf", pdfBuffer);
    }
}
// NuGet: Install-Package HiQPdf
using HiQPdf;
using System;

class Program
{
    static void Main()
    {
        HtmlToPdf htmlToPdfConverter = new HtmlToPdf();

        // Add header
        htmlToPdfConverter.Document.Header.Height = 50;
        HtmlToPdfVariableElement headerHtml = new HtmlToPdfVariableElement("<div style='text-align:center'>Page Header</div>", "");
        htmlToPdfConverter.Document.Header.Add(headerHtml);

        // Add footer with page number
        htmlToPdfConverter.Document.Footer.Height = 50;
        HtmlToPdfVariableElement footerHtml = new HtmlToPdfVariableElement("<div style='text-align:center'>Page {CrtPage} of {PageCount}</div>", "");
        htmlToPdfConverter.Document.Footer.Add(footerHtml);

        byte[] pdfBuffer = htmlToPdfConverter.ConvertHtmlToMemory("<h1>Document with Headers and Footers</h1>", "");
        System.IO.File.WriteAllBytes("header-footer.pdf", pdfBuffer);
    }
}
$vbLabelText   $csharpLabel

(IronPDF 之後):

// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Rendering;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();

        // Configure header and footer
        renderer.RenderingOptions.TextHeader = new TextHeaderFooter()
        {
            CenterText = "Page Header",
            FontSize = 12
        };

        renderer.RenderingOptions.TextFooter = new TextHeaderFooter()
        {
            CenterText = "Page {page} of {total-pages}",
            FontSize = 10
        };

        var pdf = renderer.RenderHtmlAsPdf("<h1>Document with Headers and Footers</h1>");
        pdf.SaveAs("header-footer.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Rendering;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();

        // Configure header and footer
        renderer.RenderingOptions.TextHeader = new TextHeaderFooter()
        {
            CenterText = "Page Header",
            FontSize = 12
        };

        renderer.RenderingOptions.TextFooter = new TextHeaderFooter()
        {
            CenterText = "Page {page} of {total-pages}",
            FontSize = 10
        };

        var pdf = renderer.RenderHtmlAsPdf("<h1>Document with Headers and Footers</h1>");
        pdf.SaveAs("header-footer.pdf");
    }
}
$vbLabelText   $csharpLabel

HiQPdf 方法需要設定Document.Header.Height ,建立HtmlToPdfVariableElement對象,並對頁首/頁尾部分呼叫Add() 。 頁碼佔位符使用{CrtPage}{PageCount}語法。 IronPDF 提供了一個更簡潔的TextHeaderFooter配置,帶有CenterText屬性和不同的佔位符語法: {page}{total-pages} 。 如需更多選項(包括基於 HTML 的頁首和頁尾),請參閱頁首和頁尾文件


關鍵遷移說明

佔位符語法更改

對於帶有頁碼的文件來說,最重要的變化是佔位符語法:

// HiQPdf placeholders
"Page {CrtPage} of {PageCount}"

// IronPDF placeholders
"Page {page} of {total-pages}"
// HiQPdf placeholders
"Page {CrtPage} of {PageCount}"

// IronPDF placeholders
"Page {page} of {total-pages}"
$vbLabelText   $csharpLabel

完整的佔位符映射:

  • {CrtPage}{page}
  • {PageCount}{total-pages}

合併方法差異

HiQPdf 直接修改第一份文件:

// HiQPdf: Modifies document1
document1.AddDocument(document2);
document1.WriteToFile("merged.pdf");
// HiQPdf: Modifies document1
document1.AddDocument(document2);
document1.WriteToFile("merged.pdf");
$vbLabelText   $csharpLabel

IronPDF 傳回一個新的合併文件:

// IronPDF: Returns new document
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("merged.pdf");
// IronPDF: Returns new document
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("merged.pdf");
$vbLabelText   $csharpLabel

無3頁限制

HiQPdf 的免費版本輸出最多只能產生 3 頁有浮水印的圖片。 IronPDF 可在試用期內產生完整文檔,不受任何人為限制。

重用 ChromePdfRenderer

與 HiQPdf 中每次轉換都可能需要建立新的HtmlToPdf實例不同,IronPDF 的ChromePdfRenderer應該可以重複使用:

// IronPDF: Create once, reuse
var renderer = new ChromePdfRenderer();
var pdf1 = renderer.RenderHtmlAsPdf(html1);
var pdf2 = renderer.RenderHtmlAsPdf(html2);
// IronPDF: Create once, reuse
var renderer = new ChromePdfRenderer();
var pdf1 = renderer.RenderHtmlAsPdf(html1);
var pdf2 = renderer.RenderHtmlAsPdf(html2);
$vbLabelText   $csharpLabel

故障排除

問題 1:未找到 HtmlToPdf 函數

問題: IronPDF 中不存在HtmlToPdf類別。

解決方案:替換為ChromePdfRenderer

// HiQPdf
HtmlToPdf htmlToPdfConverter = new HtmlToPdf();

// IronPDF
var renderer = new ChromePdfRenderer();
// HiQPdf
HtmlToPdf htmlToPdfConverter = new HtmlToPdf();

// IronPDF
var renderer = new ChromePdfRenderer();
$vbLabelText   $csharpLabel

問題 2:未找到 ConvertHtmlToMemory 函數

問題: ConvertHtmlToMemory()方法不存在。

解決方案:使用RenderHtmlAsPdf()

// HiQPdf
byte[] pdfBytes = converter.ConvertHtmlToMemory(html, "");

// IronPDF
var pdf = renderer.RenderHtmlAsPdf(html);
byte[] pdfBytes = pdf.BinaryData;
// HiQPdf
byte[] pdfBytes = converter.ConvertHtmlToMemory(html, "");

// IronPDF
var pdf = renderer.RenderHtmlAsPdf(html);
byte[] pdfBytes = pdf.BinaryData;
$vbLabelText   $csharpLabel

問題 3:頁碼佔位符無法正常運作

問題: {CrtPage}{PageCount}直接出現在輸出結果。

解決方案:更新 IronPDF 佔位符語法:

// HiQPdf syntax (won't work)
"Page {CrtPage} of {PageCount}"

// IronPDF syntax
"Page {page} of {total-pages}"
// HiQPdf syntax (won't work)
"Page {CrtPage} of {PageCount}"

// IronPDF syntax
"Page {page} of {total-pages}"
$vbLabelText   $csharpLabel

問題 4:未找到 HtmlToPdfVariableElement

問題: HtmlToPdfVariableElement類別不存在。

解決方案:使用TextHeaderFooterHtmlHeaderFooter

// HiQPdf
HtmlToPdfVariableElement headerHtml = new HtmlToPdfVariableElement("<div>Header</div>", "");
converter.Document.Header.Add(headerHtml);

// IronPDF
renderer.RenderingOptions.TextHeader = new TextHeaderFooter()
{
    CenterText = "Header",
    FontSize = 12
};
// HiQPdf
HtmlToPdfVariableElement headerHtml = new HtmlToPdfVariableElement("<div>Header</div>", "");
converter.Document.Header.Add(headerHtml);

// IronPDF
renderer.RenderingOptions.TextHeader = new TextHeaderFooter()
{
    CenterText = "Header",
    FontSize = 12
};
$vbLabelText   $csharpLabel

遷移清單

遷移前

  • 清點程式碼庫中所有 HiQPdf API 呼叫
  • 記錄目前頁面尺寸、邊距和設置
  • 確定頁首/頁尾配置和占位符
  • 取得 IronPDF 許可證密鑰
  • 在開發環境中測試 IronPDF

程式碼遷移

  • 刪除所有 HiQPdf NuGet 套件(所有變體) 安裝 IronPdf NuGet 套件: dotnet add package IronPdf
  • 更新命名空間匯入
  • HtmlToPdf替換為ChromePdfRenderer
  • ConvertHtmlToMemory()轉換為RenderHtmlAsPdf()
  • ConvertUrlToMemory()轉換為RenderUrlAsPdf()
  • 更新頁首/頁尾佔位符( {CrtPage}{page}{PageCount}{total-pages}
  • HtmlToPdfVariableElement替換為TextHeaderFooter
  • 更新合併操作( AddDocumentPdfDocument.Merge
  • 新增啟動時許可證金鑰初始化功能

測試

  • 測試 HTML 到 PDF 的轉換
  • 測試 URL 到 PDF 的轉換
  • 驗證頁首/頁尾渲染效果
  • 核對頁碼佔位符
  • 測試 PDF 合併
  • 測試大量使用 JavaScript 的頁面(現在 Chromium 已支援)

移民後

  • 從配置中移除 HiQPdf 序號
  • 更新文檔
  • 監控渲染差異

Curtis Chau
技術撰稿人

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

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