跳過到頁腳內容
遷移指南

從 Fluid (Templating) 轉移到 IronPDF

Migrating from Fluid (Templating) to IronPDF:完整的 C# 開發人員指南。

Fluid 是實作 Liquid 模板語言的 .NET 函式庫,提供開發人員多樣化的方式來呈現動態模板,並將內容與呈現邏輯分離。 雖然 Fluid 擅長於產生動態文字輸出,但並不直接支援 PDF 產生 - 開發人員必須整合額外的 PDF 函式庫,才能將 HTML 輸出轉換為 PDF 文件。 這種雙庫的方式帶來了許多開發團隊想要消除的複雜性。

本指南提供了從使用外部 PDF 函式庫的 Fluid (templating) 到IronPDF的完整轉換路徑,並提供分步說明、程式碼比較以及實用範例,以供評估此轉換的 .NET 專業開發人員使用。

為什麼要從 Fluid(模板化)轉移到 IronPDF?

Fluid 是出色的基於 Liquid 的範本引擎,但將其用於 PDF 生成會帶來顯著的複雜性:

雙庫依賴:Fluid 只會產生 HTML - 您需要另一個 PDF 函式庫(wkhtmltopdf、PuppeteerSharp 等)來建立 PDF,這會加倍您的依賴性和維護負擔。

整合複雜性:協調兩個程式庫意味著要管理兩套組態、錯誤處理和更新。 當發生故障時,除錯就會變得更具挑戰性。

Liquid 語法學習曲線:開發人員必須學習 Liquid 模板語法({{ }}, {% %}),而 C# 已經內建了強大的字串處理功能。

Limited PDF Control:您的 PDF 輸出品質取決於您選擇搭配 Fluid 的 PDF 函式庫,而非專用的渲染引擎。

Debugging Challenges:錯誤可能發生在模板或 PDF 生成階段,使得故障排除比單一整合解決方案更困難。

線程安全疑慮TemplateContext 不是線程安全的,需要在並發應用程式中小心管理。

IronPDFvs Fluid(模板化):功能比較

了解架構上的差異有助於技術決策者評估遷移投資:

範疇Fluid + PDF 庫IronPDF
依賴性2+ 套件 (Fluid + PDF 資料庫)單一套件
範例設計液態語法 ({{ }})C# 字串插值或 Razor
PDF生成需要外部函式庫內建 Chromium 引擎
CSS 支援依賴 PDF 函式庫完整的 CSS3 與 Flexbox/Grid
JavaScript依賴 PDF 函式庫完整的 JavaScript 支援
線程安全TemplateContext 非線程安全ChromePdfRenderer 是線程安全的
學習曲線Liquid + PDF 圖書館 APIHTML/CSS (網頁標準)
錯誤處理兩個錯誤來源單一錯誤來源

快速入門:Fluid 到IronPDF的遷移。

只要完成這些基本步驟,就可以立即開始遷移。

步驟 1:取代 NuGet 套件

移除 Fluid 和任何外部 PDF 函式庫:

# Remove Fluid and external PDF library
dotnet remove package Fluid.Core
dotnet remove package WkHtmlToPdf-DotNet  # or whatever PDF library you used
dotnet remove package PuppeteerSharp       # if used
# Remove Fluid and external PDF library
dotnet remove package Fluid.Core
dotnet remove package WkHtmlToPdf-DotNet  # or whatever PDF library you used
dotnet remove package PuppeteerSharp       # if used
SHELL

安裝 IronPDF:

# InstallIronPDF(all-in-one solution)
dotnet add package IronPdf
# InstallIronPDF(all-in-one solution)
dotnet add package IronPdf
SHELL

步驟 2:更新命名空間

用 IronPdf 取代 Fluid 命名空間:

// Before (Fluid + external PDF library)
using Fluid;
using Fluid.Values;
using SomeExternalPdfLibrary;

// After (IronPDF)
using IronPdf;
using IronPdf.Rendering;  // For RenderingOptions
// Before (Fluid + external PDF library)
using Fluid;
using Fluid.Values;
using SomeExternalPdfLibrary;

// After (IronPDF)
using IronPdf;
using IronPdf.Rendering;  // For RenderingOptions
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

步驟 3:初始化授權

在應用程式啟動時加入授權初始化:

IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"
$vbLabelText   $csharpLabel

程式碼遷移範例

Basic HTML to PDF

最基本的操作揭示了這些方法之間的關鍵差異。

流暢的方法:

// NuGet: Install-Package Fluid.Core
using Fluid;
using System.IO;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var parser = new FluidParser();
        var template = parser.Parse("<html><body><h1>Hello {{name}}!</h1></body></html>");
        var context = new TemplateContext();
        context.SetValue("name", "World");
        var html = await template.RenderAsync(context);

        // Fluid only generates HTML - you'd need another library to convert to PDF
        File.WriteAllText("output.html", html);
    }
}
// NuGet: Install-Package Fluid.Core
using Fluid;
using System.IO;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var parser = new FluidParser();
        var template = parser.Parse("<html><body><h1>Hello {{name}}!</h1></body></html>");
        var context = new TemplateContext();
        context.SetValue("name", "World");
        var html = await template.RenderAsync(context);

        // Fluid only generates HTML - you'd need another library to convert to PDF
        File.WriteAllText("output.html", html);
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

IronPDF 方法:

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

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var html = "<html><body><h1>Hello World!</h1></body></html>";
        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("output.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var html = "<html><body><h1>Hello World!</h1></body></html>";
        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("output.pdf");
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Fluid 需要建立<編碼>FluidParser</編碼、解析範本字串、建立範本上下文、為每個變數呼叫 SetValue() 、異步渲染以取得 HTML,然後寫入檔案 - 這仍不是 PDF。 程式碼中的注解明確指出:"Fluid 只會產生 HTML - 您需要另一個函式庫來轉換成 PDF"。

IronPDF 消除了這種複雜性:建立一個渲染器,呼叫 RenderHtmlAsPdf() 並直接儲存為 PDF。 沒有中間的 HTML 檔案,沒有額外的程式庫。

如需進階的 HTML 至IronPDF情境,請參閱 HTML 至 PDF 轉換指南

具有動態資料的發票範本

具有多重變數的文件範本可清楚顯示範本模式的差異。

流暢的方法:

// NuGet: Install-Package Fluid.Core
using Fluid;
using System;
using System.IO;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var parser = new FluidParser();
        var template = parser.Parse(@"
            <html><body>
                <h1>Invoice #{{invoiceNumber}}</h1>
                <p>Date: {{date}}</p>
                <p>Customer: {{customer}}</p>
                <p>Total: ${{total}}</p>
            </body></html>");

        var context = new TemplateContext();
        context.SetValue("invoiceNumber", "12345");
        context.SetValue("date", DateTime.Now.ToShortDateString());
        context.SetValue("customer", "John Doe");
        context.SetValue("total", 599.99);

        var html = await template.RenderAsync(context);
        // Fluid outputs HTML - requires additional PDF library
        File.WriteAllText("invoice.html", html);
    }
}
// NuGet: Install-Package Fluid.Core
using Fluid;
using System;
using System.IO;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var parser = new FluidParser();
        var template = parser.Parse(@"
            <html><body>
                <h1>Invoice #{{invoiceNumber}}</h1>
                <p>Date: {{date}}</p>
                <p>Customer: {{customer}}</p>
                <p>Total: ${{total}}</p>
            </body></html>");

        var context = new TemplateContext();
        context.SetValue("invoiceNumber", "12345");
        context.SetValue("date", DateTime.Now.ToShortDateString());
        context.SetValue("customer", "John Doe");
        context.SetValue("total", 599.99);

        var html = await template.RenderAsync(context);
        // Fluid outputs HTML - requires additional PDF library
        File.WriteAllText("invoice.html", html);
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

IronPDF 方法:

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

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var invoiceNumber = "12345";
        var date = DateTime.Now.ToShortDateString();
        var customer = "John Doe";
        var total = 599.99;

        var html = $@"
            <html><body>
                <h1>Invoice #{invoiceNumber}</h1>
                <p>Date: {date}</p>
                <p>Customer: {customer}</p>
                <p>Total: ${total}</p>
            </body></html>";

        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("invoice.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var invoiceNumber = "12345";
        var date = DateTime.Now.ToShortDateString();
        var customer = "John Doe";
        var total = 599.99;

        var html = $@"
            <html><body>
                <h1>Invoice #{invoiceNumber}</h1>
                <p>Date: {date}</p>
                <p>Customer: {customer}</p>
                <p>Total: ${total}</p>
            </body></html>";

        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("invoice.pdf");
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Fluid 使用 Liquid 的 {{variable}} 語法,每個變數使用 context.SetValue() 。 註解明確指出 "Fluid 輸出 HTML - 需要額外的 PDF 函式庫"。IronPDF 使用標準 C# 字串插值 ($"{variable}") - 開發人員已經知道的語法 - 並直接輸出為 PDF。

探索 IronPDF 教學,瞭解更多文件生成模式。

使用循環的動態資料

使用集合和迴圈的範本展示控制流程的差異。

流暢的方法:

// NuGet: Install-Package Fluid.Core
using Fluid;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var parser = new FluidParser();
        var template = parser.Parse(@"
            <html><body>
                <h1>{{title}}</h1>
                <ul>
                {% for item in items %}
                    <li>{{item}}</li>
                {% endfor %}
                </ul>
            </body></html>");

        var context = new TemplateContext();
        context.SetValue("title", "My List");
        context.SetValue("items", new[] { "Item 1", "Item 2", "Item 3" });

        var html = await template.RenderAsync(context);
        // Fluid generates HTML only - separate PDF conversion needed
        File.WriteAllText("template-output.html", html);
    }
}
// NuGet: Install-Package Fluid.Core
using Fluid;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var parser = new FluidParser();
        var template = parser.Parse(@"
            <html><body>
                <h1>{{title}}</h1>
                <ul>
                {% for item in items %}
                    <li>{{item}}</li>
                {% endfor %}
                </ul>
            </body></html>");

        var context = new TemplateContext();
        context.SetValue("title", "My List");
        context.SetValue("items", new[] { "Item 1", "Item 2", "Item 3" });

        var html = await template.RenderAsync(context);
        // Fluid generates HTML only - separate PDF conversion needed
        File.WriteAllText("template-output.html", html);
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

IronPDF 方法:

// NuGet: Install-Package IronPdf
using IronPdf;
using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var title = "My List";
        var items = new[] { "Item 1", "Item 2", "Item 3" };

        var html = $@"
            <html><body>
                <h1>{title}</h1>
                <ul>";

        foreach (var item in items)
        {
            html += $"<li>{item}</li>";
        }

        html += "</ul></body></html>";

        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("template-output.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var title = "My List";
        var items = new[] { "Item 1", "Item 2", "Item 3" };

        var html = $@"
            <html><body>
                <h1>{title}</h1>
                <ul>";

        foreach (var item in items)
        {
            html += $"<li>{item}</li>";
        }

        html += "</ul></body></html>";

        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("template-output.pdf");
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Fluid 使用 Liquid 的 {% for item in items %}...{% endfor %} 語法 - 開發人員必須學習的模板語言。 註解指出 "Fluid 只會產生 HTML - 需要另外轉換 PDF"。IronPdf 使用標準 C# foreach 循環 - 無需學習新的語法 - 並直接輸出為 PDF。

Fluid API 至IronPDF對應參考。

此對應可透過顯示直接的 API 對應關係來加速遷移:

核心類映射

流體類IronPdf 同等級產品筆記
<編碼>FluidParser</編碼不適用不需要-使用 C# 字串
<編碼>FluidTemplate</編碼不適用不需要
範本上下文C# 物件/字串直接傳遞資料
範本選項渲染選項PDF 輸出配置
<編碼>FluidValue</編碼原生 C# 類型無需轉換
外部 PDF 類<代碼>ChromePdfRenderer</代碼主要渲染類別

方法映射

流體方法IronPdf 同等級產品筆記
新的 FluidParser()新的 ChromePdfRenderer()取代建立呈現器
<編碼>parser.Parse(source)</編碼不適用不需要-HTML 是字串
template.RenderAsync(context)renderer.RenderHtmlAsPdf(html)直接 PDF 渲染
context.SetValue("key", value)var key = value;使用 C# 變數

Liquid 語法到 C# 的映射

液態語法C# 對應詞筆記
{{ 變數 }}$"{variable}"字串插值
{% for item in items %}foreach (var item in items)C# 環路
{% if condition %}if(條件)C# 條件
{{ x \|上例 }}<編碼>x.ToUpper()</編碼C# 方法
{{ x \|date: '%Y-%m-%d' }}x.ToString("yyyy-MM-dd")C# 格式化
{{ x \|number_with_precision: 2 }}x.ToString("F2")C# 數字格式化

常見的遷移問題與解決方案

問題 1:液態語法轉換

Fluid: 使用 {{ 變數 }}{% 控制 %} 語法。

解決方案:以 C# 字串插值和控制流程取代:

// Liquid: {{ name | upcase }}
// C#: $"{name.ToUpper()}"

// Liquid: {% for item in items %}{{item}}{% endfor %}
// C#: foreach (var item in items) { html += $"{item}"; }
// Liquid: {{ name | upcase }}
// C#: $"{name.ToUpper()}"

// Liquid: {% for item in items %}{{item}}{% endfor %}
// C#: foreach (var item in items) { html += $"{item}"; }
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

問題 2:TemplateContext 變數

Fluid: 使用context.SetValue("key", value)傳遞資料。

解決方案:使用標準 C# 變數:

// Before (Fluid)
var context = new TemplateContext();
context.SetValue("customer", customerName);

// After (IronPDF)
var customer = customerName;
var html = $"<p>Customer: {customer}</p>";
// Before (Fluid)
var context = new TemplateContext();
context.SetValue("customer", customerName);

// After (IronPDF)
var customer = customerName;
var html = $"<p>Customer: {customer}</p>";
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

第 3 期:線程安全

Fluid:範本上下文不是線程安全的,需要在並發應用程式中小心管理。

解決方案:<代碼>ChromePdfRenderer</代碼是線程安全的,可以跨線程共用:

// Thread-safe usage
private static readonly ChromePdfRenderer _renderer = new ChromePdfRenderer();

public byte[] GeneratePdf(string html)
{
    var pdf = _renderer.RenderHtmlAsPdf(html);
    return pdf.BinaryData;
}
// Thread-safe usage
private static readonly ChromePdfRenderer _renderer = new ChromePdfRenderer();

public byte[] GeneratePdf(string html)
{
    var pdf = _renderer.RenderHtmlAsPdf(html);
    return pdf.BinaryData;
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

第 4 期:兩階錯誤處理

流暢:錯誤可能發生在模板階段或 PDF 生成階段。

解決方案:IronPDF只有一個錯誤來源:

try
{
    var pdf = renderer.RenderHtmlAsPdf(html);
    pdf.SaveAs("output.pdf");
}
catch (Exception ex)
{
    // Single point of failure—easier debugging
    Console.WriteLine($"PDF generation failed: {ex.Message}");
}
try
{
    var pdf = renderer.RenderHtmlAsPdf(html);
    pdf.SaveAs("output.pdf");
}
catch (Exception ex)
{
    // Single point of failure—easier debugging
    Console.WriteLine($"PDF generation failed: {ex.Message}");
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

流體遷移清單

遷移前的任務

審核您的程式碼庫,找出所有 Fluid 的用法:

# Find all Fluid references
grep -r "FluidParser\|FluidTemplate\|TemplateContext\|using Fluid" --include="*.cs" --include="*.csproj" .

# Find Liquid template files
find . -name "*.liquid" -o -name "*.html" | xargs grep -l "{{"
# Find all Fluid references
grep -r "FluidParser\|FluidTemplate\|TemplateContext\|using Fluid" --include="*.cs" --include="*.csproj" .

# Find Liquid template files
find . -name "*.liquid" -o -name "*.html" | xargs grep -l "{{"
SHELL

記錄所有範本:檔案位置、使用的變數、循環和條件,以及外部 PDF 函式庫組態。

程式碼更新任務

1.移除 Fluid.Core NuGet 套件 2.移除外部 PDF 函式庫套件 3.安裝 IronPdf NuGet 套件 4.更新命名空間匯入,從 FluidIronPdf 5.將 {{ 變數 }} 轉換為 $"{variable}" 6.將 {% for item in collection %} 轉換為 C# foreach 7.將{% if condition %}轉換為 C# if 語句 8.將 Liquid 過濾器轉換為 C# 方法 (例如: .|upcase.ToUpper()) 9.將<編碼>FluidParser</編碼替換為 ChromePdfRenderer 10.以直接 C# 變數取代 TemplateContext.SetValue() 11.移除外部 PDF 函式庫呼叫 12.在啟動時增加 IronPdf 授權初始化功能

後遷移測試

轉移後,驗證這些方面:

  • 驗證 PDF 輸出符合預期
  • 測試所有範本變化是否能正確呈現
  • 檢查圖片和樣式顯示是否正確
  • 驗證分頁符是否正確
  • 使用各種資料大小進行測試
  • 效能測試 vs Fluid + 外部函式庫
  • 測試並發情況下的線程安全性

清理任務

  • 刪除 .liquid 模板檔案 (如果不再需要)
  • 移除與 Fluid 相關的輔助程式碼
  • 更新文件
  • 清理未使用的相依性

遷移到IronPDF的主要優點。

從使用外部 PDF 函式庫的 Fluid (templating) 轉換到IronPDF提供了幾個關鍵的優勢:

單一套件解決方案:消除雙庫依賴。IronPDF可在一個套件中處理模板(透過 HTML/CSS)和 PDF 的產生。

無需學習新的語法:使用標準的 C# 字串插值和控制流程,而無需學習 Liquid 模板語法。

線程安全渲染ChromePdfRenderer 是線程安全的,與範本上下文不同,它簡化了 PDF 的並發生成。

Chromium 渲染引擎:符合業界標準的渲染可確保完整的 CSS3 支援,包括 Flexbox 和 Grid,以及完整的 JavaScript 執行。

單一錯誤來源:調試變得更簡單,只需一個函式庫即可排除故障,而無需在模板和 PDF 生成階段之間進行協調。

主動開發:隨著 .NET 10 和 C# 14 的採用增加至 2026 年,IronPDF 的定期更新可確保與目前和未來的 .NET 版本相容。

結論

Fluid (templating) 為追求內容分離彈性的開發人員提供了絕佳的解決方案,並可使用 Liquid 語法建立動態文字。 然而,該函式庫明確表示不會產生 PDF - 它只會輸出 HTML。 這需要與其他 PDF 函式庫整合,形成雙函式庫的依賴關係,增加複雜性、除錯難度和維護負擔。

IronPDF 提供了多合一的解決方案,免除了多重依賴的需求。 轉換路徑很直接:取代 NuGet 套件,將 Liquid 語法轉換為 C# 字串插值,並利用IronPDF內建的 Chromium 渲染引擎直接輸出 PDF。

立即使用 免費試用 IronPDF 開始您的遷移工作,並簡化您的 PDF 生成工作流程。

如需全面的實施指導,請探索 IronPDF 文件教學

Curtis Chau
技術作家

Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。

除了開發之外,Curtis 對物聯網 (IoT) 有著濃厚的興趣,探索將硬體和軟體結合的創新方式。在閒暇時間,他喜愛遊戲並構建 Discord 機器人,結合科技與創意的樂趣。