feat: Add Razor support as an optional extension to TemplateEngine.Core (#12)

jupre003 · web-flow · commit 8248ee3d3fda · 2025-12-06T16:19:59.000+01:00
* Add Razor support as an optional extension to TemplateEngine.Core

- Introduced MbSoftLab.TemplateEngine.Core.Razor project with RazorTemplateEngine implementation.
- Updated project references in existing projects to include the new Razor extension.
- Removed Razor dependencies from core classes and adjusted documentation to reflect optional usage.
- Enhanced README and other documentation files to guide users on installing and using the Razor extension.

* Disable package cache and specify solution file for restore, build, and test steps in CI workflows
diff --git a/.github/workflows/BuildFromDevelop.yml b/.github/workflows/BuildFromDevelop.yml
@@ -20,10 +20,11 @@ jobs:
       uses: actions/setup-dotnet@v4
       with:
         dotnet-version: 8.0.x
-        cache: true
+        # Disable package cache to avoid lock file requirement
+        cache: false
     - name: Restore
-      run: dotnet restore
+      run: dotnet restore MbSoftLab.TemplateEngine.Core.sln
     - name: Build
-      run: dotnet build --configuration Release --no-restore
+      run: dotnet build MbSoftLab.TemplateEngine.Core.sln --configuration Release --no-restore
     - name: Test
-      run: dotnet test --no-restore --verbosity normal
+      run: dotnet test MbSoftLab.TemplateEngine.Core.sln --no-restore --verbosity normal
diff --git a/.github/workflows/BuildFromMaster.yml b/.github/workflows/BuildFromMaster.yml
@@ -20,10 +20,10 @@ jobs:
       uses: actions/setup-dotnet@v4
       with:
         dotnet-version: 8.0.x
-        cache: true
+        cache: false
     - name: Restore
-      run: dotnet restore
+      run: dotnet restore MbSoftLab.TemplateEngine.Core.sln
     - name: Build
-      run: dotnet build --configuration Release --no-restore
+      run: dotnet build MbSoftLab.TemplateEngine.Core.sln --configuration Release --no-restore
     - name: Test
-      run: dotnet test --no-restore --verbosity normal
+      run: dotnet test MbSoftLab.TemplateEngine.Core.sln --no-restore --verbosity normal
diff --git a/.github/workflows/Release.yml b/.github/workflows/Release.yml
@@ -14,11 +14,11 @@ jobs:
       uses: actions/setup-dotnet@v4
       with:
         dotnet-version: 8.0.x
-        cache: true
+        cache: false
     - name: Restore
-      run: dotnet restore
+      run: dotnet restore MbSoftLab.TemplateEngine.Core.sln
     - name: Build
-      run: dotnet build --configuration Release --no-restore
+      run: dotnet build MbSoftLab.TemplateEngine.Core.sln --configuration Release --no-restore
     - name: Pack
       run: dotnet pack MbSoftLab.TemplateEngine.Core/MbSoftLab.TemplateEngine.Core.csproj --configuration Release --no-restore -o ./artifacts
     - name: Push to NuGet
diff --git a/MbSoftLab.TemplateEngine.Core.Razor/Documentation.xml b/MbSoftLab.TemplateEngine.Core.Razor/Documentation.xml
diff --git a/MbSoftLab.TemplateEngine.Core.Razor/MbSoftLab.TemplateEngine.Core.Razor.csproj b/MbSoftLab.TemplateEngine.Core.Razor/MbSoftLab.TemplateEngine.Core.Razor.csproj
@@ -0,0 +1,37 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <AssemblyVersion>1.1.0.0</AssemblyVersion>
+    <FileVersion>1.1.0.0</FileVersion>
+    <Version>1.1.0</Version>
+    <PackageVersion>1.1.0-preview</PackageVersion>
+    <Description>Razor-enabled extension for MbSoftLab.TemplateEngine.Core providing RazorTemplateEngine.</Description>
+    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
+    <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
+    <PackageTags>Template Engine Razor RazorEngineCore Html</PackageTags>
+    <PackageId>MbSoftLab.TemplateEngine.Core.Razor</PackageId>
+    <Company>MbSoftLab</Company>
+    <Authors>MbSoftLab</Authors>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <Copyright>© 2021 - 2025 MbSoftLab</Copyright>
+    <PackageIcon>MbSoftLabLogo.png</PackageIcon>
+    <PackageProjectUrl>https://github.com/mbsoftlab/MbSoftLab.TemplateEngine.Core</PackageProjectUrl>
+    <RepositoryUrl>https://github.com/mbsoftlab/MbSoftLab.TemplateEngine.Core</RepositoryUrl>
+    <RepositoryType>Git</RepositoryType>
+    <DocumentationFile>Documentation.xml</DocumentationFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="RazorEngineCore" Version="2020.10.1" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../MbSoftLab.TemplateEngine.Core/MbSoftLab.TemplateEngine.Core.csproj" />
+    <None Include="../MbSoftLab.TemplateEngine.Core/MbSoftLabLogo.png">
+      <Pack>True</Pack>
+      <PackagePath></PackagePath>
+    </None>
+  </ItemGroup>
+
+</Project>
diff --git a/MbSoftLab.TemplateEngine.Core.Razor/README.md b/MbSoftLab.TemplateEngine.Core.Razor/README.md
@@ -0,0 +1,32 @@
+# MbSoftLab.TemplateEngine.Core.Razor
+
+Optionales Erweiterungspaket für MbSoftLab.TemplateEngine.Core, das die `RazorTemplateEngine<T>` bereitstellt.
+
+## Installation
+
+```bash
+# .NET CLI
+dotnet add package MbSoftLab.TemplateEngine.Core.Razor
+
+# Oder Projekt-Referenz (Monorepo)
+dotnet add <IhrProjekt>.csproj reference MbSoftLab.TemplateEngine.Core.Razor/MbSoftLab.TemplateEngine.Core.Razor.csproj
+```
+
+## Verwendung
+
+```csharp
+using MbSoftLab.TemplateEngine.Core;
+
+public class Person : TemplateDataModel<Person>
+{
+    public string FirstName { get; set; }
+}
+
+var person = new Person { FirstName = "Anna" };
+
+var engine = new RazorTemplateEngine<Person>();
+engine.TemplateString = "<h1>@Model.FirstName</h1>";
+string html = engine.CreateStringFromTemplate(person);
+```
+
+Hinweis: `TemplateDataModel<T>` ist nun eine einfache Klasse im Core (ohne Razor-Basis). Die Razor-Engine erhält intern `Model` als Datenmodell (`template.Run(TemplateDataModel?.Model)`).
diff --git a/MbSoftLab.TemplateEngine.Core.Razor/RazorTemplateEngine.cs b/MbSoftLab.TemplateEngine.Core.Razor/RazorTemplateEngine.cs
@@ -1,4 +1,4 @@
-﻿using RazorEngineCore;
+using RazorEngineCore;
 using System;
 using System.ComponentModel;
 using System.Globalization;
@@ -86,4 +86,4 @@ public string CreateStringFromTemplate(T templateDataModel, string csHtmlTemplat
         TemplateString = csHtmlTemplate;
         return CreateStringFromTemplate();
     }
-}
+}
diff --git a/MbSoftLab.TemplateEngine.Core.Tests/MbSoftLab.TemplateEngine.Core.Tests.csproj b/MbSoftLab.TemplateEngine.Core.Tests/MbSoftLab.TemplateEngine.Core.Tests.csproj
@@ -14,6 +14,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\MbSoftLab.TemplateEngine.Core\MbSoftLab.TemplateEngine.Core.csproj" />
+    <ProjectReference Include="..\MbSoftLab.TemplateEngine.Core.Razor\MbSoftLab.TemplateEngine.Core.Razor.csproj" />
   </ItemGroup>
 
   <ItemGroup>
diff --git a/MbSoftLab.TemplateEngine.Core.sln b/MbSoftLab.TemplateEngine.Core.sln
@@ -7,6 +7,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MbSoftLab.TemplateEngine.Co
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MbSoftLab.TemplateEngine.Core", "MbSoftLab.TemplateEngine.Core\MbSoftLab.TemplateEngine.Core.csproj", "{CA5BFFAC-ADA4-478B-8B13-B3AF81FE4A05}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MbSoftLab.TemplateEngine.Core.Razor", "MbSoftLab.TemplateEngine.Core.Razor\MbSoftLab.TemplateEngine.Core.Razor.csproj", "{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MbSoftlab.TemplateEngine.Core.Demo", "MbSoftlab.TemplateEngine.Core.Demo\MbSoftlab.TemplateEngine.Core.Demo.csproj", "{159ED0CF-FB05-4F88-A442-90890814E6A8}"
 EndProject
 Global
@@ -63,6 +65,26 @@ Global
 		{CA5BFFAC-ADA4-478B-8B13-B3AF81FE4A05}.Release|x64.Build.0 = Release|Any CPU
 		{CA5BFFAC-ADA4-478B-8B13-B3AF81FE4A05}.Release|x86.ActiveCfg = Release|Any CPU
 		{CA5BFFAC-ADA4-478B-8B13-B3AF81FE4A05}.Release|x86.Build.0 = Release|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Debug|ARM.ActiveCfg = Debug|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Debug|ARM.Build.0 = Debug|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Debug|ARM64.ActiveCfg = Debug|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Debug|ARM64.Build.0 = Debug|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Debug|x64.Build.0 = Debug|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Debug|x86.Build.0 = Debug|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Release|ARM.ActiveCfg = Release|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Release|ARM.Build.0 = Release|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Release|ARM64.ActiveCfg = Release|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Release|ARM64.Build.0 = Release|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Release|x64.ActiveCfg = Release|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Release|x64.Build.0 = Release|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Release|x86.ActiveCfg = Release|Any CPU
+		{A9E18D5A-4B79-4C49-BB3A-1E8D0B0D7F1E}.Release|x86.Build.0 = Release|Any CPU
 		{159ED0CF-FB05-4F88-A442-90890814E6A8}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{159ED0CF-FB05-4F88-A442-90890814E6A8}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{159ED0CF-FB05-4F88-A442-90890814E6A8}.Debug|ARM.ActiveCfg = Debug|Any CPU
diff --git a/MbSoftLab.TemplateEngine.Core/MbSoftLab.TemplateEngine.Core.csproj b/MbSoftLab.TemplateEngine.Core/MbSoftLab.TemplateEngine.Core.csproj
@@ -31,7 +31,6 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="RazorEngineCore" Version="2020.10.1" />
   </ItemGroup>
 
 </Project>
diff --git a/MbSoftLab.TemplateEngine.Core/TemplateDataModel.cs b/MbSoftLab.TemplateEngine.Core/TemplateDataModel.cs
@@ -1,12 +1,11 @@
-﻿using RazorEngineCore;
-using System.Text.Json.Serialization;
+﻿using System.Text.Json.Serialization;
 
 namespace MbSoftLab.TemplateEngine.Core;
 
-public class TemplateDataModel<T> : RazorEngineTemplateBase
+public class TemplateDataModel<T>
 {
     [JsonIgnore]
-    public new T Model { get; set; }
+    public T Model { get; set; }
     
     public string GetNullstringValue()
     {
diff --git a/MbSoftlab.TemplateEngine.Core.Demo/MbSoftlab.TemplateEngine.Core.Demo.csproj b/MbSoftlab.TemplateEngine.Core.Demo/MbSoftlab.TemplateEngine.Core.Demo.csproj
@@ -11,6 +11,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\MbSoftLab.TemplateEngine.Core\MbSoftLab.TemplateEngine.Core.csproj" />
+    <ProjectReference Include="..\MbSoftLab.TemplateEngine.Core.Razor\MbSoftLab.TemplateEngine.Core.Razor.csproj" />
   </ItemGroup>
 
   <ItemGroup>
diff --git a/README.md b/README.md
@@ -30,7 +30,13 @@ string result = engine.CreateStringFromTemplate();
 // Output: "Hallo Max Mustermann!"
 ```
 
-### Razor-Template-Beispiel
+### Razor-Template-Beispiel (optional)
+
+Installieren Sie zusätzlich das optionale Paket:
+
+```bash
+dotnet add package MbSoftLab.TemplateEngine.Core.Razor
+```
 
 ```csharp
 public class Person : TemplateDataModel<Person>
@@ -44,6 +50,7 @@ var person = new Person {
     Tags = new List<string> { "Developer", "Designer" } 
 };
 
+// Razor steht erst nach Installation von MbSoftLab.TemplateEngine.Core.Razor zur Verfügung
 var engine = new RazorTemplateEngine<Person>();
 engine.TemplateString = @"
 <h1>@Model.FirstName</h1>
diff --git a/docs/README.md b/docs/README.md
@@ -11,8 +11,8 @@
 Willkommen zur offiziellen Dokumentation der **MbSoftLab.TemplateEngine.Core** Bibliothek - einer leistungsstarken und flexiblen Template-Engine für .NET 8.0.
 
 Diese Bibliothek bietet zwei verschiedene Ansätze zur Template-Verarbeitung:
-- **TemplateEngine<T>** - Schnell und einfach für String-basierte Templates
-- **RazorTemplateEngine<T>** - Mächtig und flexibel für komplexe HTML-Templates mit Razor-Syntax
+- **TemplateEngine<T>** – Schnell und einfach für String-basierte Templates
+- **RazorTemplateEngine<T>** – Mächtig und flexibel für komplexe HTML-Templates mit Razor-Syntax (optional, verfügbar nach Installation von `MbSoftLab.TemplateEngine.Core.Razor`)
 
 ---
 
@@ -74,6 +74,12 @@ Install-Package MbSoftLab.TemplateEngine.Core
 dotnet add package MbSoftLab.TemplateEngine.Core
 ```
 
+Optional: Razor-Unterstützung installieren
+
+```bash
+dotnet add package MbSoftLab.TemplateEngine.Core.Razor
+```
+
 ### Erstes Beispiel
 
 ```csharp
@@ -121,10 +127,11 @@ var engine = new TemplateEngine<Customer>(customer, "Hallo ${Name}!");
 
 → Siehe [Einfache Beispiele](/docs/examples/#einfache-beispiele)
 
-### 2. Komplexe HTML-Templates
+### 2. Komplexe HTML-Templates (optional)
 Für dynamische HTML-Generierung mit Schleifen, Bedingungen und verschachtelten Objekten.
 
 ```csharp
+// Razor steht erst nach Installation von MbSoftLab.TemplateEngine.Core.Razor zur Verfügung
 var engine = new RazorTemplateEngine<Person>();
 engine.TemplateString = "@foreach(var item in Model.Items) { <li>@item</li> }";
 ```
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -20,7 +20,7 @@
 MbSoftLab.TemplateEngine.Core ist eine .NET 8.0 Bibliothek, die zwei verschiedene Template-Engine-Implementierungen bereitstellt:
 
 1. **TemplateEngine<T>** - Einfacher, schneller String-basierter Template-Engine
-2. **RazorTemplateEngine<T>** - Komplexer Razor-basierter Template-Engine für HTML
+2. **RazorTemplateEngine<T>** - Komplexer Razor-basierter Template-Engine für HTML (bereitgestellt durch das optionale Paket `MbSoftLab.TemplateEngine.Core.Razor`)
 
 Beide implementieren das gemeinsame `ITemplateEngine<T>` Interface.
 
@@ -39,7 +39,7 @@ graph TB
     subgraph "MbSoftLab.TemplateEngine.Core"
         B[ITemplateEngine&lt;T&gt;]
         C[TemplateEngine&lt;T&gt;]
-        D[RazorTemplateEngine&lt;T&gt;]
+        D[[RazorTemplateEngine&lt;T&gt;]]
         E[TemplateDataModelProcessor]
         F[PlaceholderValueReplacer]
         G[ReplacementActionCollection]
@@ -48,7 +48,8 @@ graph TB
         J[TemplateEngineExtensions]
     end
     
-    subgraph "External Dependencies"
+    subgraph "MbSoftLab.TemplateEngine.Core.Razor (optional)"
+        D
         K[RazorEngineCore]
     end
     
@@ -125,7 +126,7 @@ classDiagram
     ITemplateEngine~T~ <|.. TemplateEngine~T~
     ITemplateEngine~T~ <|.. RazorTemplateEngine~T~
     ITemplateEngineConfig~T~ <|.. TemplateEngineConfig~T~
-    RazorEngineTemplateBase <|-- TemplateDataModel~T~
+    %% Core ist von Razor entkoppelt; kein RazorEngineTemplateBase
     TemplateEngine~T~ --> ITemplateEngineConfig~T~
     RazorTemplateEngine~T~ --> ITemplateEngineConfig~T~
     RazorTemplateEngine~T~ --> TemplateDataModel~T~
diff --git a/docs/development.md b/docs/development.md
@@ -66,24 +66,23 @@ MbSoftLab.TemplateEngine.Core/
 │       ├── BuildFromDevelop.yml
 │       ├── BuildFromMaster.yml
 │       └── Release.yml
-├── MbSoftLab.TemplateEngine.Core/          # Haupt-Bibliothek
+├── MbSoftLab.TemplateEngine.Core/          # Haupt-Bibliothek (ohne Razor-Abhängigkeit)
 │   ├── ITemplateEngine.cs                   # Interface für Template-Engines
 │   ├── TemplateEngine.cs                    # Simple Template-Engine
-│   ├── RazorTemplateEngine.cs               # Razor-basierte Engine
-│   ├── TemplateDataModel.cs                 # Basis-Klasse für Razor-Models
+│   ├── TemplateDataModel.cs                 # Datenmodell (ohne Razor-Basisklasse)
 │   ├── TemplateDataModelProcessor.cs        # Property/Methoden-Verarbeitung
 │   ├── PlaceholderValueRaplacer.cs          # Platzhalter-Ersetzung
 │   ├── ReplacementActionCollection.cs       # Typ-spezifische Actions
 │   ├── ITemplateEngineConfig.cs             # Konfigurations-Interface
 │   ├── TemplateEngineConfig.cs              # Konfigurations-Implementierung
 │   ├── TemplateEngineExtensions.cs          # Erweiterungsmethoden
 │   └── MbSoftLab.TemplateEngine.Core.csproj # Projekt-Datei
-├── MbSoftLab.TemplateEngine.Core.Tests/    # Unit-Tests
+├── MbSoftLab.TemplateEngine.Core.Tests/    # Unit-Tests (referenzieren bei Bedarf Razor-Projekt)
 │   ├── TemplateEngineUnitTest.cs
 │   ├── RazorTemplateEngineUnitTest.cs
 │   ├── TemplateDataModelDummy.cs            # Test-Fixtures
 │   └── *.cs                                 # Weitere Test-Dateien
-├── MbSoftlab.TemplateEngine.Core.Demo/     # Demo-Anwendung
+├── MbSoftlab.TemplateEngine.Core.Demo/     # Demo-Anwendung (Razor-Demo referenziert Razor-Projekt)
 │   ├── Program.cs
 │   ├── Person.cs
 │   ├── Address.cs
@@ -97,7 +96,10 @@ MbSoftLab.TemplateEngine.Core/
 ├── CHANGELOG.md                             # Versions-Historie
 ├── RELEASENOTES.md                          # Release-Informationen
 ├── README.md                                # Haupt-Dokumentation
-└── MbSoftLab.TemplateEngine.Core.sln       # Solution-Datei
+├── MbSoftLab.TemplateEngine.Core.Razor/    # Optionales Razor-Erweiterungsprojekt
+│   ├── RazorTemplateEngine.cs               # Razor-basierte Engine
+│   └── MbSoftLab.TemplateEngine.Core.Razor.csproj
+└── MbSoftLab.TemplateEngine.Core.sln       # Solution-Datei (enthält beide Projekte)
 ```
 
 ---
@@ -119,6 +121,20 @@ dotnet pack --configuration Release
 
 **Output:** Das NuGet-Package wird in `bin/Release/` erstellt.
 
+### Razor-Erweiterung (optional)
+
+Das Razor-Feature ist als separates Paket/Projekt verfügbar.
+
+```bash
+# Razor-Erweiterung lokal referenzieren
+dotnet add <IhrProjekt>.csproj reference MbSoftLab.TemplateEngine.Core.Razor/MbSoftLab.TemplateEngine.Core.Razor.csproj
+
+# Oder als NuGet installieren
+dotnet add package MbSoftLab.TemplateEngine.Core.Razor
+```
+
+Die Projekte, die `RazorTemplateEngine<T>` verwenden, müssen die Razor-Erweiterung referenzieren oder das NuGet einsetzen.
+
 ### Tests ausführen
 
 ```bash
diff --git a/docs/examples.md b/docs/examples.md
