ValidateTemplate-Methode hinzufügen, die prüft, ob ein Template gebaut werden kann

[jupre003]

Hintergrund

Im Projekt existiert in den Docs bereits ein kleines Beispiel zur Template-Validierung (siehe "Tipp 2: Template-Validierung"). Aktuell ist das nur ein Beispiel-Helper in der Dokumentation. Ziel dieses Issues ist, eine offizielle, wiederverwendbare ValidateTemplate-Methode in der API einzuführen, die prüft, ob ein gegebenes Template erfolgreich gebaut / gerendert werden kann (ohne Nebenwirkungen) und strukturierte Informationen über Fehler liefert.

Vorschlag / API-Design

• Neuer Rückgabetyp:
  • class TemplateValidationResult
    • bool IsValid
    • List Errors (lesbar; leer wenn IsValid == true)
    • Exception? Exception (optional; für interne Compile-/Razor-Fehler)
• Methoden (Überladungen):
  • Instanzmethode:
    • TemplateValidationResult ValidateTemplate(string? template = null)
      • Verwendet bei Instanz vorhandene TemplateString / TemplateDataModel wenn template == null
  • Statische/generische Variante:
    • TemplateValidationResult ValidateTemplate(string template, T? sampleData = default)
  • Typ-basierte Variante:
    • TemplateValidationResult ValidateTemplate(string template, Type? modelType = null)
• Verhalten:
  • Methode führt eine "trocken" Verarbeitung durch:
    • Parst/analysiert das Template.
    • Versucht, alle Platzhalter (Property-Zugriffe / parameterlose Methoden-Aufrufe) gegen ein Instanzobjekt oder gegen modelType (mit Activator.CreateInstance wenn möglich) aufzulösen.
    • Für Razor-Engine: versucht Razor-Compile, aber ohne Ausführung von benutzerseitigem Code mit Seiteneffekten.
  • Rückgabe:
    • Wenn alles funktioniert: IsValid == true, Errors == []
    • Wenn Fehler auftreten: IsValid == false, Errors enthält menschenlesbare Fehlermeldungen (z. B. "Property 'Foo' not found on type Customer", "Method 'GetTotal(int)' requires parameters", "Razor compilation error: ...")
  • Eingabe-Validierung:
    • template null oder whitespace -> IsValid == false, Errors enthält "Template is empty" (oder deutsche Message)
  • Thread-safety: Methode darf keine globale Engine-Instanz verändern; muss thread-safe sein.

Beispiele

Instanzvariante

var engine = new TemplateEngine<Customer>();
engine.TemplateDataModel = customer;
engine.TemplateString = "Hallo ${Name} ${NonExisting}";

var result = engine.ValidateTemplate();
// result.IsValid == false
// result.Errors -> ["Property 'NonExisting' not found on type Customer"]

Statische/generische Variante

var result = TemplateEngine.ValidateTemplate<Customer>("Hallo ${Name} ${OrderCount}");
if (!result.IsValid) {
    Console.WriteLine(string.Join("\n", result.Errors));
}

Akzeptanzkriterien

1. Es existiert der Typ TemplateValidationResult mit den angegebenen Eigenschaften.
2. Mindestens eine Instanzmethode ValidateTemplate(string? template = null) ist implementiert und funktioniert wie beschrieben.
3. Mindestens eine Generic-/statische Variante (ValidateTemplate) ist vorhanden.
4. Fehlende Properties führen zu aussagekräftigen Fehlermeldungen in result.Errors (keine unstrukturierte StackTrace-Ausgabe als alleiniges Feedback).
5. Parameterlose Methodenaufrufe, die existieren, werden als gültig erkannt; Methoden mit Parametern werden als Fehler gemeldet.
6. Razor-Templates (falls Razor-Paket installiert) sollten validiert werden — Kompilationsfehler werden in Errors abgebildet.
7. Unit-Tests: Coverage für valide Template, fehlende Property, Methode mit Parametern, null/empty template, Razor compile error.
8. Kein Breaking Change für existierende API-Nutzer.

---

Testfälle (Unit-Tests):

• ValidateTemplate_ReturnsValid_ForSimpleProperties
• ValidateTemplate_ReturnsError_ForMissingProperty
• ValidateTemplate_ReturnsError_ForMethodWithParameters
• ValidateTemplate_ReturnsValid_ForParameterlessMethod
• ValidateTemplate_ReturnsError_ForEmptyTemplate
• ValidateTemplate_HandlesRazorCompilationError (nur falls Razor optional-Paket vorhanden; kann mit ConditionalFact / Category markiert werden)
• ValidateTemplate_IsThreadSafe (paralleler Aufruf mit verschiedenen Templates)

Dokumentation

• docs/examples.md: Beispiel unter "Tipp 2: Template-Validierung" ersetzen/erweitern und auf die neue Methode verweisen.
• API-Docs: Signaturen und TemplateValidationResult dokumentieren.
• Release-Notes: Kurzbeschreibung der neuen Methode und Beispiel.

Implementierungs-Hinweise

• Wiederverwenden, wenn möglich, der internen Parsing- / Compile-Pipelines, aber in "trockenem" Modus (kein echtes Rendern mit Seiteneffekten).
• Für Reflection-basierte Validierung kann ein Instanz-Objekt (Activator.CreateInstance) oder ein vom Nutzer übergebenes sampleData zur Prüfung genutzt werden.
• Für Razor: sicherstellen, dass Kompilierung isoliert läuft; nicht synchronen Code mit Seiteneffekten aufrufen.
• Fehlertexte sollten lokalisiert werden (vorerst deutsch/englisch), für MVP englische, gut lesbare Meldungen sind ausreichend.
• Performance: Validierung soll schneller als vollständiges Rendering sein, aber es ist akzeptabel, die normalen Parsing-/Compile-Schritte zu nutzen.