Apresentação do NVelocity

Motor de templates para plataforma .NET, uma versão portada para .NET do Velocity, voltado para a plataforma Java.

Apresentação

Amplamente utilizado em projetos ASP.NET;
O ASP.NET MVC conta com o motor de templates Razor nativo;

Muitos desenvolvedores optam pelo NVelocity quando querem adotar o padrão MVC em projetos tradicionais com páginas .aspx.

O NVelocity não recebe mais atualizações e só é utilizado em projetos legados do .NET Framework. Para projetos novos, dê preferência a motores modernos como Razor e Handlebars.NET.

Relação entre versões e o .NET Framework

Versão do .NET Framework	Versão do NVelocity
.NET 4.0	1.0 (última versão oficial)
.NET 2.0	0.5
.NET 1.0	0.48

Velocity é um motor de templates tradicional para Java, com sintaxe compacta que usa # e $ como marcadores. O NVelocity traz essa sintaxe integralmente para o ambiente .NET;

Download

A última atualização oficial ocorreu em 2018, sendo a versão mais recente a 1.2.0

Você pode baixar o código no endereço abaixo

Trata-se de um projeto open source hospedado no GitHub castleproject/NVelocity: Castle’s NVelocity

O arquivo baixado oficialmente não contém uma DLL já compilada. Você pode baixar o código fonte e compilar manualmente, ou adicionar o projeto diretamente à sua solução.

Abra o arquivo sln no Visual Studio

A última versão é baseada no .NET Core 2.1. Recomenda-se atualizar o projeto para o .NET 4.8

Após compilar, as DLLs estarão disponíveis no diretório de saída

Depois basta importar o arquivo em outros projetos ASP.NET Web. Adicione o NVelocity.dll ao seu projeto web.

Integração ao projeto

Adicione a referência ao assembly NVelocity.dll no projeto
Vantagem principal: com esse motor, fica muito simples implementar troca de múltiplos templates (mudança de tema) no site

Crie uma pasta chamada Themes na raiz do site, que funcionará como diretório principal de todos os templates
Dentro de Themes, crie subpastas para cada tema, como nos exemplos:

Crie a pasta Themes na raiz web como diretório de temas

Diretório de temas

Em seguida, crie uma pasta default para o template padrão
Você poderá adicionar outros conjuntos depois: Themes/blue, Themes/dark e assim por diante

Raiz do site
└── Themes
    ├── default      # Arquivos do tema padrão
    ├── dark         # Arquivos do tema escuro
    └── blue         # Arquivos do tema azulCode language: PHP (php)

Em tempo de execução, o nome do tema ativo é lido da configuração e o NVelocity carrega os templates da pasta correspondente.
A troca de template funciona alterando apenas o caminho configurado para a pasta de temas, sem necessidade de mudar o código de regras de negócio.
Ideal para projetos antigos ASP.NET WebForm (.aspx) que precisam de troca de visual na área pública.

aspx

Crie uma nova página aspx na raiz do site: Register.aspx, usada como exemplo de acesso.

Dentro de Themes/default, crie o arquivo de template register.htm. Esse arquivo é o template NVelocity e contém código HTML e sintaxe Velocity.

Abra Register.aspx, mantenha apenas a diretiva da página e apague todo o restante do conteúdo HTML:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Register.aspx.cs" Inherits="NVelocityStudy.Web.Register" %>Code language: HTML, XML (xml)

O arquivo aspx não fará mais a renderização da página, ele só serve como ponto de entrada do controlador. O código-behind chamará o NVelocity para carregar o template register.htm e gerar o conteúdo final.

Raiz do site
├─ Register.aspx          # Ponto de acesso
├─ Register.aspx.cs       # Lógica do código-behind
└─ Themes
    └─ default
        └─ register.htm   # Template NVelocityCode language: PHP (php)

Depois escreva o código em Register.aspx.cs para carregar o template register.htm do tema atual, enviar o modelo de dados e gerar o HTML final.

Para trocar de tema, basta alterar o caminho do diretório para carregar o arquivo register.htm da pasta do tema escolhido.

aspx.cs

Abra o arquivo de código-behind Register.aspx.cs. Implemente a lógica de renderização do NVelocity dentro do método Page_Load, executado para processar o template quando a página carregar.

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)
        {
            // Insira aqui o código para carregar o template e renderizar a página com NVelocity
        }
    }
}Code language: C# (cs)

Adicione o código abaixo dentro de Page_Load

protected void Page_Load(object sender, EventArgs e)
{
    //Passo 1: Criar instância do VelocityEngine
    VelocityEngine ve = new VelocityEngine();

    //Passo 2: Inicializar configurações do motor
    ExtendedProperties pros = new ExtendedProperties();
    pros.AddProperty(RuntimeConstants.RESOURCE_LOADER, "file"); // Carregar templates por arquivo
    pros.AddProperty(RuntimeConstants.FILE_RESOURCE_LOADER_PATH, Server.MapPath(@"")); // Diretório raiz dos templates
    ve.Init(pros); // Inicializar motor com as configurações

    //Passo 3: Ler arquivo de template
    Template template = ve.GetTemplate("themes/default/register.htm");

    //Passo 4: Criar contexto e enviar variáveis ao template
    IContext context = new VelocityContext();
    context.Put("websiteName", "FoxDevelop");
    context.Put("domainName", "foxdevelop.com");

    //Passo 5: Combinar template e dados para renderizar HTML
    StringWriter writer = new StringWriter();
    template.Merge(context, writer); // O resultado renderizado é salvo no writer

    //Passo 6: Enviar conteúdo para o navegador
    Response.Write(writer.ToString().Replace("\r\n", "<br/>"));
}Code language: C# (cs)

Esse código faz a leitura do arquivo HTML de template, cria variáveis e substitui os marcadores presentes no HTML pelos valores correspondentes.

1. Instanciar VelocityEngine: Objeto de motor independente, diferente da chamada global estática Velocity.Init(). Suporta múltiplas configurações separadas.
2. Inicialização e configuração do motor

• RESOURCE_LOADER=file: Define que os templates são carregados de arquivos locais;
• FILE_RESOURCE_LOADER_PATH: Configura o diretório base para busca de templates;
• ve.Init(pros): Carrega as configurações e conclui a inicialização.

3. Carregar template com GetTemplate(): Lê o arquivo themes/default/register.htm com base no diretório raiz configurado.
4. Contexto de dados VelocityContext: Com context.Put(chave, valor) enviamos variáveis C# para o template. Dentro do arquivo htm acessamos elas usando $websiteName e $domainName.
5. Renderização Merge no template: template.Merge(contexto, fluxoSaída) insere as variáveis no template e cria uma string HTML completa. Usamos StringWriter para receber o texto renderizado.
6. Saída via Response: Envia o HTML final ao navegador. Replace("\r\n","<br/>") converte quebras de linha do código fonte em tags HTML de quebra de linha.

Template htm

Edite o arquivo register.htm dentro do diretório de temas

<!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>
    Site: $websiteName <br />
    Domínio: $domainName
</body>
</html>Code language: HTML, XML (xml)

As duas marcações com $xxxxxxx são os espaços reservados das variáveis criadas no Page_Load. Elas serão substituídas pelos valores definidos durante a renderização.

1. Identificador de variável $nomeDaVariavel $websiteName e $domainName seguem a sintaxe VTL do NVelocity. Os valores são definidos no código com context.Put("websiteName", "FoxDevelop") e o motor faz a substituição automática na renderização:

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

Resultado da execução

Site: FoxDevelop
Domínio: foxdevelop.comCode language: HTTP (http)

Apresentação do NVelocity