一、反斜杠 \ 转义规则

预设变量：#set($dog = "woof woof")

1. Velocity变量名必须字母开头，$10.0 不会识别为变量，直接原样输出，所以文本里写微软$10.0美元无需额外转义；
2. 连续反斜杠两两抵消；只有\$组合具备转义美元符号的能力；
3. 如果页面需要原样展示$变量名，标准写法：\$dog。

二、#if 分支条件语法

#set($ages = 22)
#if ($ages <13)
    <h1>你是儿童</h1>
#elseif ($ages <18)
    <h1>你是少年</h1>
#elseif ($ages <35)
    <h1>你是青年</h1>
#elseif ($ages <60)
    <h1>你是中年</h1>
#else
    <h1>你是老年</h1>
#end

执行结果

$ages=22，满足 22 < 35 → 输出：<h1>你是青年</h1>

注意

1. 结尾必须写#end闭合判断块，缺少会直接报错；
2. 关键字：#elseif（不要分开写成 #else if，这是错误写法）；
3. 条件支持：< > <= >= == != && || 等运算符；
4. 匹配逻辑：从上往下依次判断，命中第一条满足条件分支后，后续分支不再执行。

一、后端 Person 实体代码（C#）

public class Person
{
    private string name;
    public string Name
    {
        get { return name; }
        set { name = value; }
    }
    private int age;
    public int Age
    {
        get { return age; }
        set { age = value; }
    }

    //无参构造
    public Person(){}
    //带参构造
    public Person(string name, int age)
    {
        this.name = name;
        this.age = age;
    }

    //无参实例方法
    public string getMyName()
    {
        return this.name;
    }

    //多参数实例方法
    public string JoinStr(string str1, string str2)
    {
        return str1 + str2;
    }
}

cs后端代码中设置对象变量

Person pTest = new Person("Tom", 22);
context.Put("pTest", pTest);

二、VTL模板代码 & 渲染说明

方法的调用<br />
$pTest.getMyName();

#set($a = "hello")
#set($b = "foxdevelop")

$pTest.JoinStr($a, $b);

1. $pTest.getMyName()

• 调用对象无参方法 getMyName()
• 返回 Tom

Velocity 调用无参方法：括号()可以省略，$pTest.getMyName 等价 $pTest.getMyName()

2. $pTest.JoinStr($a, $b)

• 调用带两个字符串参数的方法
• VTL 会先解析 $a、$b，传入实参 "hello"、"foxdevelop"
• 返回拼接结果：hellofoxdevelop

总结

1. 方法名大小写严格匹配
   C# getMyName() ≠ GetMyName()，模板必须和代码写法一致。
2. 传参直接写变量
   不需要额外引号，$pTest.JoinStr($a,$b) 正确；不要写成 $pTest.JoinStr("$a","$b")（会传递字面字符串”$a”）
3. 属性 vs 方法区分

• $pTest.Name → 访问属性（getter）
• $pTest.getMyName() → 调用方法

1. 返回值自动输出
   模板里直接写 $对象.方法()，Velocity会自动打印方法返回值；如果不需要输出，用 #set 接收结果：

#set($result = $pTest.JoinStr($a,$b))

三、最终页面渲染输出

方法的调用
Tom;

hellofoxdevelop;

变量预设：#set ($valok = "hello foxdevelop")

变量边界 ${} 与 . 访问辨析

${valok}.cn 变量 + 后缀拼接
${valok.cn} 访问对象valok下的cn属性

单引号 / 双引号 & 变量粘连

代码	渲染结果	原理说明
what$valok	whathello foxdevelop	直接拼接，Velocity自动识别变量边界
what$"valok"	what$”valok”	语法错误写法，$后面不能直接跟引号，无法识别变量
what"$valok"	what”hello foxdevelop“	引号只是普通文本，模板内的引号不触发字符串解析，变量正常渲染
what'$valok'	what’hello foxdevelop‘	同上，单引号属于普通文本字符
$valokwhat	$valokwhat	无法识别变量！Velocity把valokwhat整体当成变量名，找不到该变量，原样输出
${valok}what	hello foxdevelopwhat	大括号锁定边界，完美解决变量和文字粘连问题

总结

1. 变量粘连场景务必使用 ${变量名}
   错误：$valokwhat；正确：${valok}what
2. 拼接后缀文本：${valok}.cn 不要写成 ${valok.cn}
3. $!变量 静默引用：变量不存在时输出空白，不会打印$xxx
4. 模板HTML里的单/双引号只是普通字符；只有#set赋值内部才区分单引号（不解析变量）、双引号（解析变量）

#set($a = "$valok") // 双引号：解析变量，a=hello bamn
#set($a = '$valok') // 单引号：不解析变量，a=$valok

一、遍历字符串List

C#后端代码

List<string> strList = new List<string>() {"dsd","sdfsd","asdfsd","asdfsdfsd"};
context.Put("strList", strList);

Velocity模板代码

#foreach($str in $strList)
    $str <br/>
#end

执行效果：循环取出列表每一个字符串，换行输出。

语法说明

#foreach(循环变量 in 集合) 开启循环，#end 闭合循环。

二、遍历自定义实体类 List

1. Person实体（C#）

public class Person
{
    private string name;
    public string Name
    {
        get { return name; }
        set { name = value; }
    }
    private int age;
    public int Age
    {
        get { return age; }
        set { age = value; }
    }
    public Person(){}
    public Person(string name,int age)
    {
        this.name = name;
        this.age = age;
    }
}

2. 后端封装List

List<Person> pList = new List<Person>();
pList.Add(new Person("Jack", 1));
pList.Add(new Person("Ben", 11));
pList.Add(new Person("Kevin", 100));
pList.Add(new Person("Simon", 500));
pList.Add(new Person("Lulu", 20));
context.Put("pList", pList);

3.模板访问属性写法

模板代码：

#foreach($per in $pList)
<tr>
    <td>$per.name</td>
    <td>$per.age</td>
</tr>
#end

会读取不到数据！报错/空白

根本原理

Velocity 访问对象属性规则：
$per.xxx 会自动寻找 公共Get方法 GetXxx()

• $per.name → 尝试调用 per.getName()
• $per.age → 尝试调用 per.getAge()

你的实体：

• 私有字段：name、age
• 公共属性大写开头：Name、Age，对应方法 GetName()、GetAge()

正确模板写法：

#foreach($per in $pList)
<tr>
    <td>$per.Name</td>
    <td>$per.Age</td>
</tr>
#end

补充：C#规范属性首字母大写；Java实体属性一般小写，这是新手最容易踩的大小写陷阱。

三、#foreach内置常用变量

循环内部自带变量，可以直接使用：

示例：

#foreach($per in $pList)
    $foreach.count 、姓名：$per.Name
#end

四、表格显示

<table border="0" cellpadding="0" cellspacing="0">
#foreach($per in $pList)
    <tr>
        <td>$per.Name</td>
        <td>$per.Age</td>
    </tr>
#end
</table>

总结

1. #foreach(变量 in 集合) + #end 是Velocity标准循环；
2. 遍历普通List，直接输出$变量；
3. 遍历实体对象：$对象.属性名 匹配公共属性名大小写，不要访问私有字段；
4. C#实体属性建议统一大写首字母，模板保持一致书写；
5. 如果出现数据空白，优先检查属性大小写、是否存在get访问器。

一、模板注释区分

开发建议：业务说明代码注释优先使用## / #* *#，避免页面源码泄露注释信息。

二、变量命名规则

官方命名基础规则

1. 变量首字符必须是英文字母（a-z / A-Z）
2. 后续字符允许：字母、数字0-9、下划线_、减号-

减号 - 存在运算符歧义

#set($name-d = "test")

执行时会报截图错误：Encountered "name" ... Was expecting one of:
原因：Velocity把 - 识别为减法运算符！
引擎解析逻辑：$name - d，误认为是变量$name减去变量d，语法直接冲突。

两种解决方案：

1. 推荐：改用下划线命名（无歧义，通用规范）

#set($name_d = "hello world")

2. 大括号限定变量边界（兼容带减号名称）

#set(${name-d} = "hello world")
${name-d}

合法/非法示例对照

# 合法
#set($name_d = "下划线")
#set($name12d = "字母开头+数字")
#set(${name-1_2d} = "带减号必须加大括号")

# 直接写减号，不加大括号 → 解析报错
#set($name-d = "报错！")
#set($name-1_2d = "报错！")

三、#set 语法书写规范

标准写法（括号前后空格可灵活，建议统一风格）

#set($变量名 = "值")

字符串必须使用双引号包裹；等号左右建议保留空格，可读性更好。

一、核心作用

Velocity 模板引擎通过 #include / #parse 实现模板复用。
网页通用部分（页面头部导航_head.htm、底部版权_footer.htm）抽离为独立子模板，在页面中引入，避免多处重复编写HTML。

二、两者核心区别

1. #include("文件路径")

单纯把文件原文原样输出，不会解析子模板中的Velocity变量（$!{xxx}）

• 子模板内的 $!{testinclude} 不会被渲染，直接原样输出字符串$!{testinclude}
• 支持一次性传入多个文件：#include("a.htm","b.htm")
• 适合：纯静态HTML、不含任何VTL变量的静态片段

2. #parse("文件路径")

引入子模板并完整解析Velocity语法，父模板传递的变量可以在子模板中正常渲染

• 子模板里的 $!{testinclude} 会读取上下文变量，替换成后端传入的值
• 只能接收单个文件路径，不支持同时引入多个文件
• 适合：头部、底部这类包含变量的公共模板（页面标题、版权动态信息等）

对应你截图笔记原文：
#include只是单纯的把子模板的代码加入到主模板里面，而不会解析，而#parse则会解析

三、案例演示

1. 后端代码（.cs）

context.Put("testinclude", "子模板的文字：");

2. 子模板 _footer.htm 内容

版权信息 $!{testinclude}

场景① 使用 #include("./themes/default/_footer.htm")

页面输出结果：

版权信息 $!{testinclude}

变量没有被解析，原样打印占位符。

场景② 使用 #parse("./themes/default/_footer.htm")

页面输出结果：

版权信息 子模板的文字：

变量成功渲染，这也是项目中头部、底部通用模板优先使用#parse的原因。

四、使用场景推荐

开发规范：
页面导航、底部版权这类大概率需要动态变量的公共组件，统一使用#parse；纯静态文本、样式片段使用#include。

一、变量定义#set()

两种方式定义变量：
方式1：后台C#/Java代码预先定义变量，模板页面读取；
方式2：直接在模板内部使用 #set() 定义变量（本课重点）

#set($name = "hello foxdevelop.com")
#set($okay = "common baby")
#set($nameokay = "$name|$okay")

• #set(变量 = 值)，支持字符串、数字、数组、对象属性、其他变量赋值
• 弱类型，不需要声明变量类型

二、变量渲染两种写法和规范

1. 基础形式

• $name：变量不存在时，原样输出字符串 $name
• $!name：静默渲染，变量不存在时输出空白（推荐避免页面出现$xxx文本）
• 推荐标准写法：${name}（大括号隔离变量边界）

2. 边界问题示例

#set($name = "hello")
$namehello     × 引擎会识别变量名为 $namehello，找不到变量
${name}hello   √ 正确，引擎识别变量$name，后面拼接hello文本

三、单行注释 ##

## 这里表示注释，最终不会显示
#set($name = "test") ## 行尾注释也支持

1. 注释内容不会输出到最终渲染页面；
2. 浏览器查看网页源代码，也看不到注释文本（模板引擎渲染阶段直接丢弃注释）。

四、#set 支持多种赋值类型

## 字符串赋值
#set($name = "hello world")

## 将变量赋值给另一个变量
#set($obj= $name)

## 对象属性赋值
#set($obj.Friend = "monica")
#set($obj.Blame = $whitehouse.Leak)

## 调用方法，将返回值赋值
#set($obj.Plan = $spindoctor.weave($web))

## 数字赋值
#set($obj.Number = 123)

## 数组赋值
#set($obj.Say = ["Not", $my, "fault"])

五、变量不存在的特殊规则

$sadfsdfsd

当模板引擎找不到该变量时：

• 普通写法 $sadfsdfsd：直接原样输出文本 $sadfsdfsd
• 如果写成 $!sadfsdfsd：变量不存在，输出空白字符串

1. PageInfo实体类

之前我们都是用单个字符串传递，但是这样效率太低，而且代码维护也不方便，我们可以通过封装实体对象的方式，会使得代码更具直观

public class PageInfo
{
    private bool IsShowImage;
    public bool IsShowImage1
    {
        get { return IsShowImage; }
        set { IsShowImage = value; }
    }
}

• 私有字段IsShowImage，对外暴露属性IsShowImage1
• 模板中访问：$info.IsShowImage1

2. 填充上下文数据

//模板上下文容器
IContext context = new VelocityContext();

PageInfo pi = new PageInfo();
pi.IsShowImage1 = true;

//将对象pi以键名info存入上下文
context.Put("info",pi);

//字符串变量示例
context.Put("infotitle","你好");

context.Put("键名",数据)：把数据交给模板，模板通过$键名获取。

二、Velocity模板核心语法

1. 关键字标识 #

以#开头为指令，常见：
#if、#else、#end、#foreach、#set、#include

条件渲染示例：

请实现准备两张图片，放到网站根目录下的Contents/Images里面，通过设置IsShowImage1可以显示不同的图片

#if($info.IsShowImage1)
    <img src="./Contents/Images/a.gif" />
#else
    <img src="./Contents/Images/b.gif" />
#end

逻辑：当IsShowImage1=true展示a.gif，否则展示b.gif

2. 变量标识 $

• $变量名：输出变量值
• ${变量名}：界定变量边界（重点！）

场景：变量后紧跟英文，引擎无法区分变量名范围

错误写法：$infotitlefoxdevelop.com
引擎会识别成变量名叫 infotitlefoxdevelop，不存在！

正确写法：${infotitle}foxdevelop.com
引擎识别 infotitle 为变量，后面拼接字符串foxdevelop.com

3. 静默符 ! → $!变量名

默认行为：如果变量不存在，页面原样输出$变量名文本
$!变量名：变量不存在或者为null时，输出空白，不打印$符号

对比示例：

完整测试代码：

${infotitle}foxdevelop.com <br/>
$!infotitlefoxdevelop.com <br/>
$infotitle <br/>
$!infotitle <br/>

总结

1. 变量后面拼接文字，务必使用 ${变量} 包裹
2. 生产环境优先使用 $!{变量名}，防止变量为空时页面打印原始$xxx破坏布局
3. #if 判断布尔属性，直接写#if($info.IsShowImage1)，不需要额外==true

介绍

ASP.NET 项目中使用广泛；
ASP.NET MVC 配套有 Razor 模板；

传统 .aspx 页面项目想要引入 MVC 模式时，很多开发者选用 NVelocity。

NVelocity 早已停止维护，仅用于老旧 .NET Framework 历史项目；新项目优先使用 Razor、Handlebars.NET 等现代模板引擎。

版本与 .NET Framework 对应关系

Velocity 是老牌 Java 模板引擎，语法简洁，使用 #、$ 作为模板标记；NVelocity 完整移植这套语法；

下载

官方最后一次更新是2018年，最新的版本是1.2.0

读者可以到下面地址下载

它是开源的，托管在GitHub castleproject/NVelocity: Castle’s NVelocity

官方下载的不是编译好的dll，读者可以下载下来后，自己编译，或者直接把项目引入到你项目的解决方案中。

用vs打开sln

最后一个版本是基于.NET Core 2.1的 建议读者可以把它升级到.NET 4.8

编译后，在目录下面 就可以看到 dll

然后引入到其他asp.net web 项目中就可以。把上面的NVelocity.dll 引入到您的web项目中。

引入项目

项目中引用程序集：NVelocity.dll
核心优势：基于该模板引擎，实现网站多模板切换（换肤）十分便捷

在网站根目录创建文件夹：Themes，作为所有模板存放根目录
在 Themes 内部建立多个主题文件夹，例如：

我们在网站根目录下面创建Themes文件夹，作为主题目录

主题目录

然后创建一个default文件夹，作为 默认模板
后续可新增 Themes/blue、Themes/dark 等多套模板

网站根目录
└── Themes
    ├── default      # 默认主题模板文件
    ├── dark         # 深色主题模板文件
    └── blue         # 蓝色主题模板文件

运行时通过配置读取当前启用的主题名称，NVelocity 加载对应主题目录下的模板文件；
切换模板本质：修改配置指向不同主题文件夹，无需改动业务逻辑代码；
适合老旧 ASP.NET WebForm（aspx）项目实现前台页面换肤功能。

aspx

新建一个aspx的页面 ，网站根目录新建 Register.aspx，作为演示页面访问。

在 Themes/default 目录下新建模板文件：register.htm，它作为NVelocity 模板文件，存放 HTML 与 Velocity 模板语法

打开 Register.aspx，仅保留页面指令，删除其余所有 HTML 内容：

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Register.aspx.cs" Inherits="NVelocityStudy.Web.Register" %>

aspx 不再负责渲染页面，仅充当控制器入口，由后台代码调用 NVelocity 加载 register.htm 模板输出内容。

网站根目录
├─ Register.aspx          # 访问入口
├─ Register.aspx.cs       # 后台逻辑
└─ Themes
    └─ default
        └─ register.htm   # NVelocity模板页面

后续在 Register.aspx.cs 编写代码，指定加载当前主题下的 register.htm 模板、传入数据模型，最终输出 HTML

如果切换主题，只需要修改主题目录指向，加载对应主题文件夹内的 register.htm

aspx.cs

打开后台代码文件：Register.aspx.cs 在 Page_Load 方法内编写 NVelocity 渲染逻辑，页面加载时执行模板解析输出。

using System;
using System.Collections.Generic;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace NVelocityStudy.Web
{
    public partial class Register : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            // 此处编写NVelocity加载模板、渲染页面的代码
        }
    }
}

pageload中添加下面代码

protected void Page_Load(object sender, EventArgs e)
{
    //第一步 创建Velocity引擎实例 VelocityEngine
    VelocityEngine ve = new VelocityEngine();

    //第二步 初始化引擎配置
    ExtendedProperties pros = new ExtendedProperties();
    pros.AddProperty(RuntimeConstants.RESOURCE_LOADER, "file"); // 文件方式加载模板
    pros.AddProperty(RuntimeConstants.FILE_RESOURCE_LOADER_PATH, Server.MapPath(@"")); // 模板根目录
    ve.Init(pros); // 使用配置初始化引擎

    //第三步 读取模板文件
    Template template = ve.GetTemplate("themes/default/register.htm");

    //第四步 创建上下文，向模板传递变量
    IContext context = new VelocityContext();
    context.Put("websiteName", "FoxDevelop");
    context.Put("domainName", "foxdevelop.com");

    //第五步 合并模板与数据，渲染HTML
    StringWriter writer = new StringWriter();
    template.Merge(context, writer); //渲染结果存入writer

    //第六步 输出页面
    Response.Write(writer.ToString().Replace("\r\n", "<br/>"));
}

这段代码，就是读取模板html文件，并且创建一些变量，用来替换html中的占位符

1. 实例化 VelocityEngine 独立引擎对象，区别于全局静态Velocity.Init()，支持多套独立配置。
2. 引擎初始化与配置

• RESOURCE_LOADER=file：指定模板加载方式为本地文件；
• FILE_RESOURCE_LOADER_PATH：设置模板查找根路径；
• ve.Init(pros)：加载配置完成初始化。

3. 加载模板 GetTemplate() 基于配置的根路径，读取 themes/default/register.htm 模板文件。
4. VelocityContext 数据上下文context.Put(键, 值)：把 C# 变量传入模板，在 htm 中使用$websiteName、$domainName取值。
5. 模板 Merge 渲染template.Merge(上下文, 输出流)，将变量填充进模板，生成完整 HTML 字符串； 使用StringWriter接收渲染后的文本。
6. Response 输出 把最终 HTML 发送浏览器；Replace("\r\n","<br/>")：将源码换行符转换为 HTML 换行标签。

htm模板

修改主题目录中的register.htm

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
</head>
<body>
    网站：$websiteName <br />
    域名：$domainName
</body>
</html>

上面两个$xxxxxxx 就是pageload中创建的两个变量的占位符，渲染过程会替换成对应的值。

1. 变量标识 $变量名 $websiteName、$domainName 是 NVelocity (VTL) 变量语法。 程序代码中 context.Put("websiteName", "FoxDevelop") 赋值，渲染时引擎自动替换：

• $websiteName → FoxDevelop
• $domainName → foxdevelop.com

运行效果

网站：FoxDevelop
域名：foxdevelop.com