Einführung in NVelocity

Eine Template-Engine für die .NET-Plattform, die als .NET-Port der Java-Velocity-Implementierung entstanden ist.

Vorstellung

Weit verbreitet in ASP.NET-Projekten;
Für ASP.NET MVC steht standardmäßig die Razor-Template-Engine zur Verfügung;

Viele Entwickler setzen auf NVelocity, wenn herkömmliche .aspx-Projekte um das MVC-Muster erweitert werden sollen.

NVelocity wird nicht mehr weiterentwickelt und kommt nur noch in alten .NET Framework-Projekten zum Einsatz. Bei neuen Projekten empfehlen sich moderne Template-Engines wie Razor oder Handlebars.NET.

Zuordnung der Versionen zum .NET Framework

.NET Framework-Version	NVelocity-Version
.NET 4.0	1.0 (neueste offizielle Version)
.NET 2.0	0.5
.NET 1.0	0.48

Velocity ist eine altbewährte Template-Engine für Java mit einer kompakten Syntax, die # und $ als Template-Markierungen nutzt. NVelocity übernimmt diese Syntax vollständig;

Download

Die letzte offizielle Aktualisierung erfolgte im Jahr 2018, die neueste Version ist 1.2.0

Sie können den Quellcode unter folgender Adresse herunterladen

Das Projekt ist quelloffen und wird auf GitHub gehostet castleproject/NVelocity: Castle’s NVelocity

Beim offiziellen Download handelt es sich nicht um vorkompilierte DLL-Dateien. Sie können den Quellcode herunterladen und selbst kompilieren oder das Projekt direkt zur Projektmappe Ihrer Anwendung hinzufügen.

Öffnen Sie die SLN-Datei mit Visual Studio

Die letzte Version basiert auf .NET Core 2.1. Es empfiehlt sich, das Projekt auf .NET 4.8 zu aktualisieren

Nach dem Kompilieren finden Sie die DLL-Dateien im Ausgabeverzeichnis

Anschließend können Sie die Datei in Ihr anderes ASP.NET Web-Projekt einbinden. Fügen Sie die NVelocity.dll Ihrem Web-Projekt hinzu.

Einbindung im Projekt

Fügen Sie dem Projekt die Assembly NVelocity.dll hinzu
Hauptvorteil: Mit dieser Template-Engine lassen sich unkompliziert mehrere Webseitenvorlagen (Designwechsel) realisieren

Legen Sie im Stammverzeichnis der Webseite einen Ordner namens Themes als Hauptverzeichnis für alle Vorlagen an
Erstellen Sie innerhalb von Themes mehrere Unterordner für einzelne Designs, zum Beispiel:

Erstellen Sie den Ordner Themes im Webstammverzeichnis als Designverzeichnis

Designverzeichnis

Erstellen Sie danach einen Ordner default für die Standardvorlage
Später können Sie weitere Vorlagenordner wie Themes/blue oder Themes/dark hinzufügen

Webstammverzeichnis
└── Themes
    ├── default      # Dateien des Standarddesigns
    ├── dark         # Dateien des dunklen Designs
    └── blue         # Dateien des blauen DesignsCode-Sprache: PHP (php)

Zur Laufzeit wird der aktive Designname aus der Konfiguration ausgelesen, woraufhin NVelocity die Vorlagen aus dem passenden Designordner lädt.
Der Wechsel der Vorlage funktioniert durch die Änderung des konfigurierten Pfades zum Designordner – der eigentliche Geschäftslogikcode bleibt unverändert.
Geeignet für alte ASP.NET WebForm-(aspx)-Projekte zur Umsetzung eines Designwechsels für die Benutzeroberfläche.

aspx

Legen Sie eine neue ASPX-Seite im Webstammverzeichnis an: Register.aspx als Beispiel für den Zugriff.

Erstellen Sie im Ordner Themes/default eine Vorlagendatei namens register.htm. Diese Datei dient als NVelocity-Vorlage und enthält HTML-Code sowie Velocity-Syntax.

Öffnen Sie Register.aspx, behalten Sie ausschließlich die Seitenanweisung bei und entfernen Sie allen übrigen HTML-Inhalt:

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

Die ASPX-Datei übernimmt keine Darstellung des Seiteninhalts mehr, sondern fungiert nur als Einstiegspunkt des Controllers. Der Code-Behind lädt über NVelocity die Vorlage register.htm und gibt den generierten Inhalt aus.

Webstammverzeichnis
├─ Register.aspx          # Zugriffspunkt
├─ Register.aspx.cs       # Logik im Code-Behind
└─ Themes
    └─ default
        └─ register.htm   # NVelocity-VorlageCode-Sprache: CSS (css)

Anschließend schreiben Sie den Code in Register.aspx.cs, um die Vorlage register.htm des aktuellen Designs zu laden, das Datenmodell zu übergeben und abschließend HTML zu generieren.

Zum Wechsel des Designs muss nur der Pfad zum Designordner angepasst werden, damit die Datei register.htm aus dem entsprechenden Ordner geladen wird.

aspx.cs

Öffnen Sie die Code-Behind-Datei Register.aspx.cs. Implementieren Sie die Rendering-Logik für NVelocity innerhalb der Methode Page_Load. Die Vorlage wird beim Laden der Seite verarbeitet und ausgegeben.

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)
        {
            // Hier Code zum Laden der Vorlage und Rendern der Seite mit NVelocity einfügen
        }
    }
}Code-Sprache: C# (cs)

Fügen Sie folgenden Code in Page_Load ein

protected void Page_Load(object sender, EventArgs e)
{
    //Schritt 1: Instanz der VelocityEngine erstellen
    VelocityEngine ve = new VelocityEngine();

    //Schritt 2: Engine-Konfiguration initialisieren
    ExtendedProperties pros = new ExtendedProperties();
    pros.AddProperty(RuntimeConstants.RESOURCE_LOADER, "file"); // Vorlagen aus Dateien laden
    pros.AddProperty(RuntimeConstants.FILE_RESOURCE_LOADER_PATH, Server.MapPath(@"")); // Stammverzeichnis der Vorlagen
    ve.Init(pros); // Engine mit Konfiguration initialisieren

    //Schritt 3: Vorlagendatei einlesen
    Template template = ve.GetTemplate("themes/default/register.htm");

    //Schritt 4: Kontext erstellen und Variablen an die Vorlage übergeben
    IContext context = new VelocityContext();
    context.Put("websiteName", "FoxDevelop");
    context.Put("domainName", "foxdevelop.com");

    //Schritt 5: Vorlage mit Daten zusammenführen und HTML rendern
    StringWriter writer = new StringWriter();
    template.Merge(context, writer); // Das Ergebnis der Darstellung wird im Writer gespeichert

    //Schritt 6: Seite ausgeben
    Response.Write(writer.ToString().Replace("\r\n", "<br/>"));
}Code-Sprache: C# (cs)

Dieser Code liest die HTML-Vorlagendatei, erstellt Variablen und ersetzt die Platzhalter innerhalb der HTML-Datei durch die zugewiesenen Werte.

1. Instanziierung VelocityEngine: Ein eigenständiges Engine-Objekt, abweichend vom globalen statischen Aufruf Velocity.Init(). Es unterstützt separate unabhängige Konfigurationen.
2. Initialisierung und Konfiguration der Engine

• RESOURCE_LOADER=file: Legt fest, dass Vorlagen aus lokalen Dateien geladen werden;
• FILE_RESOURCE_LOADER_PATH: Legt das Stammverzeichnis für die Vorlagensuche fest;
• ve.Init(pros): Lädt die Konfiguration und schließt die Initialisierung ab.

3. Laden der Vorlage mit GetTemplate(): Liest die Datei themes/default/register.htm ausgehend vom konfigurierten Stammverzeichnis.
4. Datenkontext VelocityContext: Mit context.Put(Schlüssel, Wert) werden C#-Variablen an die Vorlage übergeben. Innerhalb der HTM-Datei greifen Sie mit $websiteName und $domainName auf diese Werte zu.
5. Vorlagen-Rendering per Merge: Mit template.Merge(Kontext, Ausgabestream) werden Variablen in die Vorlage eingefügt und ein vollständiger HTML-String erzeugt. Der generierte Text wird über einen StringWriter aufgefangen.
6. Ausgabe mit Response: Der fertige HTML-Code wird an den Browser gesendet. Replace("\r\n","<br/>") wandelt Zeilenumbrüche des Quellcodes in HTML-Zeilenumbruch-Tags um.

htm-Vorlage

Bearbeiten Sie die Datei register.htm im Designordner

<!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>
    Webseite: $websiteName <br />
    Domain: $domainName
</body>
</html>Code-Sprache: HTML, XML (xml)

Die beiden Ausdrücke mit $xxxxxxx sind Platzhalter für die im Page_Load erstellten Variablen. Während der Darstellung werden sie automatisch durch die entsprechenden Werte ersetzt.

1. Variablenkennzeichnung $Variablenname $websiteName und $domainName sind VTL-Syntax von NVelocity. Im Programmcode werden sie mit context.Put("websiteName", "FoxDevelop") belegt, die Engine ersetzt diese Markierungen beim Rendering:

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

Ergebnis bei Ausführung

Webseite: FoxDevelop
Domain: foxdevelop.comCode-Sprache: HTTP (http)

Einführung in NVelocity