Fluid to biblioteka .NET (dostępna na NuGet jako Fluid.Core, autorem jest Sebastien Ros, licencjonowana na zasadach MIT), która implementuje język szablonów Liquid, oferując programistom elastyczny sposób renderowania dynamicznych szablonów i oddzielenie treści od logiki prezentacji. Fluid skutecznie generuje dynamiczne wyjścia tekstowe, ale nie obsługuje bezpośrednio generowania PDF — deweloperzy muszą zintegrować dodatkową bibliotekę PDF, aby przekształcić wyjście HTML do dokumentów PDF. Takie podejście oparte na dwóch bibliotekach wprowadza złożoność, którą wiele zespołów programistycznych stara się wyeliminować.
Niniejszy przewodnik zawiera kompletną ścieżkę migracji z Fluid (szablony) z zewnętrznymi bibliotekami PDF do IronPDF, wraz z instrukcjami krok po kroku, porównaniami kodu i praktycznymi przykładami dla profesjonalnych programistów .NET rozważających tę zmianę.
Fluid to solidny silnik szablonów oparty na Liquid, ale użycie go do generowania plików PDF wiąże się ze znacznym stopniem złożoności:
Zależność od dwóch bibliotek: Fluid generuje wyłącznie kod HTML — do tworzenia plików PDF potrzebna jest osobna biblioteka do obsługi formatu PDF (wkhtmltopdf, PuppeteerSharp itp.), co podwaja liczbę zależności i obciążenie związane z utrzymaniem.
Złożoność integracji: Koordynacja dwóch bibliotek oznacza zarządzanie dwoma zestawami konfiguracji, obsługą błędów i aktualizacjami. Kiedy coś się psuje, debugowanie staje się trudniejsze.
Krzywa uczenia się składni Liquid: Programiści muszą nauczyć się składni szablonów Liquid ({{ }}, {% %}), mimo że C# ma już wbudowane potężne możliwości obsługi ciągów znaków.
Ograniczona kontrola nad plikami PDF: Jakość wyjściowego pliku PDF zależy od biblioteki PDF, którą wybierzesz do połączenia z Fluid, a nie od dedykowanego silnika renderującego.
Wyzwania związane z debugowaniem: Błędy mogą wystąpić zarówno na etapie tworzenia szablonów, jak i generowania plików PDF, co sprawia, że rozwiązywanie problemów jest trudniejsze niż w przypadku pojedynczego, zintegrowanego rozwiązania.
Problemy z bezpieczeństwem wątków: TemplateContext nie jest bezpieczne w wątkach i wymaga ostrożnego zarządzania w aplikacjach równoczesnych.
##IronPDF vs Fluid (szablony): Porównanie funkcji
Zrozumienie różnic architektonicznych pomaga decydentom technicznym w ocenie inwestycji w migrację:
| Aspekt | Fluid + Biblioteka PDF | IronPDF |
|---|---|---|
| Zależności | 2+ pakiety (Fluid + biblioteka PDF) | Pojedynczy pakiet |
| Szablony | Składnia Liquid ({{ }}) | Interpolacja ciągów znaków w języku C# lub Razor |
| Generowanie plików PDF | Wymagana biblioteka zewnętrzna | Wbudowany silnik Chromium |
| Obsługa CSS | Zależy od biblioteki PDF | Pełna obsługa CSS3 z Flexbox/Grid |
| JavaScript | Zależy od biblioteki PDF | Pełna obsługa JavaScript |
| Bezpieczeństwo wątków | TemplateContext nie jest bezpieczny dla wątków | ChromePdfRenderer jest bezpieczny dla wątków |
| Krzywa uczenia się | Liquid + biblioteka API PDF | HTML/CSS (standardy internetowe) |
| Obsługa błędów | Dwa źródła błędów | Pojedyncze źródło błędu |
Migrację można rozpocząć natychmiast, wykonując te podstawowe kroki.
Usuń Fluid i wszelkie zewnętrzne biblioteki 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 usedZainstaluj IronPDF:
# Install IronPDF(all-in-one solution)
dotnet add package IronPdfZamień przestrzenie nazw Fluid na IronPDF:
// Before (Fluid + external PDF library)
using Fluid;
using Fluid.Values;
using SomeExternalPdfLibrary;
// After (IronPDF)
using IronPdf;
using IronPdf.Rendering; // For RenderingOptionsImports Fluid
Imports Fluid.Values
Imports SomeExternalPdfLibrary
Imports IronPdf
Imports IronPdf.Rendering ' For RenderingOptionsDodaj inicjalizację licencji podczas uruchamiania aplikacji:
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"Najbardziej podstawowa operacja ujawnia kluczową różnicę między tymi podejściami.
Płynne podejście:
// 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
Imports Fluid
Imports System.IO
Imports System.Threading.Tasks
Module Program
Async Function Main() As Task
Dim parser As New FluidParser()
Dim template = parser.Parse("<html><body><h1>Hello {{name}}!</h1></body></html>")
Dim context As New TemplateContext()
context.SetValue("name", "World")
Dim html = Await template.RenderAsync(context)
' Fluid only generates HTML - you'd need another library to convert to PDF
File.WriteAllText("output.html", html)
End Function
End ModulePodejście 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");
}
}Imports IronPdf
Imports System
Class Program
Shared Sub Main()
Dim renderer = New ChromePdfRenderer()
Dim html = "<html><body><h1>Hello World!</h1></body></html>"
Dim pdf = renderer.RenderHtmlAsPdf(html)
pdf.SaveAs("output.pdf")
End Sub
End ClassFluid wymaga utworzenia FluidParser, parsowania ciągu szablonu, utworzenia TemplateContext, wywołania SetValue() dla każdej zmiennej, renderowania asynchronicznego w celu uzyskania HTML-a, a następnie zapisania do pliku — co nadal nie jest PDF-em. Komentarz w kodzie wyraźnie stwierdza: "Fluid generuje wyłącznie HTML — do konwersji do formatu PDF potrzebna jest inna biblioteka".
IronPDF eliminuje tę złożoność: stwórz renderer, wywołaj RenderHtmlAsPdf() i zapisz bezpośrednio do PDF. Bez pośrednich plików HTML, bez dodatkowych bibliotek.
W przypadku zaawansowanych scenariuszy konwersji HTML do PDF zapoznaj się z przewodnikiem po konwersji HTML do PDF.
Szablony dokumentów z wieloma zmiennymi wyraźnie pokazują różnice w wzorcach szablonów.
Płynne podejście:
// 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
Imports Fluid
Imports System
Imports System.IO
Imports System.Threading.Tasks
Module Program
Async Function Main() As Task
Dim parser = New FluidParser()
Dim template = parser.Parse("
<html><body>
<h1>Invoice #{{invoiceNumber}}</h1>
<p>Date: {{date}}</p>
<p>Customer: {{customer}}</p>
<p>Total: ${{total}}</p>
</body></html>")
Dim context = New TemplateContext()
context.SetValue("invoiceNumber", "12345")
context.SetValue("date", DateTime.Now.ToShortDateString())
context.SetValue("customer", "John Doe")
context.SetValue("total", 599.99)
Dim html = Await template.RenderAsync(context)
' Fluid outputs HTML - requires additional PDF library
File.WriteAllText("invoice.html", html)
End Function
End ModulePodejście 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
Imports IronPdf
Imports System
Module Program
Sub Main()
Dim renderer As New ChromePdfRenderer()
Dim invoiceNumber As String = "12345"
Dim [date] As String = DateTime.Now.ToShortDateString()
Dim customer As String = "John Doe"
Dim total As Double = 599.99
Dim html As String = $"
<html><body>
<h1>Invoice #{invoiceNumber}</h1>
<p>Date: {[date]}</p>
<p>Customer: {customer}</p>
<p>Total: ${total}</p>
</body></html>"
Dim pdf = renderer.RenderHtmlAsPdf(html)
pdf.SaveAs("invoice.pdf")
End Sub
End ModuleFluid używa składni {{variable}} Liquid z context.SetValue() dla każdej zmiennej. Komentarz wyraźnie stwierdza "Fluid generuje HTML - wymagana dodatkowa biblioteka PDF."IronPDF używa standardowej interpolacji ciągów w C# ($"{variable}") — składni, którą programiści już znają — i generuje bezpośrednio do PDF.
Zapoznaj się z samouczkami IronPDF, aby poznać więcej wzorców generowania dokumentów.
Szablony z kolekcjami i pętlami pokazują różnice w przebiegu programu.
Płynne podejście:
// 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
Imports Fluid
Imports System.Collections.Generic
Imports System.IO
Imports System.Threading.Tasks
Module Program
Async Function Main() As Task
Dim parser = New FluidParser()
Dim template = parser.Parse("
<html><body>
<h1>{{title}}</h1>
<ul>
{% for item in items %}
<li>{{item}}</li>
{% endfor %}
</ul>
</body></html>")
Dim context = New TemplateContext()
context.SetValue("title", "My List")
context.SetValue("items", New String() { "Item 1", "Item 2", "Item 3" })
Dim html = Await template.RenderAsync(context)
' Fluid generates HTML only - separate PDF conversion needed
File.WriteAllText("template-output.html", html)
End Function
End ModulePodejście 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
Imports IronPdf
Imports System
Imports System.Collections.Generic
Module Program
Sub Main()
Dim renderer = New ChromePdfRenderer()
Dim title = "My List"
Dim items = {"Item 1", "Item 2", "Item 3"}
Dim html = $"
<html><body>
<h1>{title}</h1>
<ul>"
For Each item In items
html += $"<li>{item}</li>"
Next
html += "</ul></body></html>"
Dim pdf = renderer.RenderHtmlAsPdf(html)
pdf.SaveAs("template-output.pdf")
End Sub
End ModuleFluid używa składni {% for item in items %}...{% endfor %} Liquid — języka szablonów, którego programiści muszą się nauczyć. Komentarz wskazuje "Fluid generuje tylko HTML - potrzebna oddzielna konwersja do PDF."IronPDF używa standardowych pętli C# foreach — bez potrzeby nauki nowej składni — i generuje bezpośrednio do PDF.
To mapowanie przyspiesza migrację, pokazując bezpośrednie odpowiedniki API:
| Klasa Fluid | Odpowiednik IronPDF |
|---|---|
FluidParser | Nie dotyczy |
FluidTemplate | Nie dotyczy |
TemplateContext | Obiekty/ciągi znaków w języku C# |
TemplateOptions | RenderingOptions |
FluidValue | Natywne typy C# |
| Zewnętrzna klasa PDF | ChromePdfRenderer |
| Metoda płynna | Odpowiednik IronPDF |
|---|---|
new FluidParser() | new ChromePdfRenderer() |
parser.Parse(source) | Nie dotyczy |
template.RenderAsync(context) | renderer.RenderHtmlAsPdf(html) |
context.SetValue("key", value) | var key = value; |
| Liquid Syntax | Odpowiednik w języku C# |
|---|---|
{{variable}} | $"{variable}" |
{% for item in items %} | foreach (var item in items) |
{% if condition %} | if (condition) |
{{x |upcase}} | x.ToUpper() |
{{x |date: '%Y-%m-%d'}} | x.ToString("yyyy-MM-dd") |
{{x | number_with_precision: 2}} | x.ToString("F2") |
Fluid: Używa składni {{variable}} i {% control %}.
Rozwiązanie: Zastąp interpolacją ciągów znaków w języku C# i kontrolą przepływu:
// Liquid: {{name | upcase}}
// C#: $"{name.ToUpper()}"
// Liquid: {% for item in items %}{{item}}{% endfor %}
// C#: foreach (var item in items) { html += $"{item}"; }Fluid: Używa context.SetValue("key", value) do przesyłania danych.
Rozwiązanie: Użyj standardowych zmiennych języka C#:
// Before (Fluid)
var context = new TemplateContext();
context.SetValue("customer", customerName);
// After (IronPDF)
var customer = customerName;
var html = $"<p>Customer: {customer}</p>";' Before (Fluid)
Dim context As New TemplateContext()
context.SetValue("customer", customerName)
' After (IronPDF)
Dim customer = customerName
Dim html = $"<p>Customer: {customer}</p>"Fluid: TemplateContext nie jest bezpieczne w wątkach i wymaga ostrożnego zarządzania w aplikacjach równoczesnych.
Rozwiązanie: ChromePdfRenderer jest bezpieczne w wątkach i może być współdzielone między wątkami:
// 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 Shared ReadOnly _renderer As New ChromePdfRenderer()
Public Function GeneratePdf(html As String) As Byte()
Dim pdf = _renderer.RenderHtmlAsPdf(html)
Return pdf.BinaryData
End FunctionPłynność: Błędy mogą wystąpić na etapie tworzenia szablonów LUB generowania plików PDF.
**Rozwiązanie:**IronPDF ma jedno źródło błędu:
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
Dim pdf = renderer.RenderHtmlAsPdf(html)
pdf.SaveAs("output.pdf")
Catch ex As Exception
' Single point of failure—easier debugging
Console.WriteLine($"PDF generation failed: {ex.Message}")
End TryPrzeprowadź audyt kodu źródłowego, aby zidentyfikować wszystkie przypadki użycia 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 "{{"Należy udokumentować wszystkie szablony: lokalizacje plików, użyte zmienne, pętle i warunki oraz konfigurację zewnętrznej biblioteki PDF.
Fluid do IronPdf{{variable}} do $"{variable}"{% for item in collection %} do C# foreach{% if condition %} do C# if deklaracji| upcase → .ToUpper())FluidParser na ChromePdfRendererTemplateContext.SetValue() na bezpośrednie zmienne C#Po migracji należy zweryfikować następujące aspekty:
.liquid (jeśli są już niepotrzebne)Przejście z Fluid (szablonowanie) z zewnętrznymi bibliotekami PDF na IronPDF zapewnia kilka kluczowych korzyści:
Rozwiązanie w jednym pakiecie: Wyeliminuj zależność od dwóch bibliotek.IronPDF obsługuje zarówno tworzenie szablonów (za pomocą HTML/CSS), jak i generowanie plików PDF w jednym pakiecie.
Nie trzeba uczyć się nowej składni: zamiast uczyć się składni szablonów Liquid, używaj standardowej interpolacji ciągów znaków i sterowania przepływem w języku C#.
Renderowanie wątkowo-bezpieczne: ChromePdfRenderer jest bezpieczne w wątkach, w przeciwieństwie do TemplateContext, co upraszcza jednoczesne generowanie PDF.
Silnik renderowania Chromium: renderowanie oparte na Chromium obsługuje nowoczesny CSS (w tym Flexbox i Grid) oraz wykonywanie JavaScript.
Jedno źródło błędów: Debugowanie staje się prostsze, ponieważ wystarczy zająć się tylko jedną biblioteką, zamiast koordynować działania na etapie tworzenia szablonów i generowania plików PDF.
**Szerokie pokrycie .NET:**IronPDF obsługuje .NET Framework 4.6.2+, .NET Core 2.0+, .NET Standard 2.0 oraz .NET 5 do .NET 10.
Curtis Chau posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.
IronPDF jest częścią IRONSUITE
10 produktów API .NET dla twoich dokumentów biurowych
Kiedy potrzebujesz, aby twój PDF wyglądał jak HTML, szybko.
