Generieren von Code zur Entwurfszeit mithilfe von T4-Textvorlagen

T4-Entwurfszeittextvorlagen ermöglichen es Ihnen, Programmcode und andere Dateien im Visual Studio-Projekt zu generieren. In der Regel werden die Vorlagen so geschrieben, dass der Code, der gemäß den Daten aus einem Modell generiert wird, variiert wird. Ein Modell ist eine Datei oder Datenbank, die wichtige Informationen zu den Anforderungen der Anwendung enthält.

In einem Modell kann z. B. ein Workflow entweder als Tabelle oder Diagramm definiert sein. Anhand des Modells können Sie die Software generieren, die den Workflow ausführt. Wenn sich die Anforderungen der Benutzer ändern, kann der neue Workflow problemlos mit den Benutzern besprochen werden. Die erneute Generierung des Codes anhand des Workflows ist zuverlässiger als die manuelle Aktualisierung des Codes.

Sie sind wahrscheinlich bereits mit der Codegenerierung vertraut. Wenn Sie Ressourcen in einer .resx-Datei in der Visual Studio-Projektmappe definieren, wird automatisch ein Satz von Klassen und Methoden generiert. Durch die Ressourcendatei können die Ressourcen einfacher und zuverlässiger bearbeitet werden als dies beim Bearbeiten der Klassen und Methoden möglich wäre. Mithilfe von Textvorlagen können Sie Code auf die gleiche Weise aus einer selbst entworfenen Quelle generieren.

Eine Textvorlage enthält eine Mischung des Texts, den Sie generieren möchten, sowie Programmcode, der Variablenteile des Texts generiert. Der Programmcode ermöglicht die Wiederholung oder das bedingte Auslassen von Teilen des generierten Texts. Der generierte Text selbst kann Programmcode sein, der einen Teil der Anwendung bildet.

Erstellen einer T4-Textvorlage für die Entwurfszeit

So erstellen Sie eine T4-Vorlage für die Entwurfszeit in Visual Studio

1. Erstellen Sie ein Visual Studio-Projekt, oder öffnen Sie ein vorhandenes Projekt.

   Zeigen Sie z. B. im Menü Datei auf Neu, und klicken Sie dann auf Projekt.

2. Fügen Sie dem Projekt eine Textvorlagendatei mit dem Namen "NewTemplate.tt" hinzu.

   Klicken Sie dazu im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, zeigen Sie auf Hinzufügen, und klicken Sie dann auf Neues Element. Wählen Sie im Dialogfeld Neues Element hinzufügen im Bereich Vorlagen die Option Textvorlage aus. Geben Sie für die Datei den Namen "NewTemplate.tt" ein.

   Die Eigenschaft Benutzerdefiniertes Tool der Datei ist auf TextTemplatingFileGenerator festgelegt.

3. Öffnen Sie die Datei. Sie enthält bereits die folgenden Direktiven:

   <#@ template debug="false" hostspecific="false" language="C#" #>
   <#@ output extension=".txt" #>
   

   Wenn Sie die Vorlage einem Visual Basic-Projekt hinzugefügt haben, ist das Sprachattribut auf VB festgelegt.

4. Fügen Sie am Ende der Datei Text hinzu. Beispiel:

   Hello, world!
   

5. Speichern Sie die Datei.

   Möglicherweise wird eine Sicherheitswarnung angezeigt, in der Sie aufgefordert werden, die Ausführung der Vorlage zu bestätigen. Klicken Sie auf OK.

6. Erweitern Sie im Projektmappen-Explorer den Knoten "NewTemplate.tt". Der Knoten enthält eine Datei mit dem Namen "NewTemplate.txt". Die Datei enthält den von Ihnen eingegebenen Text.

   Tipp

   Im Fall eines Visual Basic-Projekts müssen Sie auf Alle Dateien anzeigen klicken, um die Ausgabedatei "NewTemplate.txt" anzuzeigen.

Erneutes Generieren des Codes

In den folgenden Fällen wird eine Vorlage ausgeführt, wobei die untergeordnete Datei generiert wird:

• Sie bearbeiten eine Vorlage und verschieben dann den Fokus auf ein anderes Visual Studio-Fenster.

• Sie speichern die Vorlage.

• Sie klicken Sie auf der Symbolleiste im Projektmappen-Explorer auf Alle Vorlagen transformieren. Dadurch werden alle Vorlagen in der Visual Studio-Projektmappe transformiert.

• Sie klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf eine oder mehrere Dateien und klicken dann auf Benutzerdefiniertes Tool ausführen. Verwenden Sie diese Methode, um ausgewählte Vorlagen zu transformieren.

Sie können ein Visual Studio-Projekt auch so einrichten, dass die Vorlagen ausgeführt werden, wenn sich die von den Vorlagen gelesenen Datendateien ändern. Weitere Informationen finden Sie unter Automatisches erneutes Generieren des Codes.

Generieren von Variablentext

Textvorlagen ermöglichen es Ihnen, den Inhalt der generierten Datei mithilfe von Programmcode zu verändern.

So generieren Sie Text mithilfe von Programmcode

1. Ändern des Inhalts der .tt-Datei:

   <#@ template debug="false" hostspecific="false" language="C#" #>
   <#@ output extension=".txt" #>
   <#int top = 10;
   
   for (int i = 0; i<=top; i++) { #>
   The square of <#= i #> is <#= i*i #>
   <# } #>
   

   <#@ template debug="false" hostspecific="false" language="VB" #>
   <#@ output extension=".txt" #>
   <#Dim top As Integer = 10
   
   For i As Integer = 0 To top
   #>
       The square of <#= i #> is <#= i*i #>
   <#
   Next
   #>
   

2. Speichern Sie die TT-Datei, und überprüfen Sie die generierte TXT-Datei erneut. Sie enthält die Quadratzahlen der Zahlen 0 bis 9.

Beachten Sie, dass Anweisungen in <#...#> eingeschlossen sind und einzelne Ausdrücke in <#=...#>. Weitere Informationen finden Sie unter Schreiben einer T4-Textvorlage.

Wenn Sie den generierenden Code in Visual Basic schreiben, sollte die template-Direktive language="VB" enthalten. Standardmäßig ist "C#" festgelegt.

Generieren von Code oder Ressourcen für die Projektmappe

Abhängig vom Modell können verschiedene Programmdateien generiert werden. Ein Modell ist eine Eingabequelle wie eine Datenbank, eine Konfigurationsdatei, ein UML- oder DSL-Modell oder eine andere Quelle. Normalerweise generieren Sie mehrere Programmdateien aus dem gleichen Modell. Sie erstellen zu diesem Zweck eine Vorlagendatei für jede generierte Programmdatei und lassen das gleiche Modell von allen Vorlagen lesen.

So generieren Sie Programmcode oder Ressourcen

1. Ändern Sie die output-Direktive, um eine Datei des entsprechenden Typs zu generieren, z. B. .cs, .vb, .resx oder .xml.

2. Fügen Sie Code ein, durch den der benötigte Projektmappencode generiert wird. Fügen Sie z. B. folgenden Code ein, wenn Sie drei Deklarationen für Felder für ganze Zahlen in einer Klasse generieren möchten:

                     <#@ template debug="false" hostspecific="false" language="C#" #>
   <#@ output extension=".cs" #>
   <# var properties = new string [] {"P1", "P2", "P3"}; #>
   class MyGeneratedClass {
   <# 
     foreach (string propertyName in properties)
     { #>
     private int <#= propertyName #> = 0;
   <# } #>
   }
   

   <#@ template debug="false" hostspecific="false" language="VB" #>
   <#@ output extension=".cs" #>
   <# Dim properties = {"P1", "P2", "P3"} #>
   class MyGeneratedClass {
   <# 
      For Each propertyName As String In properties
   #>
     private int <#= propertyName #> = 0;
   <#
      Next
   #>
   }
   

3. Speichern Sie die Datei, und überprüfen Sie die generierte Datei, die nun den folgenden Code enthält:

   class MyGeneratedClass {
     private int P1 = 0; 
     private int P2 = 0;
     private int P3 = 0;
   }
   

Generieren von Code und generierter Text

Wenn Sie Programmcode generieren, ist es wichtig, den Generierungscode, der in der Vorlage ausgeführt wird, nicht mit dem resultierenden generierten Code zu verwechseln, der Teil der Projektmappe wird. Die beiden Sprachen müssen nicht identisch sein.

Das vorherige Beispiel enthält zwei Versionen. In einer Version liegt der generierende Code in C# vor. In der anderen Version liegt der generierende Code in Visual Basic vor. Der in beiden Versionen generierte Text ist jedoch identisch, und er befindet sich in einer C#-Klasse.

Ebenso können Sie eine Visual C#-Vorlage verwenden, um Code in einer beliebigen Sprache zu generieren. Der generierte Text muss nicht in einer bestimmten Sprache vorliegen, und es muss sich nicht um Programmcode handeln.

Strukturieren von Textvorlagen

Es wird empfohlen, den Vorlagencode in zwei Teile aufzuteilen:

• Ein Konfigurations- oder Datensammlungsteil, der Werte in Variablen festlegt, jedoch keine Textblöcke enthält. Im vorherigen Beispiel ist dieser Teil die Initialisierung von properties.

  Dies wird manchmal als Modellabschnitt bezeichnet, da ein speicherinternes Modell erstellt und normalerweise eine Modelldatei gelesen wird.

• Der Textgenerierungsteil (im vorliegenden Beispiel foreach(...){...}), in dem die Werte der Variablen verwendet werden.

Dies ist keine notwendige Trennung, doch auf diese Weise wird das Lesen der Vorlage wegen der geringeren Komplexität des Teils, der Text enthält, vereinfacht.

Lesen von Dateien oder anderen Quellen

Im Vorlagencode können Assemblys wie System.XML verwendet werden, um auf eine Modelldatei oder eine Datenbank zuzugreifen. Um Zugriff auf diese Assemblys zu erhalten, müssen Sie wie hier dargestellt Direktiven einfügen:

<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#@ import namespace="System.IO" #>

Die assembly-Direktive macht die angegebene Assembly auf die gleiche Weise für den Vorlagencode verfügbar wie der Abschnitt "Verweise" eines Visual Studio-Projekts. Sie müssen keinen Verweis auf "System.dll" einschließen, da automatisch darauf verwiesen wird. Die import-Direktive ermöglicht wie die using-Direktive in einer normalen Programmdatei die Verwendung von Typen ohne ihre vollqualifizierten Namen.

Nach dem Import von System.IO können Sie z. B. Folgendes schreiben:

          <# var properties = File.ReadLines("C:\\propertyList.txt");#>
...
<# foreach (string propertyName in properties) { #>
...

<# For Each propertyName As String In 
             File.ReadLines("C:\\propertyList.txt")
#>

Öffnen einer Datei mit einem relativen Pfadnamen

Verwenden Sie this.Host.ResolvePath(), um eine Datei aus einem Ort zu laden, der relativ zur Textvorlage ist. Zur Verwendung von this.Host muss hostspecific="true" in template festgelegt werden:

<#@ template debug="false" hostspecific="true" language="C#" #>

Anschließend können Sie z. B. Folgendes schreiben:

<# string fileName = this.Host.ResolvePath("filename.txt");
  string [] properties = File.ReadLines(filename);
#>
...
<#  foreach (string propertyName in properties { #>
...

<# Dim fileName = Me.Host.ResolvePath("propertyList.txt")
   Dim properties = File.ReadLines(filename)
#>
...
<#   For Each propertyName As String In properties
...
#>

Sie können auch this.Host.TemplateFile verwenden, was den Namen der aktuellen Vorlagendatei darstellt.

Der Typ von this.Host (in VB Me.Host) ist Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost.

Abrufen von Daten von Visual Studio

Um in Visual Studio bereitgestellte Dienste zu verwenden, legen Sie das hostSpecific-Attribut fest, und laden Sie die EnvDTE-Assembly. Beispiele:

<#@ 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 #>

Automatisches erneutes Generieren des Codes

In der Regel werden mehrere Dateien in einer Visual Studio-Projektmappe mit einem Eingabemodell generiert. Jede Datei wird aus einer eigenen Vorlage generiert, die Vorlagen verweisen jedoch alle auf das gleiche Modell.

Wenn sich das Quellmodell ändert, müssen Sie alle Vorlagen in der Projektmappe erneut ausführen. Klicken Sie auf der Symbolleiste des Projektmappen-Explorers auf Alle Vorlagen transformieren, um die erneute Generierung manuell auszuführen.

Wenn Sie das Visualisierungs- und Modellierungs-SDK für Visual Studio installiert haben, können alle Vorlagen bei jeder Buildausführung automatisch transformiert werden. Bearbeiten Sie dazu die Projektdatei (.csproj oder .vbproj) in einem Text-Editor, und fügen Sie in der Nähe des Endes der Datei nach allen anderen <import>-Anweisungen die folgenden Zeilen hinzu:

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\TextTemplating\v10.0\Microsoft.TextTemplating.targets" />
<PropertyGroup>
   <TransformOnBuild>true</TransformOnBuild>
   <!-- Other properties can be inserted here -->
</PropertyGroup>

Weitere Informationen finden Sie unter Codegenerierung in einem Buildprozess.

Fehlerberichte

Zum Anzeigen von Fehler- und Warnmeldungen im Fehlerfenster von Visual Studio stehen Ihnen die folgenden Methoden zur Verfügung:

Error("An error message");
Warning("A warning message");

Konvertieren einer vorhandenen Datei in eine Vorlage

Eine hilfreiche Eigenschaft von Vorlagen ist, dass sie den generierten Dateien sehr ähneln und zudem einigen eingefügten Programmcode enthalten. Dadurch ergibt sich eine einfache Methode zum Erstellen einer Vorlage. Erstellen Sie zuerst eine normale Datei als Prototyp, z. B. eine Visual C#-Datei, und fügen Sie dann nach und nach Generierungscode ein, durch den die resultierende Datei verändert wird.

So konvertieren Sie eine vorhandene Datei in eine Entwurfszeitvorlage

1. Fügen Sie dem Visual Studio-Projekt eine Datei des Typs hinzu, den Sie generieren möchten, z. B. eine .cs-, .vb- oder .resx-Datei.

2. Testen Sie die neue Datei, um sicherzustellen, dass sie ordnungsgemäß funktioniert.

3. Ändern Sie in Projektmappen-Explorer die Dateinamenerweiterung in .tt.

4. Überprüfen Sie die folgenden Eigenschaften der .tt-Eigenschaft:

   Benutzerdefiniertes Tool =	TextTemplatingFileGenerator
   Buildvorgang =	Keiner

5. Fügen Sie am Anfang der Datei die folgenden Zeilen ein:

   <#@ template debug="false" hostspecific="false" language="C#" #>
   <#@ output extension=".cs" #>
   

   Wenn Sie den Generierungscode der Vorlage in Visual Basic schreiben möchten, legen Sie das language-Attribut anstelle von "C#" auf "VB" fest.

   Legen Sie das extension-Attribut auf die Dateinamenerweiterung für den zu generierenden Dateityp fest, z. B. .cs, .resx oder .xml.

6. Speichern Sie die Datei.

   Eine untergeordnete Datei mit der angegebenen Erweiterung wird erstellt. Die Eigenschaften entsprechen dem Dateityp. Die Eigenschaft Buildvorgang einer CS-Datei wäre z. B. Kompilieren.

   Vergewissern Sie sich, dass die generierte Datei den gleichen Inhalt enthält wie die ursprüngliche Datei.

7. Identifizieren Sie einen Teil der Datei, den Sie ändern möchten. Beispielsweise einen Teil, der nur unter bestimmten Bedingungen angezeigt oder wiederholt wird oder in dem sich bestimmte Werte ändern. Fügen Sie Generierungscode ein. Speichern Sie die Datei, und überprüfen Sie, ob die untergeordnete Datei ordnungsgemäß generiert wurde. Wiederholen Sie diesen Schritt.

Richtlinien für die Codegenerierung

Siehe Richtlinien für das Verfassen von T4-Textvorlagen.

Nächste Schritte

Siehe auch

Weitere Ressourcen

Richtlinien für das Verfassen von T4-Textvorlagen

Änderungsprotokoll