GuideIntroduction
Getting started
Install Fluid, render your first template, and set it up the way it is meant to be used in an application.
Fluid is an open-source .NET template engine based on the Liquid template language. It is fast, allocates little, and is safe for templates written by users: they can only read the data you give them.
Install the packageLink to this heading
Fluid is published on NuGet as Fluid.Core:
dotnet add package Fluid.Core
The samples of this documentation assume using Fluid;.
Previews of the next version are published to a feedz.io feed
after every push to main:
dotnet nuget add source https://f.feedz.io/sebastienros/fluid/nuget/index.json --name fluid-preview
dotnet add package Fluid.Core --prerelease
Render a templateLink to this heading
A FluidParser turns the source of a template into an IFluidTemplate, and a TemplateContext holds the values a
rendering can read:
var parser = new FluidParser();
var model = new { Firstname = "Bill", Lastname = "Gates" };
var source = "Hello {{ Firstname }} {{ Lastname }}";
if (parser.TryParse(source, out var template, out var error))
{
var context = new TemplateContext(model);
Console.WriteLine(template.Render(context)); // Hello Bill Gates
}
else
{
Console.WriteLine($"Error: {error}");
}
TryParse returns parsing errors as a string. Parse throws a ParseException that has the line and column of the
error, see Parsing errors.
Reuse instancesLink to this heading
Parsing and configuration are meant to happen once, and rendering many times:
- A
FluidParseris thread-safe and expensive to create: create it once and share it, for instance in astaticfield. - An
IFluidTemplateis thread-safe: cache parsed templates and render them concurrently. - A
TemplateOptionsis immutable and thread-safe: build it once with aTemplateOptionsBuilder, and callToBuilder()to derive a variation. - A
TemplateContextis not thread-safe: create a new one for every rendering.
private static readonly FluidParser Parser = new FluidParser();
private static readonly TemplateOptions Options = new TemplateOptionsBuilder()
.WithCultureInfo(new CultureInfo("en-US"))
.WithStrictVariables()
.Build();
public static ValueTask<string> RenderAsync(IFluidTemplate template, object model)
{
return template.RenderAsync(new TemplateContext(model, Options), HtmlEncoder.Default);
}
Go furtherLink to this heading
| To | Read |
|---|---|
Learn how Fluid reads Liquid, and enable macro, parentheses or escape sequences |
Liquid syntax |
| Expose .NET objects, convert values, register members | Models and values |
| Add your own filters, tags, blocks and operators | Extending the grammar |
| Render templates written by users | Security |
| Load partials, handle undefined values, encode the output | Parsing and rendering |
| Use culture-aware filters, dates and money | Filters and Cultures, dates and time zones |
| Render Liquid views in ASP.NET Core | View engines |
| Avoid reflection, or compile templates at build time | Model accessor generator and Compiled template generator |