Scriban模板引擎中的成员名称转换机制解析

在使用Scriban模板引擎时，开发者可能会遇到一个常见问题：模板中的变量明明与模型属性匹配，却无法正常渲染出预期的值。本文将深入探讨这一现象背后的原因及解决方案。

问题现象

当开发者尝试使用以下代码渲染模板时：

var templateText = "Hello {{ UserName }}, go to {{ HostName }}/change-email/{{ Token }}";
var model = new {
    UserName = "John",
    HostName = "https://example.com",
    Token = "abc123"
};

得到的输出结果却是："Hello , go to /change-email/"，模型属性值没有被正确渲染。

原因分析

这一现象源于Scriban模板引擎的默认成员重命名机制。Scriban为了保持与Liquid模板的兼容性，默认会将.NET对象的属性名转换为小写并用下划线分隔的格式。具体转换规则如下：

• 原属性名：UserName
• 转换后：user_name

因此，当模板中使用{{ UserName }}时，实际上需要匹配的是模型中的user_name属性，而非原始的UserName属性。

解决方案

开发者有以下几种方式解决这个问题：

方案一：修改模板中的变量名

将模板中的变量名改为转换后的格式：

Hello {{ user_name }}, go to {{ host_name }}/change-email/{{ token }}

方案二：禁用成员重命名

通过修改模板的成员重命名策略，可以禁用这一转换行为：

var templateOptions = new TemplateOptions {
    MemberRenamer = member => member.Name
};
var template = Template.Parse(templateText, options: templateOptions);

方案三：使用自定义重命名策略

如果需要特定的命名转换规则，可以实现自定义的重命名策略：

var templateOptions = new TemplateOptions {
    MemberRenamer = member => {
        // 自定义转换逻辑
        return member.Name.ToLowerInvariant();
    }
};

最佳实践建议

1. 一致性原则：在项目中统一使用一种命名风格，要么全部使用转换后的命名，要么禁用转换功能。

2. 跨团队协作：如果模板需要由非开发人员编辑，建议使用更友好的命名方式，可以考虑禁用转换或实现更简单的转换策略。

3. 性能考量：频繁的成员名称转换会带来一定的性能开销，在性能敏感场景下应考虑缓存模板或优化重命名策略。

理解Scriban的这一默认行为，能够帮助开发者避免在模板渲染过程中遇到变量不匹配的问题，从而更高效地使用这一强大的模板引擎。