Fluid.Core
2.11.1
dotnet add package Fluid.Core --version 2.11.1
NuGet\Install-Package Fluid.Core -Version 2.11.1
<PackageReference Include="Fluid.Core" Version="2.11.1" />
paket add Fluid.Core --version 2.11.1
#r "nuget: Fluid.Core, 2.11.1"
// Install Fluid.Core as a Cake Addin #addin nuget:?package=Fluid.Core&version=2.11.1 // Install Fluid.Core as a Cake Tool #tool nuget:?package=Fluid.Core&version=2.11.1
<p align="center"><img width=25% src="https://github.com/sebastienros/fluid/raw/main/Assets/logo-vertical.png"></p>
Basic Overview
Fluid is an open-source .NET template engine based on the Liquid template language. It's a secure template language that is also very accessible for non-programmer audiences.
The following content is based on the 2.0.0-beta version, which is the recommended version even though some of its API might vary significantly. To see the corresponding content for v1.0 use this version
<br>
Tutorials
Deane Barker wrote a very comprehensive tutorial on how to write Liquid templates with Fluid. For a high-level overview, read The Four Levels of Fluid Development describing different stages of usages of Fluid.
<br>
Features
- Very fast Liquid parser and renderer (no-regexp), with few allocations. See benchmarks.
- Secure templates by allow-listing all the available properties in the template. User templates can't break your application.
- Supports async filters. Templates can execute database queries more efficiently under load.
- Customize filters and tag with your own. Even with complex grammar constructs. See Customizing tags and blocks
- Parses templates in a concrete syntax tree that lets you cache, analyze and alter the templates before they are rendered.
- Register any .NET types and properties, or define custom handlers to intercept when a named variable is accessed.
<br>
Contents
- Features
- Using Fluid in your project
- Allow-listing object members
- Execution limits
- Converting CLR types
- Encoding
- Localization
- Time zones
- Customizing tags and blocks
- ASP.NET MVC View Engine
- Whitespace control
- Custom filters
- Functions
- Visiting and altering a template
- Performance
- Used by
<br>
Source
<ul id="products">
{% for product in products %}
<li>
<h2>{{product.name}}</h2>
Only {{product.price | price }}
{{product.description | prettyprint | paragraph }}
</li>
{% endfor %}
</ul>
Result
<ul id="products">
<li>
<h2>Apple</h2>
$329
Flat-out fun.
</li>
<li>
<h2>Orange</h2>
$25
Colorful.
</li>
<li>
<h2>Banana</h2>
$99
Peel it.
</li>
</ul>
Notice
- The
<li>
tags are at the same index as in the template, even though the{% for }
tag had some leading spaces - The
<ul>
and<li>
tags are on contiguous lines even though the{% for }
is taking a full line.
<br>
Using Fluid in your project
You can directly reference the Nuget package.
Hello World
Source
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));
}
else
{
Console.WriteLine($"Error: {error}");
}
Result
Hello Bill Gates
Thread-safety
A FluidParser
instance is thread-safe, and should be shared by the whole application. A common pattern is declare the parser in a local static variable:
private static readonly FluidParser _parser = new FluidParser();
A IFluidTemplate
instance is thread-safe and can be cached and reused by multiple threads concurrently.
A TemplateContext
instance is not thread-safe and an instance should be created every time an IFluidTemplate
instance is used.
<br>
Adding custom filters
Filters can be async or not. They are defined as a delegate
that accepts an input, a set of arguments and the current context of the rendering process.
Here is the downcase
filter as defined in Fluid.
Source
public static ValueTask<FluidValue> Downcase(FluidValue input, FilterArguments arguments, TemplateContext context)
{
return new StringValue(input.ToStringValue().ToLower());
}
Registration
Filters are registered in an instance of TemplateOptions
. This options object can be reused every time a template is rendered.
var options = new TemplateOptions();
options.Filters.AddFilter('downcase', Downcase);
var context = new TemplateContext(options);
<br>
Allow-listing object members
Liquid is a secure template language which will only allow a predefined set of members to be accessed, and where model members can't be changed.
Property are added to the TemplateOptions.MemberAccessStrategy
property. This options object can be reused every time a template is rendered.
Alternatively, the MemberAccessStrategy
can be assigned an instance of UnsafeMemberAccessStrategy
which will allow any property to be accessed.
Allow-listing a specific type
This will allow any public field or property to be read from a template.
var options = new TemplateOptions();
options.MemberAccessStrategy.Register<Person>();
Note: When passing a model with
new TemplateContext(model)
the type of themodel
object is automatically registered. This behavior can be disable by callingnew TemplateContext(model, false)
Allow-listing specific members
This will only allow the specific fields or properties to be read from a template.
var options = new TemplateOptions();
options.MemberAccessStrategy.Register<Person>("Firstname", "Lastname");
Intercepting a type access
This will provide a method to intercept when a member is accessed and either return a custom value or prevent it.
NB: If the model implements IDictionary
or any similar generic dictionary types the dictionary access has priority over the custom accessors.
This example demonstrates how to intercept calls to a Person
and always return the same property.
var model = new Person { Name = "Bill" };
var options = new TemplateOptions();
options.MemberAccessStrategy.Register<Person, object>((obj, name) => obj.Name);
Customizing object accessors
To provide advanced customization for specific types, it is recommended to use value converters and a custom FluidValue
implementation by inheriting from ObjectValueBase
.
The following example show how to provide a custom transformation for any Person
object:
private class PersonValue : ObjectValueBase
{
public PersonValue(Person value) : base(value)
{
}
public override ValueTask<FluidValue> GetIndexAsync(FluidValue index, TemplateContext context)
{
return Create(((Person)Value).Firstname + "!!!" + index.ToStringValue(), context.Options);
}
}
This custom type can be used with a converter such that any time a Person
is used, it is wrapped as a PersonValue
.
var options = new TemplateOptions();
options.ValueConverters.Add(o => o is Person p ? new PersonValue(p) : null);
It can also be used to replace custom member access by customizing GetValueAsync
, or do custom conversions to standard Fluid types.
Inheritance
All the members of the class hierarchy are registered. Besides, all inherited classes will be correctly evaluated when a base class is registered and a member of the base class is accessed.
<br>
Object members casing
By default, the properties of a registered object are case sensitive and registered as they are in their source code. For instance,
the property FirstName
would be access using the {{ p.FirstName }}
tag.
However it can be necessary to register these properties with different cases, like Camel case (firstName
), or Snake case (first_name
).
The following example configures the templates to use Camel casing.
var options = new TemplateOptions();
options.MemberAccessStrategy.MemberNameStrategy = MemberNameStrategies.CamelCase;
Execution limits
Limiting templates recursion
When invoking {% include 'sub-template' %}
statements it is possible that some templates create an infinite recursion that could block the server.
To prevent this the TemplateOptions
class defines a default MaxRecursion = 100
that prevents templates from being have a depth greater than 100
.
Limiting templates execution
Template can inadvertently create infinite loop that could block the server by running indefinitely.
To prevent this the TemplateOptions
class defines a default MaxSteps
. By default this value is not set.
<br>
Converting CLR types
Whenever an object is manipulated in a template it is converted to a specific FluidValue
instance that provides a dynamic type system somehow similar to the one in JavaScript.
In Liquid they can be Number, String, Boolean, Array, Dictionary, or Object. Fluid will automatically convert the CLR types to the corresponding Liquid ones, and also provides specialized ones.
To be able to customize this conversion you can add value converters.
Adding a value converter
When the conversion logic is not directly inferred from the type of an object, a value converter can be used.
Value converters can return:
null
to indicate that the value couldn't be converted- a
FluidValue
instance to stop any further conversion and use this value - another object instance to continue the conversion using custom and internal type mappings
The following example shows how to convert any instance implementing an interface to a custom string value:
var options = new TemplateOptions();
options.ValueConverters.Add((value) => value is IUser user ? user.Name : null);
Note: Type mapping are defined globally for the application.
<br>
Encoding
By default Fluid doesn't encode the output. Encoders can be specified when calling Render()
or RenderAsync()
on the template.
HTML encoding
To render a template with HTML encoding use the System.Text.Encodings.Web.HtmlEncoder.Default
instance.
This encoder is used by default for the MVC View engine.
Disabling encoding contextually
When an encoder is defined you can use a special raw
filter or {% raw %} ... {% endraw %}
tag to prevent a value from being encoded, for instance if you know that the content is HTML and is safe.
Source
{% assign html = '<em>This is some html</em>' %}
Encoded: {{ html }}
Not encoded: {{ html | raw }
Result
<em%gt;This is some html</em%gt;
<em>This is some html</em>
Captured blocks are not double-encoded
When using capture
blocks, the inner content is flagged as
pre-encoded and won't be double-encoded if used in a {{ }}
tag.
Source
{% capture breaktag %}<br />{% endcapture %}
{{ breaktag }}
Result
<br />
<br>
Localization
By default templates are rendered using an invariant culture so that the results are consistent across systems. This is important for instance when rendering dates, times and numbers.
However it is possible to define a specific culture to use when rendering a template using the TemplateContext.CultureInfo
property.
Source
var options = new TemplateOptions();
options.CultureInfo = new CultureInfo("en-US");
var context = new TemplateContext(options);
var result = template.Render(context);
{{ 1234.56 }}
{{ "now" | date: "%v" }}
Result
1234.56
Tuesday, August 1, 2017
<br>
Time zones
System time zone
TemplateOptions
and TemplateContext
provides a property to define a default time zone to use when parsing date and times. The default value is the current system's time zone. Setting a custom one can also prevent different environments (data centers) from
generating different results.
- When dates and times are parsed and don't specify a time zone, the configured one is assumed.
- When a time zone is provided in the source string, the resulting date time uses it.
Note: The
date
filter conforms to the Ruby date and time formats https://ruby-doc.org/core-3.0.0/Time.html#method-i-strftime. To use the .NET standard date formats, use theformat_date
filter.
Source
var context = new TemplateContext { TimeZone = TimeZoneInfo.FindSystemTimeZoneById("Pacific Standard Time") } ;
var result = template.Render(context);
{{ '1970-01-01 00:00:00' | date: '%c' }}
Result
Wed Dec 31 19:00:00 -08:00 1969
Converting time zones
Dates and times can be converted to specific time zones using the time_zone: <iana>
filter.
Example
var context = new TemplateContext();
context.SetValue("published", DateTime.UtcNow);
{{ published | time_zone: 'America/New_York' | date: '%+' }}
Result
Tue Aug 1 17:04:36 -05:00 2017
<br>
Customizing tags and blocks
Fluid's grammar can be modified to accept any new tags and blocks with any custom parameters. The parser is based on Parlot which makes it completely extensible.
Unlike blocks, tags don't have a closing element (e.g., cycle
, increment
).
A closing element will match the name of the opening tag with and end
suffix, like endfor
.
Blocks are useful when manipulating a section of a a template as a set of statements.
Fluid provides helper method to register common tags and blocks. All tags and block always start with an identifier that is the tag name.
Each custom tag needs to provide a delegate that is evaluated when the tag is matched. Each delegate will be able to use these properties:
writer
, aTextWriter
instance that is used to render some text.encode
, aTextEncoder
instance, likeHtmlEncoder
, orNullEncoder
. It's defined by the caller of the template.context
, aTemplateContext
instance.
Registering a custom tag
- Empty: Tag with no parameter, like
{% renderbody %}
- Identifier: Tag taking an identifier as parameter, like
{% increment my_variable %}
- Expression: Tag taking an expression as parameter, like
{% layout 'home' | append: '.liquid' %}
Here are some examples:
Source
parser.RegisterIdentifierTag("hello", (identifier, writer, encoder, context) =>
{
writer.Write("Hello ");
writer.Write(identifier);
});
{% hello you %}
Result
Hello you
Registering a custom block
Blocks are created the same way as tags, and the lambda expression can then access the list of statements inside the block.
Source
parser.RegisterExpressionBlock("repeat", async (value, statements, writer, encoder, context) =>
{
var fluidValue = await value.EvaluateAsync(context);
for (var i = 0; i < fluidValue.ToNumberValue(); i++)
{
await statements.RenderStatementsAsync(writer, encoder, context);
}
return Completion.Normal;
});
{% repeat 1 | plus: 2 %}Hi! {% endrepeat %}
Result
Hi! Hi! Hi!
Custom parsers
If identifier, empty and expression parsers are not sufficient, the methods RegisterParserBlock
and RegisterParserTag
accept
any custom parser construct. These can be the standard ones defined in the FluidParser
class, like Primary
, or any other composition of them.
For instance, RegisterParseTag(Primary.AndSkip(Comma).And(Primary), ...)
will expect two Primary
elements separated by a comma. The delegate will then
be invoked with a ValueTuple<Expression, Expression>
representing the two Primary
expressions.
Registering a custom operator
Operator are used to compare values, like >
or contains
. Custom operators can be defined if special comparisons need to be provided.
Source
The following example creates a custom xor
operator that will evaluate to true
if only one of the left and right expressions is true when converted to booleans.
XorBinaryExpression.cs
using Fluid.Ast;
using Fluid.Values;
using System.Threading.Tasks;
namespace Fluid.Tests.Extensibility
{
public class XorBinaryExpression : BinaryExpression
{
public XorBinaryExpression(Expression left, Expression right) : base(left, right)
{
}
public override async ValueTask<FluidValue> EvaluateAsync(TemplateContext context)
{
var leftValue = await Left.EvaluateAsync(context);
var rightValue = await Right.EvaluateAsync(context);
return BooleanValue.Create(leftValue.ToBooleanValue() ^ rightValue.ToBooleanValue());
}
}
}
Parser configuration
parser.RegisteredOperators["xor"] = (a, b) => new XorBinaryExpression(a, b);
Usage
{% if true xor false %}Hello{% endif %}
Result
Hello
Accessing the concrete syntax tree
The syntax tree is accessible by casting the template to its concrete FluidTemplate
type and using the Statements
property.
Source
var template = (FluidTemplate)iTemplate;
var statements = template.Statements;
<br>
ASP.NET MVC View Engine
The package Fluid.MvcViewEngine
provides a convenient way to use Liquid as a replacement or in combination of Razor in ASP.NET MVC.
Configuration
Registering the view engine
- Reference the
Fluid.MvcViewEngine
NuGet package - Add a
using
statement onFluid.MvcViewEngine
- Call
AddFluid()
in yourStartup.cs
.
Sample
using Fluid.MvcViewEngine;
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().AddFluid();
}
}
Registering view models
Because the Liquid language only accepts known members to be accessed, the View Model classes need to be registered in Fluid. Usually from a static constructor such that the code is run only once for the application.
View Model registration
View models are automatically registered and available as the root object in liquid templates.
Custom model registrations can be added when calling AddFluid()
.
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().AddFluid(o => o.TemplateOptions.Register<Person>());
}
}
More way to register types and members can be found in the Allow-listing object members section.
Registering custom tags
When using the MVC View engine, custom tags can still be added to the parser. Refer to this section on how to create custom tags.
It is recommended to create a custom class inheriting from FluidViewParser
, and to customize the tags in the constructor of this new class.
This class can then be registered as the default parser for the MVC view engine.
using Fluid.Ast;
using Fluid.MvcViewEngine;
namespace Fluid.MvcSample
{
public class CustomFluidViewParser : FluidViewParser
{
public CustomFluidViewParser()
{
RegisterEmptyTag("mytag", static async (s, w, e, c) =>
{
await w.WriteAsync("Hello from MyTag");
return Completion.Normal;
});
}
}
}
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.Configure<MvcViewOptions>(options =>
{
options.Parser = new CustomFluidViewParser();
});
services.AddMvc().AddFluid();
}
}
Layouts
Index.liquid
{% layout '_layout.liquid' %}
This is the home page
The {% layout [template] %}
tag accepts one argument which can be any expression that return the relative location of a liquid template that will be used as the master template.
The layout tag is optional in a view. It can also be defined multiple times or conditionally.
From a layout template the {% renderbody %}
tag is used to depict the location of the view's content inside the layout itself.
Layout.liquid
<html>
<body>
<div class="menu"></div>
<div class="content">
{% renderbody %}
</div>
<div class="footer"></div>
</body>
</html>
Sections
Sections are defined in a layout as for views to render content in specific locations. For instance a view can render some content in a menu or a footer section.
Rendering content in a section
{% layout '_layout.liquid' %}
This is is the home page
{% section menu %}
<a href="h#">This link goes in the menu</a>
{% endsection %}
{% section footer %}
This text will go in the footer
{% endsection %}
Rendering the content of a section
<html>
<body>
<div class="menu">
{% rendersection menu %}
</div>
<div class="content">
{% renderbody %}
</div>
<div class="footer">
{% rendersection footer %}
</div>
</body>
</html>
ViewStart files
Defining the layout template in each view might me cumbersome and make it difficult to change it globally. To prevent that it can be defined in a _ViewStart.liquid
file.
When a view is rendered all _ViewStart.liquid
files from its current and parent directories are executed before. This means multiple files can be defined to defined settings for a group of views.
_ViewStart.liquid
{% layout '_layout.liquid' %}
{% assign background = 'ffffff' }
You can also define other variables or render some content.
Custom views locations
It is possible to add custom file locations containing views by adding them to FluidMvcViewOptions.ViewsLocationFormats
.
The default ones are:
Views/{1}/{0}.liquid
Views/Shared/{0}.liquid
Where {0}
is the view name, and {1}
is the controller name.
For partials, the list is defined in FluidMvcViewOptions.PartialsLocationFormats
:
Views/{0}.liquid
Views/Partials/{0}.liquid
Views/Partials/{1}/{0}.liquid
Views/Shared/Partials/{0}.liquid
Layouts will be searched in the same locations as Views.
Execution
The content of a view is parsed once and kept in memory until the file or one of its dependencies changes. Once parsed, the tag are executed every time the view is called. To compare this with Razor, where views are first compiled then instantiated every time they are rendered. This means that on startup or when the view is changed, views with Fluid will run faster than those in Razor, unless you are using precompiled Razor views. In all cases Razor views will be faster on subsequent calls as they are compiled directly to C#.
This difference makes Fluid very adapted for rapid development cycles where the views can be deployed and updated frequently. And because the Liquid language is secure, developers give access to them with more confidence.
<br>
View Engine
The Fluid ASP.NET MVC View Engine is based on an MVC agnostic view engine provided in the Fluid.ViewEngine
package. The same options and features are available, but without
requiring ASP.NET MVC. This is useful to provide the same experience to build template using layouts and sections.
Usage
Use the class FluidViewRenderer : IFluidViewRender
and FluidViewEngineOptions
.
Whitespace control
Liquid follows strict rules with regards to whitespace support. By default all spaces and new lines are preserved from the template. The Liquid syntax and some Fluid options allow to customize this behavior.
Hyphens
For example:
{% assign name = "Bill" %}
{{ name }}
There is a new line after the assign
tag which will be preserved.
Outputs:
Bill
Tags and values can use hyphens to strip whitespace.
Example:
{% assign name = "Bill" -%}
{{ name }}
Outputs:
Bill
The -%}
strips the whitespace from the right side of the assign
tag.
Template Options
Fluid provides the TemplateOptions.Trimming
property that can be set with predefined preferences for when whitespace should be stripped automatically, even if hyphens are not
present in tags and output values.
Greedy Mode
When greedy model is disabled in TemplateOptions.Greedy
, only the spaces before the first new line are stripped.
Greedy mode is enabled by default since this is the standard behavior of the Liquid language.
<br>
Custom filters
Some non-standard filters are provided by default
format_date
Formats date and times using standard .NET date and time formats. It uses the current culture of the system.
Input
"now" | format_date: "G"
Output
6/15/2009 1:45:30 PM
Documentation: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings
format_number
Formats numbers using standard .NET number formats.
Input
123 | format_number: "N"
Output
123.00
Documentation: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings
format_string
Formats custom string using standard .NET format strings.
Input
"hello {0} {1:C}" | format_string: "world" 123
Output
hello world $123.00
Documentation: https://docs.microsoft.com/en-us/dotnet/api/system.string.format
<br>
Functions
Fluid provides optional support for functions, which is not part of the standard Liquid templating language. As such it is not enabled by default.
Enabling functions
When instantiating a FluidParser
set the FluidParserOptions.AllowFunction
property to true
.
var parser = new FluidParser(new FluidParserOptions { AllowFunctions = true });
When functions are used while the feature is not enabled, a parse error will be returned.
Declaring local functions with the macro
tag
macro
allows you to define reusable chunks of content invoke with local function.
{% macro field(name, value='', type='text') %}
<div class="field">
<input type="{{ type }}" name="{{ name }}"
value="{{ value }}" />
</div>
{% endmacro %}
Now field
is available as a local property of the template and can be invoked as a function.
{{ field('user') }}
{{ field('pass', type='password') }}
Macros need to be defined before they are used as they are discovered as the template is executed.
Importing functions from external templates
Macros defined in an external template must be imported before they can be invoked.
{% from 'forms' import field %}
{{ field('user') }}
{{ field('pass', type='password') }}
Extensibility
Functions are FluidValue
instances implementing the InvokeAsync
method. It allows any template to be provided custom function values as part of the model, the TemplateContext
or globally with options.
A FunctionValue
type is also available to provide out of the box functions. It takes a delegate that returns a ValueTask<FluidValue>
as the result.
var lowercase = new FunctionValue((args, context) =>
{
var firstArg = args.At(0).ToStringValue();
var lower = firstArg.ToLowerCase();
return new ValueTask<FluidValue>(new StringValue(lower));
});
var context = new TemplateContext();
context.SetValue("tolower", lowercase);
var parser = new FluidParser(new FluidParserOptions { AllowFunctions = true });
parser.TryParse("{{ tolower('HELLO') }}", out var template, out var error);
template.Render(context);
<br>
Visiting and altering a template
Fluid provides a Visitor pattern allowing you to analyze what a template is made of, but also altering it. This can be used for instance to check if a specific identifier is used, replace some filters by another one, or remove any expression that might not be authorized.
Visiting a template
The Fluid.Ast.AstVisitor
class can be used to create a custom visitor.
Here is an example of a visitor class which records if an identifier is accessed anywhere in a template:
public class IdentifierIsAccessedVisitor : AstVisitor
{
private readonly string _identifier;
public IdentifierIsAccessedVisitor(string identifier)
{
_identifier = identifier;
}
public bool IsAccessed { get; private set; }
public override IFluidTemplate VisitTemplate(IFluidTemplate template)
{
// Initialize the result each time a template is visited with the same visitor instance
IsAccessed = false;
return base.VisitTemplate(template);
}
protected override Expression VisitMemberExpression(MemberExpression memberExpression)
{
var firstSegment = memberExpression.Segments.FirstOrDefault() as IdentifierSegment;
if (firstSegment != null)
{
IsAccessed |= firstSegment.Identifier == _identifier;
}
return base.VisitMemberExpression(memberExpression);
}
}
And its usage:
var template = new FluidParser().Parse("{{ a.b | plus: 1}}");
var visitor = new IdentifierIsAccessedVisitor("a");
visitor.VisitTemplate(template);
Console.WriteLine(visitor.IsAccessed); // writes True
Rewriting a template
The Fluid.Ast.AstRewriter
class can be used to create a custom rewriter.
Here is an example of a visitor class which replaces any plus
filter with a minus
one:
public class ReplacePlusFiltersVisitor : AstRewriter
{
protected override Expression VisitFilterExpression(FilterExpression filterExpression)
{
if (filterExpression.Name == "plus")
{
return new FilterExpression(filterExpression.Input, "minus", filterExpression.Parameters);
}
return filterExpression;
}
}
And its usage:
var template = new FluidParser().Parse("{{ 1 | plus: 2 }}");
var visitor = new ReplacePlusFiltersVisitor();
var changed = visitor.VisitTemplate(template);
var result = changed.Render();
Console.WriteLine(result); // writes -1
Performance
Caching
Some performance boost can be gained in your application if you decide to cache the parsed templates before they are rendered. Even though parsing is memory-safe as it won't induce any compilation (meaning all the memory can be collected if you decide to parse a lot of templates), you can skip the parsing step by storing and reusing the FluidTemplate
instance.
These object are thread-safe as long as each call to Render()
uses a dedicated TemplateContext
instance.
Benchmarks
A benchmark application is provided in the source code to compare Fluid, Scriban, DotLiquid, Liquid.NET and Handlebars.NET. Run it locally to analyze the time it takes to execute specific templates.
Results
Fluid is faster and allocates less memory than all other well-known .NET Liquid parsers. For parsing, Fluid is 19% faster than the second, Scriban, allocating nearly 3 times less memory. For rendering, Fluid is 26% faster than the second, Handlebars, 5 times faster than Scriban, but allocates half the memory. Compared to DotLiquid, Fluid renders 11 times faster, and allocates 35 times less memory.
BenchmarkDotNet v0.13.12, Windows 11 (10.0.22631.3593/23H2/2023Update/SunValley3)
12th Gen Intel Core i7-1260P, 1 CPU, 16 logical and 12 physical cores
.NET SDK 9.0.100-preview.4.24209.11
[Host] : .NET 8.0.5 (8.0.524.21615), X64 RyuJIT AVX2
DefaultJob : .NET 8.0.5 (8.0.524.21615), X64 RyuJIT AVX2
| Method | Mean | Error | StdDev | Ratio | RatioSD | Gen0 | Gen1 | Gen2 | Allocated | Alloc Ratio |
|------------------- |--------------:|------------:|------------:|-------:|--------:|----------:|---------:|--------:|------------:|------------:|
| Fluid_Parse | 2.849 us | 0.0191 us | 0.0159 us | 1.00 | 0.00 | 0.3052 | - | - | 2.81 KB | 1.00 |
| Scriban_Parse | 3.297 us | 0.0407 us | 0.0381 us | 1.16 | 0.01 | 0.7744 | 0.0267 | - | 7.14 KB | 2.54 |
| DotLiquid_Parse | 6.558 us | 0.1118 us | 0.1046 us | 2.30 | 0.03 | 1.7624 | 0.0229 | - | 16.21 KB | 5.76 |
| LiquidNet_Parse | 25.064 us | 0.1409 us | 0.1100 us | 8.80 | 0.07 | 6.7444 | 0.6104 | - | 62.04 KB | 22.06 |
| Handlebars_Parse | 2,401.901 us | 41.1672 us | 38.5079 us | 843.36 | 15.09 | 15.6250 | 7.8125 | - | 156.52 KB | 55.65 |
| | | | | | | | | | | |
| Fluid_ParseBig | 16.257 us | 0.1450 us | 0.1357 us | 1.00 | 0.00 | 1.2512 | 0.0305 | - | 11.64 KB | 1.00 |
| Scriban_ParseBig | 18.521 us | 0.1000 us | 0.0886 us | 1.14 | 0.01 | 3.4790 | 0.4883 | - | 32.07 KB | 2.75 |
| DotLiquid_ParseBig | 27.612 us | 0.4320 us | 0.4041 us | 1.70 | 0.03 | 10.2539 | 0.4883 | - | 94.36 KB | 8.11 |
| LiquidNet_ParseBig | 12,206.204 us | 188.5327 us | 176.3536 us | 750.86 | 12.96 | 3093.7500 | 15.6250 | - | 28543.38 KB | 2,452.05 |
| | | | | | | | | | | |
| Fluid_Render | 134.311 us | 1.5910 us | 1.4104 us | 1.00 | 0.00 | 10.2539 | 0.4883 | - | 95.86 KB | 1.00 |
| Scriban_Render | 615.143 us | 5.4851 us | 4.5803 us | 4.58 | 0.06 | 68.3594 | 68.3594 | 68.3594 | 498.64 KB | 5.20 |
| DotLiquid_Render | 1,403.693 us | 27.4426 us | 40.2251 us | 10.63 | 0.27 | 351.5625 | 140.6250 | 23.4375 | 3368.09 KB | 35.13 |
| LiquidNet_Render | 825.819 us | 8.6639 us | 7.6803 us | 6.15 | 0.08 | 339.8438 | 160.1563 | - | 3130.8 KB | 32.66 |
| Handlebars_Render | 238.959 us | 4.7119 us | 11.5585 us | 1.68 | 0.06 | 20.9961 | 3.4180 | - | 194.92 KB | 2.03 |
Tested on May 28, 2024 with
- Scriban 5.10.0
- DotLiquid 2.2.692
- Liquid.NET 0.10.0
- Handlebars.Net 2.1.6
Legend
- Parse: Parses a simple HTML template containing filters and properties
- ParseBig: Parses a Blog Post template.
- Render: Renders a simple HTML template containing filters and properties, with 500 products.
Used by
Fluid is known to be used in the following projects:
- Orchard Core CMS Open Source .NET modular framework and CMS
- MaltReport OpenDocument/OfficeOpenXML powered reporting engine for .NET and Mono
- Elsa Workflows .NET Workflows Library
- FluentEmail All in one email sender for .NET
- NJsonSchema Library to read, generate and validate JSON Schema draft v4+ schemas
- NSwag Swagger/OpenAPI 2.0 and 3.0 toolchain for .NET
- Optimizely An enterprise .NET CMS
- Rock Relationship Management System
- TemplateTo Powerful Template Based Document Generation
- Weavo Liquid Loom A Liquid Template generator/editor + corresponding Azure Logic Apps Connector / Microsoft Power Automate Connector
- Semantic Kernel Integrate cutting-edge LLM technology quickly and easily into your apps
- Mailgen A .NET package that generates clean, responsive HTML e-mails for sending transactional mail.
Please create a pull-request to be listed here.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Microsoft.CSharp (>= 4.7.0)
- Microsoft.Extensions.FileProviders.Abstractions (>= 8.0.0)
- Parlot (>= 1.0.2)
- System.Text.Json (>= 8.0.4)
- TimeZoneConverter (>= 6.1.0)
-
net6.0
- Microsoft.Extensions.FileProviders.Abstractions (>= 8.0.0)
- Parlot (>= 1.0.2)
- TimeZoneConverter (>= 6.1.0)
-
net8.0
- Microsoft.Extensions.FileProviders.Abstractions (>= 8.0.0)
- Parlot (>= 1.0.2)
- TimeZoneConverter (>= 6.1.0)
NuGet packages (183)
Showing the top 5 NuGet packages that depend on Fluid.Core:
Package | Downloads |
---|---|
NJsonSchema.CodeGeneration
JSON Schema reader, generator and validator for .NET |
|
Elsa.Scripting.Liquid
Elsa is a set of workflow libraries and tools that enable lean and mean workflowing capabilities in any .NET Core application. This package provides a Liquid expression evaluator based on Fluid. |
|
OrchardCore.DisplayManagement
Orchard Core Framework is an application framework for building modular, multi-tenant applications on ASP.NET Core. Library for DisplayManagement. Provides BaseDisplayManager, Shape, Layout and Theming support. |
|
OrchardCore.Liquid.Abstractions
Orchard Core Framework is an application framework for building modular, multi-tenant applications on ASP.NET Core. Abstractions for liquid syntax. |
|
OrchardCore.ContentManagement.Display
Orchard Core CMS is a Web Content Management System (CMS) built on top of the Orchard Core Framework. DisplayManagement Library for ContentManagement. Provides implementation of DisplayManager for ContentItem and useful utilities classes for shapes, placement and Razor - related to ContentManagement. |
GitHub repositories (20)
Showing the top 5 popular GitHub repositories that depend on Fluid.Core:
Repository | Stars |
---|---|
microsoft/semantic-kernel
Integrate cutting-edge LLM technology quickly and easily into your apps
|
|
OrchardCMS/OrchardCore
Orchard Core is an open-source modular and multi-tenant application framework built with ASP.NET Core, and a content management system (CMS) built on top of that framework.
|
|
elsa-workflows/elsa-core
A .NET workflows library
|
|
BililiveRecorder/BililiveRecorder
录播姬 | mikufans 生放送录制
|
|
scriban/scriban
A fast, powerful, safe and lightweight scripting language and engine for .NET
|
Version | Downloads | Last updated |
---|---|---|
2.11.1 | 385,407 | 7/23/2024 |
2.11.0 | 77,919 | 7/11/2024 |
2.10.0 | 275,420 | 5/17/2024 |
2.9.0 | 648,159 | 4/23/2024 |
2.8.0 | 164,000 | 4/4/2024 |
2.7.0 | 133,621 | 3/18/2024 |
2.6.0 | 25,186 | 3/11/2024 |
2.5.0 | 2,013,646 | 9/28/2023 |
2.4.0 | 983,487 | 3/1/2023 |
2.3.1 | 415,483 | 12/17/2022 |
2.3.0 | 37,654 | 11/30/2022 |
2.2.16 | 445,019 | 9/21/2022 |
2.2.15 | 4,231,840 | 4/12/2022 |
2.2.14 | 2,904,590 | 1/13/2022 |
2.2.13 | 6,418 | 1/8/2022 |
2.2.12 | 1,552 | 1/7/2022 |
2.2.11 | 1,413 | 1/7/2022 |
2.2.10 | 1,795 | 1/7/2022 |
2.2.9 | 2,187 | 1/5/2022 |
2.2.8 | 1,113,895 | 12/9/2021 |
2.2.7 | 97,846 | 12/2/2021 |
2.2.6 | 2,646 | 12/1/2021 |
2.2.5 | 5,115 | 11/27/2021 |
2.2.4 | 12,174 | 11/25/2021 |
2.2.3 | 4,743 | 11/22/2021 |
2.2.2 | 2,483 | 11/20/2021 |
2.2.1 | 2,265 | 11/20/2021 |
2.2.0 | 20,521 | 11/2/2021 |
2.1.4 | 176,030 | 10/26/2021 |
2.1.3 | 16,748 | 10/19/2021 |
2.1.2 | 6,696 | 10/16/2021 |
2.1.1 | 1,815 | 10/15/2021 |
2.1.0 | 76,764 | 10/12/2021 |
2.0.13 | 422,672 | 5/29/2021 |
2.0.12 | 8,404 | 5/25/2021 |
2.0.11 | 95,771 | 5/20/2021 |
2.0.10 | 28,425 | 5/8/2021 |
2.0.9 | 12,202 | 5/4/2021 |
2.0.8 | 2,738 | 5/3/2021 |
2.0.7 | 8,189 | 4/23/2021 |
2.0.6 | 9,012 | 4/21/2021 |
2.0.5 | 13,090 | 4/14/2021 |
2.0.4 | 1,550 | 4/14/2021 |
2.0.3 | 5,679 | 4/10/2021 |
2.0.2 | 10,491 | 4/9/2021 |
2.0.1 | 11,817 | 4/6/2021 |
2.0.0-beta-1014 | 2,678 | 4/2/2021 |
2.0.0-beta-1013 | 2,297 | 3/29/2021 |
2.0.0-beta-1012 | 1,779 | 3/27/2021 |
2.0.0-beta-1011 | 1,086 | 3/25/2021 |
2.0.0-beta-1010 | 11,000 | 3/15/2021 |
2.0.0-beta-1009 | 3,019 | 3/12/2021 |
2.0.0-beta-1008 | 1,454 | 3/9/2021 |
2.0.0-beta-1007 | 5,306 | 2/28/2021 |
2.0.0-beta-1006 | 1,151 | 2/25/2021 |
2.0.0-beta-1005 | 1,129 | 2/25/2021 |
2.0.0-beta-1004 | 1,721 | 2/10/2021 |
2.0.0-beta-1003 | 3,850 | 1/25/2021 |
2.0.0-beta-1002 | 1,143 | 1/22/2021 |
2.0.0-beta-1001 | 364,331 | 1/19/2021 |
1.0.0 | 728,158 | 1/18/2021 |
1.0.0-beta-9722 | 64,529 | 12/4/2020 |
1.0.0-beta-9693 | 381,703 | 9/21/2020 |
1.0.0-beta-9681 | 17,389 | 8/6/2020 |
1.0.0-beta-9678 | 3,937 | 7/21/2020 |
1.0.0-beta-9672 | 14,428 | 6/22/2020 |
1.0.0-beta-9663 | 3,711 | 6/8/2020 |
1.0.0-beta-9660 | 4,332 | 6/8/2020 |
1.0.0-beta-9651 | 166,794 | 5/21/2020 |
1.0.0-beta-9637 | 60,879 | 3/2/2020 |
1.0.0-beta-9634 | 11,693 | 1/15/2020 |
1.0.0-beta-9626 | 9,977 | 1/8/2020 |
1.0.0-beta-9624 | 2,967 | 12/28/2019 |
1.0.0-beta-9621 | 1,300 | 12/28/2019 |
1.0.0-beta-9619 | 1,383 | 12/28/2019 |
1.0.0-beta-9617 | 1,435 | 12/24/2019 |
1.0.0-beta-9614 | 1,434 | 12/24/2019 |
1.0.0-beta-9608 | 68,814 | 10/30/2019 |
1.0.0-beta-9605 | 206,945 | 10/10/2019 |
1.0.0-beta-9599 | 92,808 | 9/20/2019 |
1.0.0-beta-9588 | 10,458 | 8/28/2019 |
1.0.0-beta-9586 | 2,228 | 8/22/2019 |
1.0.0-beta-9578 | 7,357 | 8/15/2019 |
1.0.0-beta-9571 | 110,663 | 4/2/2019 |
1.0.0-beta-9560 | 3,359 | 3/22/2019 |
1.0.0-beta-9558 | 1,628 | 3/21/2019 |
1.0.0-beta-9554 | 2,624 | 3/14/2019 |
1.0.0-beta-9545 | 32,740 | 3/5/2019 |
1.0.0-beta-9542 | 1,489 | 3/3/2019 |
1.0.0-beta-9519 | 17,930 | 2/4/2019 |
1.0.0-beta-9513 | 4,812 | 1/22/2019 |
1.0.0-beta-9507 | 1,712 | 1/21/2019 |
1.0.0-beta-9504 | 1,964 | 1/17/2019 |
1.0.0-beta-9501 | 1,519 | 1/17/2019 |
1.0.0-beta-9480 | 31,354 | 12/4/2018 |
1.0.0-beta-9463 | 4,635 | 11/15/2018 |
1.0.0-beta-9446 | 19,125 | 6/22/2018 |
1.0.0-beta-9442 | 59,054 | 6/22/2018 |
1.0.0-beta-9422 | 66,967 | 1/22/2018 |
1.0.0-beta-9415 | 2,283 | 1/16/2018 |
1.0.0-beta-9399 | 96,945 | 11/5/2017 |
1.0.0-beta-9398 | 1,750 | 11/5/2017 |
1.0.0-beta-9389 | 2,102 | 11/2/2017 |
1.0.0-beta-9334 | 2,441 | 8/30/2017 |
1.0.0-beta-9333 | 1,805 | 8/30/2017 |
1.0.0-beta-9327 | 14,771 | 8/15/2017 |
1.0.0-beta-9325 | 1,734 | 8/13/2017 |
1.0.0-beta-9308 | 1,860 | 8/10/2017 |
1.0.0-beta-9300 | 2,567 | 8/2/2017 |
1.0.0-beta-93 | 1,829 | 7/31/2017 |
1.0.0-beta-84 | 2,033 | 6/30/2017 |
1.0.0-beta-67 | 2,034 | 6/20/2017 |
1.0.0-beta-47 | 1,674 | 6/16/2017 |
1.0.0-beta-32 | 6,207 | 6/15/2017 |
1.0.0-beta-30 | 1,685 | 6/15/2017 |
1.0.0-beta-21 | 1,644 | 6/14/2017 |
1.0.0-beta-20 | 1,651 | 6/14/2017 |
1.0.0-beta-18 | 1,644 | 6/14/2017 |
1.0.0-beta-107 | 1,776 | 8/2/2017 |
0.1.0-alpha-11 | 1,688 | 6/13/2017 |