NVelocity 概要 - NVelocity チュートリアル

.NETプラットフォーム向けテンプレートエンジンで、JavaプラットフォームのVelocityを.NETへ移植したものです。

概要

ASP.NETプロジェクトで広く利用されています；
ASP.NET MVCにはRazorテンプレートが標準搭載；

従来の .aspx ページプロジェクトにMVCモデルを導入したい場合、多くの開発者がNVelocityを選択します。

NVelocityはすでに保守が停止されており、古い.NET Frameworkのレガシープロジェクトでのみ使用します。新規プロジェクトではRazorやHandlebars.NETなど最新のテンプレートエンジンを優先してください。

.NET Frameworkとバージョンの対応一覧

.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ファイルが生成されます

作成したNVelocity.dllをほかのASP.NET Webプロジェクトに参照追加します。

プロジェクト導入

プロジェクトにアセンブリを参照：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 を読み込んでHTMLを出力します。

サイトルート
├─ 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テンプレートを読み込み変数を作成し、テンプレート内のプレースホルダーを置換する処理です

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>

上記の$xxxxxxxはPage_Loadで定義した変数のプレースホルダーで、描画時に対応する値に置き換わります。

変数記法 $変数名 $websiteName、$domainName はNVelocity(VTL)の変数文法です。コード内 context.Put("websiteName", "FoxDevelop") で値を設定すると、描画時に自動的に置換されます：

$websiteName → FoxDevelop
$domainName → foxdevelop.com

実行結果

サイト：FoxDevelop
ドメイン：foxdevelop.com

NVelocity 概要

概要