Scriban：高性能的.NET模板引擎应用指南

Scriban 是一个专为 .NET 提供的高性能、灵活的模板引擎。通过简单易懂的语法，它可以帮助开发者动态生成 HTML、文本或其他格式内容。得益于其丰富多样的功能和稳定的性能，Scriban 正成为 .NET 开发者的不二之选。这个组件，我基本用于生成项目脚手架用。

核心特点

高性能：针对大规模文本渲染优化。
语法丰富：支持条件判断、循环、模板继承、自定义功能等。
灵活扩展：支持自定义函数和自定义对象模型。

安装 Scriban

在项目中添加 Scriban 包

Bash
Install-Package Scriban

基本用法

以下代码展示了 Scriban 如何处理简单的模板渲染：

C#
using Scriban;

namespace AppScriban
{
    internal class Program
    {
        static void Main(string[] args)
        {
            var template = Template.Parse("Hello {{ name }}!");
            var result = template.Render(new { name = "World" });
            Console.WriteLine(result);
            Console.ReadKey();
        }
    }
}

解释：

模板中的 {{ name }} 是一个占位符。
使用 Render 方法通过匿名对象为模板赋值。

Scriban 语法应用

条件语句

使用 if-else 语法，轻松实现条件逻辑：

C#
using Scriban;

namespace AppScriban
{
    internal class Program
    {
        static void Main(string[] args)
        {
            var template = Template.Parse(@"
            {{ if age >= 18 }}
            你是一个成人.
            {{ else }}
            你是一个未成年人.
            {{ end }}
            ");
            var result = template.Render(new { age = 19 });
            Console.WriteLine(result);
            Console.ReadKey();
        }
    }
}

循环

Scriban 的 for 循环用于遍历集合，如下演示了渲染一个简单的 HTML 列表：

C#
using Scriban;

namespace AppScriban
{
    internal class Program
    {
        static void Main(string[] args)
        {
            var template = Template.Parse(@"
            <ul>
              {{ for item in items }}
              <li>{{ item }}</li>
              {{ end }}
            </ul>
            ");
            var result = template.Render(new { items = new[] { "Apple", "Banana", "Cherry" } });
            Console.WriteLine(result);
            Console.ReadKey();
        }
    }
}

内置函数和过滤器

Scriban 提供了丰富的函数和过滤器，处理字符串、数字和集合非常方便。

常见类别及函数

Array 函数
- array.add
- array.add_range
- array.compact
- array.concat
- array.cycle
- array.any
- array.each
- array.filter
- array.first
- array.insert_at
- array.join
- array.last
- array.limit
- array.map
- array.offset
- array.remove_at
- array.reverse
- array.size
- array.sort
- array.uniq
- array.contains
Date 函数
- （未在文件中详细展开）
HTML 函数
- html.newline_to_br
- html.url_encode
- html.url_escape
Math 函数
- math.abs
- math.ceil
- math.divided_by
- math.floor
- math.format
- math.is_number
- math.minus
- math.modulo
- math.plus
- math.round
- math.times
- math.uuid
- math.random
Object 函数
- object.to_json
- object.default
- object.eval
- object.eval_template
- object.format
Regex 函数
- regex.unescape
- regex.split
String 函数
- 大量函数，如：
  - string.capitalize
  - string.contains
  - string.empty
  - string.escape
  - string.md5
  - string.sha1
  - string.sha256
  - string.pluralize
  - string.prepend
  - string.remove
  - string.size
  - string.split
  - string.upcase
  - 等等，具体可从“String 函数”分类查看。
TimeSpan 函数

具体可见

Markdown
https://github.com/scriban/scriban/blob/master/doc/builtins.md

这些函数覆盖了对常见数据结构的处理，如数组、字符串、对象、数学运算、正则表达式匹配等。

内置函数

C#
using Scriban;

namespace AppScriban
{
    internal class Program
    {
        static void Main(string[] args)
        {
            var template = Template.Parse("The length of 'Hello' is {{ 'Hello' | string.size }}.");
            var result = template.Render();
            Console.WriteLine(result);
            Console.ReadKey();
        }
    }
}

自定义函数

除了内置函数，开发者还可以定义自己的函数：

C#
using Scriban;
using Scriban.Runtime;

namespace AppScriban
{
    internal class Program
    {
        static void Main(string[] args)
        {
            var scriptObject1 = new ScriptObject();
            scriptObject1.Import("myfunc", new Func<string>(() => "Yes"));

            var context = new TemplateContext();
            context.PushGlobal(scriptObject1);

            var template = Template.Parse("This is myfunc: `{{myfunc}}`");
            var result = template.Render(context);

            Console.WriteLine(result);

            Console.ReadKey();
        }
    }
}

高级功能探索

模板继承

模板继承让你可以复用母版布局来简化嵌套模板开发。

母版模板 (base.scriban)

HTML
<html>
<head>
    <title>{{ page.title }}</title>
</head>
<body>
    <h1>{{ page.title }}</h1>
    {{ page.content }}
</body>
</html>

子模板 (child.scriban)

text
{{ page = { title: "Welcome", content: "This is an example." } }}
{{ include 'base' }}

用代码加载模板并渲染：

C#
using Scriban;
using Scriban.Parsing;
using Scriban.Runtime;

namespace AppScriban
{
    public class FileTemplateLoader : ITemplateLoader
    {
        private readonly string _templateDir;

        public FileTemplateLoader(string templateDir)
        {
            _templateDir = templateDir;
        }

        // 将模板名称转换为完整路径  
        public string GetPath(TemplateContext context, SourceSpan callerSpan, string templateName)
        {
            return Path.Combine(_templateDir, $"{templateName}.scriban");
        }

        public string Load(TemplateContext context, SourceSpan callerSpan, string templatePath)
        {
            if (!File.Exists(templatePath))
            {
                throw new FileNotFoundException($"Template file not found: {templatePath}");
            }

            return File.ReadAllText(templatePath);
        }

        public async ValueTask<string> LoadAsync(TemplateContext context, SourceSpan callerSpan, string templatePath)
        {
            if (!File.Exists(templatePath))
            {
                throw new FileNotFoundException($"Template file not found: {templatePath}");
            }

            return await File.ReadAllTextAsync(templatePath);
        }
    }

    internal class Program
    {
        static void Main(string[] args)
        {
            // 获取当前目录作为模板目录  
            string templateDir = Environment.CurrentDirectory;

            // 创建模板加载器  
            var templateLoader = new FileTemplateLoader(templateDir);

            // 创建模板上下文  
            var context = new TemplateContext
            {
                TemplateLoader = templateLoader,  // 设置模板加载器  
                EnableRelaxedMemberAccess = true, // 启用宽松的成员访问  
                EnableRelaxedTargetAccess = true  // 启用宽松的目标访问  
            };

            // 添加全局变量  
            var globalObject = new ScriptObject();
            // 可以添加其他全局变量  
            // globalObject["siteName"] = "My Website";  
            // globalObject["currentYear"] = DateTime.Now.Year;  
            context.PushGlobal(globalObject);

            try
            {
                // 直接解析子模板，子模板会通过include指令引用基础模板  
                var childTemplate = Template.Parse(File.ReadAllText("child.scriban"));

                // 渲染子模板  
                var result = childTemplate.Render(context);
                Console.WriteLine(result);
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }

            Console.ReadKey();
        }
    }
}

自定义对象模型

Scriban 支持以自定义对象模型作为数据源，方便处理复杂场景：

C#
using Scriban;
using Scriban.Parsing;
using Scriban.Runtime;

namespace AppScriban
{
    public class Person
    {
        public string Name { get; set; }
        public int Age { get; set; }
    }

    internal class Program
    {
        static void Main(string[] args)
        {
            var template = Template.Parse(@"
            {{ person.name }} is {{ person.age }} years old.
            {{ if person.age >= 18 }}
            {{ person.name }} is an adult.
            {{ else }}
            {{ person.name }} is a minor.
            {{ end }}
            ");
            var result = template.Render(new { person = new Person { Name = "Alice", Age = 25 } });
            Console.WriteLine(result);

            Console.ReadKey();
        }
    }
}

总结

通过本文的介绍和实践示例，你已经掌握了 Scriban 的核心能力和高级用法。从简单的模板到复杂的继承场景，Scriban 都能胜任，同时通过优化提升性能。

如果你正在寻找一个高性能、灵活的模板引擎，不妨尝试将 Scriban 运用于你的实际项目中！与其共创高效的开发体验，助力你的 .NET 应用更上一层楼！

关注我们，了解更多实用开发技巧推荐，让编程更高效更有趣！ 😊