Freigeben über

Gewusst wie: ... mit Textvorlagen

Textvorlagen in Visual Studio stellen eine nützliche Möglichkeit dar, Text jeglicher Art zu erzeugen. Mithilfe von Textvorlagen können Sie zur Laufzeit Text als Teil Ihrer Anwendung erzeugen und zur Entwurfszeit einen Teil Ihres Projektcodes generieren. In diesem Thema werden die am häufigsten gestellten Fragen zur Vorgehensweise zusammengefasst.

In diesem Thema stellen mehrere Antworten, denen Aufzählungspunkte vorangestellt sind, alternative Vorschläge dar.

Eine allgemeine Einführung in Textvorlagen finden Sie unter Codegenerierung und T4-Textvorlagen.

Gewusst wie ...

Generieren eines Teils meines Anwendungscodes

Ich verfüge über eine Konfiguration oder ein Modell in einer Datei oder einer Datenbank. Mindestens ein Teil meines Codes hängt von diesem Modell ab.

Generieren von Dateien zur Laufzeit, Übergeben von Daten an die Vorlage

Meine Anwendung generiert zur Laufzeit Textdateien, z. B. Berichte, die eine Mischung aus Standardtext und Daten enthalten. Ich möchte es vermeiden, Hunderte von write-Anweisungen zu schreiben.

  • Fügen Sie Ihrem Projekt eine Laufzeittextvorlage hinzu. Diese Vorlage erstellt eine Klasse in Ihrem Code, die Sie instanziieren und zum Generieren von Text verwenden können. Sie können über die Konstruktorparameter Daten an die Vorlage übergeben. Weitere Informationen finden Sie unter Laufzeittextgenerierung mithilfe von T4-Textvorlagen.

  • Wenn Sie Text aus Vorlagen generieren möchten, die nur zur Laufzeit verfügbar sind, können Sie Standardtextvorlagen verwenden. Wenn Sie eine Visual Studio-Erweiterung schreiben, können Sie den Textvorlagendienst aufrufen. Weitere Informationen finden Sie unter Aufrufen der Texttransformation in einer Visual Studio-Erweiterung. In anderen Kontexten können Sie die Textvorlagen-Engine verwenden. Weitere Informationen finden Sie unter Microsoft.VisualStudio.TextTemplating.Engine.

    Verwenden Sie die Anweisung <#@parameter#>, um Parameter an diese Vorlagen zu übergeben. Weitere Informationen finden Sie unter T4-Anweisung „parameter“.

Lesen einer anderen Projektdatei aus einer Vorlage

So lesen Sie eine Datei aus demselben Visual Studio-Projekt wie die Vorlage

  • Fügen Sie hostSpecific="true" in die <#@template#>-Anweisung ein.

    Verwenden this.Host.ResolvePath(filename) Sie im Code, um den vollständigen Pfad der Datei abzurufen.

Aufrufen von Methoden aus einer Vorlage

Wenn die Methoden bereits vorhanden sind, z. B. in .NET-Klassen:

  • Verwenden Sie die Anweisung <#@assembly#>, um die Assembly zu laden, und verwenden Sie <#@import#>, um den Namespacekontext festzulegen. Weitere Information finden Sie unter T4-Anweisung „import“.

    Wenn Sie häufig dieselben Assembler- und Importanweisungen verwenden, sollten Sie einen Anweisungsprozessor schreiben. Sie können in jeder Vorlage den Anweisungsprozessor aufrufen, der dann die Assemblys und die Modelldateien laden und den Namespacekontext festlegen kann. Weitere Informationen finden Sie unter Erstellen von benutzerdefinierten T4-Anweisungsprozessoren für Textvorlagen.

Wenn Sie die Methoden selbst schreiben:

  • Wenn Sie eine Laufzeittextvorlage schreiben, schreiben Sie eine partielle Klassendefinition, die denselben Namen wie Ihre Laufzeittextvorlage trägt. Fügen Sie dieser Klasse die zusätzlichen Methoden hinzu.

  • Schreiben Sie einen Klassenfunktionskontrollblock <#+ ... #>, in dem Sie Methoden, Eigenschaften und private Klassen deklarieren können. Wenn die Textvorlage kompiliert wurde, wird sie in eine Klasse umgewandelt. Die Standardkontrollblöcke <#...#> und der Text werden in eine einzelne Methode transformiert, und Klassenfunktionsblöcke werden als separate Member eingefügt. Weitere Informationen finden Sie unter Kontrollblöcke für Textvorlagen.

    Methoden, die als Klassenfunktionen definiert sind, können auch eingebettete Textblöcke enthalten.

    Erwägen Sie die Platzierung von Klassenfunktionen in einer separaten Datei, die Sie per <#@include#> in eine oder mehrere Vorlagendateien einfügen können.

  • Schreiben Sie die Methoden in eine separate Assembly (Klassenbibliothek), und rufen Sie sie über Ihre Vorlage auf. Verwenden Sie die Anweisung <#@assembly#> zum Laden der Assembly und <#@import#> zum Festlegen des Namespacekontexts. Beachten Sie, dass Sie Visual Studio möglicherweise beenden und neu starten müssen, um die Assembly während des Debuggens neu zu erstellen. Weitere Information finden Sie unter T4-Anweisungen für Textvorlagen.

Generieren von vielen Dateien aus einem Modellschema

Wenn Sie häufig Dateien aus Modellen generieren, die das gleiche XML- oder Datenbankschema verwenden:

Generieren von Dateien aus einem komplexen Modell

  • Erwägen Sie, eine domänenspezifische Sprache (DSL) zur Darstellung des Modells zu erstellen. Dies erleichtert das Schreiben der Vorlagen erheblich, da Sie Typen und Eigenschaften verwenden, die die Namen der Elemente in Ihrem Modell widerspiegeln. Sie müssen die Datei nicht parsen oder durch XML-Knoten navigieren. Zum Beispiel:

    foreach (Book book in this.Library) { ... }

    Weitere Informationen finden Sie unter Erste Schritte mit domänenspezifischen Sprachen und Generieren von Code für eine domänenspezifische Sprache.

Abrufen von Daten aus Visual Studio

Zur Verwendung der in Visual Studio bereitgestellten Dienste legen Sie das Attribut hostSpecific fest und laden die Assembly EnvDTE. Zum Beispiel:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#
  IServiceProvider serviceProvider = (IServiceProvider)this.Host;
  EnvDTE.DTE dte = (EnvDTE.DTE) serviceProvider.GetService(typeof(EnvDTE.DTE));
#>

Number of projects in this VS solution:  <#= dte.Solution.Projects.Count #>

Ausführen von Textvorlagen im Buildprozess

Allgemeinere Fragen

Womit sollte man beim Schreiben einer Textvorlage am besten beginnen?

  1. Schreiben Sie ein konkretes Beispiel für die generierte Datei.

  2. Wandeln Sie das Beispiel in eine Textvorlage um, indem Sie die Anweisung <#@template #> sowie den Code und die Anweisungen einfügen, die zum Laden der Eingabedatei oder des Modells erforderlich sind.

  3. Ersetzen Sie Teile der Datei nach und nach durch Ausdrücke und Codeblöcke.

Was ist ein „Modell“?

  • Die Eingabe, die von Ihrer Vorlage gelesen wird. Sie kann sich in einer Datei oder in einer Datenbank befinden. Dabei kann es sich um XML, eine Visio-Zeichnung, eine domänenspezifische Sprache (DSL), ein UML-Modell oder um einfachen Text handeln. Das Modell kann auf mehrere Dateien verteilt sein. Typischerweise wird ein Modell von mehr als einer Vorlage gelesen.

    Der Begriff „Modell“ impliziert, dass es einen Aspekt Ihres Geschäfts besser abbildet als der generierte Programmcode oder andere Dateien. So könnte das Modell beispielsweise den Aufbau eines Kommunikationsnetzwerks repräsentieren, das von Ihrer generierten Software überwacht werden soll.

Welchen Vorteil bietet die Verwendung von Textvorlagen?

Normalerweise generieren Sie mehrere Codedateien oder sonstige Dateien aus einem Modell. Das Modell bildet die Anforderungen genauer ab als der generierte Code. Es enthält keine Details zur Implementierung und wird nicht mit Blick auf den Code, sondern in Bezug auf die Anforderungen geschrieben. Wenn sich die Anforderungen ändern – und das ist meistens der Fall – können Sie das Modell einfacher und zuverlässiger aktualisieren als die verschiedenen Teile des Programmcodes.

Die Codegenerierung ist daher aus der Perspektive der agilen Entwicklungsmethoden ein wertvolles Werkzeug.

Welche „bewährten Methoden“ gibt es für Textvorlagen?

Was ist T4?

  • Ein anderer Name für die hier beschriebenen Textvorlagenfunktionen von Visual Studio. Die (nicht veröffentlichte) Vorgängerversion war eine Abkürzung für „Text Template Transformation“ (Textvorlagentransformation).