如何在 C# 中將 HiQPDF 移轉到 IronPDF

各功能預計工作量

範式轉移

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

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

步驟 1：更新許可證配置

之前（HiQPdf）：

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

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

（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";

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

// Before (HiQPdf)
using HiQPdf;

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

// Before (HiQPdf)
using HiQPdf;

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

主類別映射

轉換方法映射

PDF文檔方法映射

頁首/頁尾佔位符映射

範例 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);
    }
}

（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");
    }
}

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");
    }
}

（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");
    }
}

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);
    }
}

（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");
    }
}

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

完整的佔位符映射：

• {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");

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");

無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);

問題 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();

問題 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;

問題 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}"

問題 4：未找到 HtmlToPdfVariableElement

問題： HtmlToPdfVariableElement類別不存在。

解決方案：使用TextHeaderFooter或HtmlHeaderFooter ：

// 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
};

遷移前

• 清點程式碼庫中所有 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
• 更新合併操作（ AddDocument → PdfDocument.Merge ）
• 新增啟動時許可證金鑰初始化功能

測試

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

移民後

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