C# Scriban
last modified July 5, 2023
C# Scriban tutorial shows how to usie Scriban template engine in C#.
Scriban template engine
A template engine or template processor is a library designed to combine templates with a data model to produce documents. Template engines are often used to generate large amounts of emails, in source code preprocessing, or producing dynamic HTML pages.
We create a template engine, where we define static parts and dynamic parts. The dynamic parts are later replaced with data. The rendering function later combines the templates with data. A template engine is used to combine templates with a data model to produce documents.
Scriban uses {{ }} for code blocks and {%{ }%} for
escape blocks. Any other text is considered as a text block and simply output as
is.
The Template.Parse method parses the text data into a template and
the Template.Render renders the template into the final output
using the provided data model.
$ dotnet add package Scriban
We need to add the Scriban package to our projects.
Scriban simple example
The following is a simple Scriban example.
using Scriban;
var name = "John Doe";
var tpl = Template.Parse("Hello {{name}}!");
var res = tpl.Render(new { name = name });
Console.WriteLine(res);
The program prints a small message to the console.
var tpl = Template.Parse("Hello {{name}}!");
The Template.Parse method parses the specified scripting text into
a template. With {{ }} we output the content of the
name variable.
var res = tpl.Render(new { Name = name });
The Render method renders the template using the specified object
model.
$ dotnet run Hello John Doe!
In the next example, we pass two variables to the template engine.
using Scriban;
var name = "John Doe";
var occupation = "gardener";
var txt = "{{name}} is a {{occupation}}";
var tpl = Template.Parse(txt);
var res = tpl.Render(new { name, occupation });
Console.WriteLine(res);
The program prints a message using data from two variables: name
and occupation.
$ dotnet run John Doe is a gardener
Scriban for loop
Loops are created with for directive.
using Scriban;
string[] words = { "sky", "blue", "falcon", "book", "ocean", "dog" };
var html = @"
<ul>
{{- for word in words }}
<li> {{ word }} </li>
{{- end }}
</ul>
";
var tpl = Template.Parse(html);
var res = tpl.Render(new { words = words });
Console.WriteLine(res);
The example uses the for directive to output an array of words into
an HTML list.
{{- for word in words }}
<li> {{ word }} </li>
{{- end }}
We iterate over the array of words. The - character strips white
space characters on the left.
$ dotnet run
<ul>
<li>sky</li>
<li>blue</li>
<li>falcon</li>
<li>book</li>
<li>ocean</li>
<li>dog</li>
</ul>
Scriban string functions
We can use several string functions in the templates.
using Scriban;
var msg = "an old falcon";
var data = @"
{{ msg | string.capitalize }}
{{ msg | string.upcase }}
The message has {{ msg | string.size }} characters.
The message has {{ msg | string.split ' ' | array.size }} words.
";
var tpl = Template.Parse(data);
var res = tpl.Render(new { msg = msg });
Console.WriteLine(res);
We have a string message. We apply several string functions on the message.
{{ msg | string.capitalize }}
{{ msg | string.upcase }}
We capitalize and upcase the message.
The message has {{ msg | string.size }} characters.
We count the number of characters in the message.
The message has {{ msg | string.split ' ' | array.size }} words.
We count the number of words in the message. In addition to
string.split function, we use the array.size to get
the size of the array of split strings.
$ dotnet run An old falcon AN OLD FALCON The message has 13 characters. The message has 3 words.
Scriban array functions
Scriban supports array functions.
using Scriban;
int[] vals = { 2, 1, -3, 0, -1, -2, 3 };
var data = @"
The array has {{ vals.size }} elements
First element: {{ vals[0] }}
Last element: {{ vals[-1] }}
Sorted elements: {{ vals | array.sort}}
";
var tpl = Template.Parse(data);
var res = tpl.Render(new { vals = vals });
Console.WriteLine(res);
We have an array of integers. With built-in array functions, we count the elements and sort them.
$ dotnet run The array has 7 elements First element: 2 Last element: 3 Sorted elements: [-3, -2, -1, 0, 1, 2, 3]
Scriban conditions
We can use if/else if/else conditions in templates.
using Scriban;
string?[] names = { "John", "Nelly", null, "George" };
var data = @"
{{- for name in names -}}
{{ if !name }}
Hello there!
{{ else }}
Hello {{name}}!
{{ end }}
{{- end }}";
var tpl = Template.Parse(data);
var res = tpl.Render(new { names = names });
Console.WriteLine(res);
We have an array of names. With the if condition, we check if the element is not null.
$ dotnet run Hello John! Hello Nelly! Hello there! Hello George!
Scriban read template from file
In the following example, we read the tempate file from a file.
<table>
<thead>
<tr>
<th>Name</th>
<th>Occupation</th>
</tr>
</thead>
<tbody>
{{- for user in users }}
<tr>
<td>{{ user.name }}</td>
<td>{{ user.occupation }}</td>
</tr>
{{- end }}
</tbody>
</table>
The template file outputs data in an HTML table.
using Scriban;
var users = new List<User>
{
new ( "John Doe", "gardener"),
new ( "Roger Roe", "driver"),
new ( "Lucy Smith", "teacher")
};
var fileName = "users.tpl";
var data = File.ReadAllText(fileName);
var tpl = Template.Parse(data);
var res = tpl.Render(new { users = users });
Console.WriteLine(res);
record User(string Name, string Occupation);
The data is stored in a list of records. The template file is loaded with
the File.ReadAllText method.
$ dotnet run
<table>
<thead>
<tr>
<th>Name</th>
<th>Occupation</th>
</tr>
</thead>
<tbody>
<tr>
<td>John Doe</td>
<td>gardener</td>
</tr>
<tr>
<td>Roger Roe</td>
<td>driver</td>
</tr>
<tr>
<td>Lucy Smith</td>
<td>teacher</td>
</tr>
</tbody>
</table>
Source
In this article we have worked with the Scriban template engine in C#.
Author
List all C# tutorials.