NVelocity 개요 - NVelocity 튜토리얼

.NET 플랫폼 템플릿 엔진으로, Java 플랫폼의 Velocity를 .NET으로 포팅한 버전입니다.

소개

ASP.NET 프로젝트에서 널리 사용됩니다;
ASP.NET MVC에는 Razor 템플릿이 기본으로 탑재되어 있습니다.

기존 .aspx 페이지 기반 프로젝트에 MVC 패턴을 적용하고 싶은 개발자들이 많이 NVelocity를 선택했습니다.

NVelocity는 이미 유지보수가 중단되었으며 오래된 .NET Framework 레거시 프로젝트에서만 사용합니다. 신규 프로젝트는 Razor, Handlebars.NET 등 현대적인 템플릿 엔진을 우선 사용하는 것이 좋습니다.

.NET Framework 버전별 호환 NVelocity 버전

.NET Framework 버전	NVelocity 버전
.NET 4.0	1.0 (공식 최신판)
.NET 2.0	0.5
.NET 1.0	0.48

Velocity는 역사가 긴 Java 템플릿 엔진으로 구문이 간결하며 #, $ 기호를 템플릿 마커로 활용합니다. NVelocity는 이 구문을 완전히 포팅했습니다.

다운로드

공식 마지막 업데이트는 2018년이며 최신 버전은 1.2.0입니다.

아래 주소에서 소스 코드를 내려받을 수 있습니다.

오픈소스 프로젝트로 GitHub에서 관리되고 있습니다 castleproject/NVelocity: Castle’s NVelocity

공식 저장소에는 컴파일된 dll 파일이 없으므로 소스를 다운로드한 뒤 직접 빌드하거나 프로젝트 자체를 솔루션에 포함시켜 사용하면 됩니다.

Visual Studio로 sln 파일을 엽니다.

마지막 릴리즈 버전은 .NET Core 2.1 기반이므로 필요하다면 .NET 4.8로 업그레이드하는 것을 권장합니다.

빌드가 완료되면 출력 폴더에서 dll 파일을 확인할 수 있습니다.

그러고 나서 다른 ASP.NET 웹 프로젝트에 참조를 추가하면 됩니다. 방금 생성한 NVelocity.dll을 웹 프로젝트에 포함시키세요.

프로젝트 적용 방식

프로젝트에 어셈블리 참조 추가: NVelocity.dll
주요 장점: 이 템플릿 엔진을 활용하면 웹사이트의 테마 전환 기능을 간편하게 구현할 수 있습니다.

웹 사이트 루트 경로에 Themes 폴더를 생성해 모든 템플릿을 보관하는 기본 디렉터리로 지정합니다.
Themes 안에 여러 테마 폴더를 만들 수 있습니다. 예시는 다음과 같습니다.

사이트 루트에 Themes 폴더를 만들어 테마 저장 경로로 사용합니다.

테마 디렉터리 구조

default 폴더를 만들어 기본 템플릿으로 지정합니다.
필요에 따라 Themes/blue, Themes/dark 등 여러 템플릿 세트를 추가할 수 있습니다.

사이트 루트
└── Themes
    ├── default      # 기본 테마 템플릿 파일
    ├── dark         # 어두운 테마 템플릿 파일
    └── blue         # 파란색 테마 템플릿 파일Code language: PHP (php)

실행 시 설정 파일에서 활성화된 테마 이름을 읽고 NVelocity가 해당 테마 폴더 안의 템플릿을 불러옵니다.
테마 전환의 원리: 설정값을 수정해 다른 테마 폴더를 가리키도록 할 뿐 비즈니스 로직 코드는 수정할 필요가 없습니다.
구식 ASP.NET WebForm(.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" %>Code language: HTML, XML (xml)

aspx 파일 자체는 페이지 렌더링에 관여하지 않고 컨트롤러 진입점 역할만 수행합니다. 백엔드 코드가 NVelocity를 호출해 register.htm 템플릿을 불러와 최종 내용을 출력합니다.

사이트 루트
├─ Register.aspx          # 접속 진입 페이지
├─ Register.aspx.cs       # 서버 로직 코드
└─ Themes
    └─ default
        └─ register.htm   # NVelocity 템플릿Code language: CSS (css)

이후 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 템플릿 로딩 및 렌더링 코드를 작성합니다
        }
    }
}Code language: C# (cs)

Page_Load 안에 아래 코드를 추가합니다.

protected void Page_Load(object sender, EventArgs e)
{
    //1단계. VelocityEngine 인스턴스 생성
    VelocityEngine ve = new VelocityEngine();

    //2단계. 엔진 설정 초기화
    ExtendedProperties pros = new ExtendedProperties();
    pros.AddProperty(RuntimeConstants.RESOURCE_LOADER, "file"); // 파일 기반 템플릿 로드 방식
    pros.AddProperty(RuntimeConstants.FILE_RESOURCE_LOADER_PATH, Server.MapPath(@"")); // 템플릿 기본 경로
    ve.Init(pros); // 설정을 적용하고 엔진 초기화

    //3단계. 템플릿 파일 불러오기
    Template template = ve.GetTemplate("themes/default/register.htm");

    //4단계. 컨텍스트 생성, 템플릿에 변수 전달
    IContext context = new VelocityContext();
    context.Put("websiteName", "FoxDevelop");
    context.Put("domainName", "foxdevelop.com");

    //5단계. 템플릿과 데이터를 결합하여 HTML 생성
    StringWriter writer = new StringWriter();
    template.Merge(context, writer); // 렌더링 결과를 writer에 저장

    //6단계. 최종 페이지 출력
    Response.Write(writer.ToString().Replace("\r\n", "<br/>"));
}Code language: C# (cs)

이 코드는 템플릿 html 파일을 읽고 변수를 생성한 뒤 html 내의 자리 표시자를 실제 값으로 교체하는 과정입니다.

VelocityEngine 인스턴스 생성 전역 정적 Velocity.Init()와 달리 독립적인 엔진 객체로 여러 개의 개별 설정을 운용할 수 있습니다.
엔진 초기화 및 환경 설정

RESOURCE_LOADER=file : 템플릿을 로컬 파일로 불러오도록 지정;
FILE_RESOURCE_LOADER_PATH : 템플릿을 탐색할 기본 경로 설정;
ve.Init(pros) : 설정을 불러와 초기화를 완료.

템플릿 불러오기 GetTemplate() 설정된 기본 경로를 기준으로 themes/default/register.htm 템플릿을 읽어옵니다.
VelocityContext 데이터 컨텍스트context.Put(키, 값)으로 C# 변수를 템플릿에 전달하며, htm 파일 안에서는 $websiteName、$domainName으로 값을 호출합니다.
템플릿 Merge 렌더링template.Merge(컨텍스트, 출력스트림)으로 변수를 템플릿에 채워 완성된 HTML 문자열을 만들며, StringWriter로 렌더링 결과를 받습니다.
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>Code language: HTML, XML (xml)

위의 $xxxxxxx 두 개는 Page_Load에서 선언한 변수의 자리 표시자이며 렌더링 과정에서 실제 값으로 교체됩니다.

변수 표기 $변수명 $websiteName、$domainName는 NVelocity(VTL) 변수 문법입니다. 코드에서 context.Put("websiteName", "FoxDevelop")로 값을 할당하면 렌더링 시 엔진이 자동으로 치환합니다.

$websiteName → FoxDevelop
$domainName → foxdevelop.com

실행 결과 예시

사이트：FoxDevelop
도메인：foxdevelop.comCode language: CSS (css)

NVelocity 개요

소개