T4-Vorlagendirektive

Eine Visual Studio T4-Textvorlage beginnt normalerweise mit einer template-Direktive, die angibt, wie die Vorlage verarbeitet werden soll. In einer Textvorlage und allen darin enthaltenen Dateien darf nur eine Vorlagendirektive vorhanden sein.

Eine allgemeine Übersicht über das Schreiben von Textvorlagen finden Sie unter Schreiben einer T4-Textvorlage.

Verwenden der Vorlagendirektive

<#@ template [language="VB"] [compilerOptions="options"] [culture="code"] [debug="true"] [hostspecific="true"] [inherits="templateBaseClass"] #>

Die template-Direktive besitzt mehrere Attribute, mit denen Sie verschiedene Aspekte der Transformation angeben können. Alle Attribute sind optional.

compilerOptions-Attribut

• Beispiel:
  compilerOptions="optimize+"

• Gültige Werte:
  Alle gültigen Compileroptionen. Weitere Informationen finden Sie unter C#-Compileroptionen nach Kategorien sortiert und Visual Basic-Compileroptionen nach Kategorien sortiert.

  Ignoriert für Laufzeitvorlagen (vorverarbeitete Vorlagen).

Diese Optionen werden übernommen, wenn die Vorlage in Visual C# oder Visual Basic konvertiert wurde. Der daraus resultierende Code wird kompiliert.

Kulturattribut

• Beispiel:
  culture="de-CH"

• Gültige Werte:
  "", die invariante Kultur (Standard).

  Eine als Zeichenfolge im Format xx-XX ausgedrückte Kultur. Beispiel: en-US, ja-JP, de-CH, de-DE. Weitere Informationen finden Sie unter System.Globalization.CultureInfo.

Das Kulturattribut gibt die Kultur an, die verwendet werden soll, wenn ein Ausdrucksblock in Text konvertiert wird.

debug-Attribut

• Beispiel:

  debug="true"
  

• Gültige Werte:
  true, false. Der Standardwert ist "False".

Das debug-Attribut gibt an, ob Debuggen aktiviert ist. Wenn der Wert true ergibt, enthält die Zwischencodedatei Informationen, mit denen der Debugger die Position in der Vorlage erkennen kann, an der eine Unterbrechung oder Ausnahme aufgetreten ist. Für Entwurfszeitvorlagen wird die Zwischencodedatei in das % TEMP%-Verzeichnis geschrieben.

Um den Debugger an einen bestimmten Punkt während der Ausführung einer Vorlage zu starten, fügen Sie einen Aufruf an Launch ein. Um die Ausführung an nachfolgenden Punkten zu unterbrechen, fügen Sie einen Aufruf an Break ein. Beispiel:

<#@ template debug="true" language="C#" #>
<#@ output extension=".txt" #>
Output something.
<# 
 // Break here:
 System.Diagnostics.Debugger.Launch();  
#>
Output more.
<#
 // Break here also:
 System.Diagnostics.Debugger.Break();  
#>
Output more.

Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Debuggen einer Textvorlage.

hostspecific-Attribut

• Beispiel:

  hostspecific="true"
  

• Gültige Werte:
  true, false. Der Standardwert ist "False".

Wenn Sie den Wert dieses Attributs auf true festlegen, wird der von der Textvorlage generierten Klasse eine Eigenschaft mit dem Namen Host hinzugefügt. Die Eigenschaft ist ein Verweis auf den Host des Transformationsmoduls und wird als Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost deklariert. Wenn Sie einen benutzerdefinierten Host definiert haben, können Sie ihn in den benutzerdefinierten Hosttyp umwandeln.

Da der Typ dieser Eigenschaft vom Typ des Hosts abhängt, ist sie nur nützlich, wenn Sie eine Textvorlage schreiben, für die ein bestimmter Host verwendet werden muss.

Wenn hostspecific auf true festgelegt ist und Sie Visual Studio verwenden, können Sie this.Host in IServiceProvider umwandeln, um auf Visual Studio-Funktionen zuzugreifen. Sie können den absoluten Pfad einer Datei im Projekt auch mithilfe von Host.ResolvePath(filename) abrufen. Beispiel:

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<# // Get the Visual Studio API as a service:
 DTE dte = ((IServiceProvider)this.Host).GetService(typeof(DTE)) as DTE;  
#>
Number of projects in this solution: <#=  dte.Solution.Projects.Count #>

<#
 // Find a path within the current project:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of myFile is:
<#= myFile #>

language-Attribut

• Beispiel:
  language="VB"

• Gültige Werte:
  C# (Standardwert)

  VB

  (Die Werte VBv3.5 und C#v3.5 sind in dieser Version des Tools veraltet, werden aber als VB und C# interpretiert.)

Das language-Attribut gibt die Sprache an (Visual Basic oder Visual C#), die in Anweisungs- und Ausdrucksblöcken des Quellcodes verwendet werden soll. Die Zwischencodedatei, von der die Ausgabe generiert wird, verwendet diese Sprache. Diese Sprache bezieht sich nicht auf die Sprache, die von der Vorlage generiert wird, wobei es sich um eine beliebige Art von Text handeln kann.

Beispiel:

<#@ template language="VB" #>
<#@ output extension=".txt" #>
Squares of numbers:
<#
  Dim number As Integer
  For number = 1 To 4
#>
  Square of <#= number #> is <#= number * number #>
<#
  Next number
#>

inherits-Attribut

Sie können angeben, dass der Programmcode der Vorlage von einer anderen Klasse erben kann, die auch mit einer Textvorlage generiert werden kann.

Vererbung in einer Laufzeittextvorlage (vorverarbeiteten Textvorlage)

Sie können Vererbung zwischen Laufzeittextvorlagen verwenden, um eine Basisvorlage zu erstellen, die mehrere abgeleitete Varianten besitzt. Laufzeitvorlagen sind Vorlagen, bei denen die Eigenschaft Benutzerdefiniertes Tool auf TextTemplatingFilePreprocessor festgelegt ist. Eine Laufzeitvorlage generiert Code, den Sie in der Anwendung aufrufen können, um den in der Vorlage definierten Text zu erstellen. Weitere Informationen finden Sie unter Generieren von Text zur Laufzeit mithilfe von vorverarbeiteten T4-Textvorlagen.

Wenn Sie kein inherits-Attribut angeben, werden eine Basisklasse und eine abgeleitete Klasse von der Textvorlage generiert. Wenn Sie ein inherits-Attribut angeben, wird nur die abgeleitete Klasse generiert. Sie können eine Basisklasse manuell erstellen, doch sie muss über die Methoden verfügen, die von der abgeleiteten Klasse verwendet werden.

In der Regel geben Sie noch eine vorverarbeitete Vorlage als Basisklasse an. Die Basisvorlage beinhaltet allgemeine Textblöcke, die sich mit Text aus den abgeleiteten Vorlagen überlappen können. Sie können mithilfe von Klassenfunktionsblöcken (<#+ ... #>) Methoden definieren, die Textfragmente enthalten. Sie können z. B. das Framework des Ausgabetexts in der Basisvorlage platzieren und virtuelle Methoden bereitstellen, die in abgeleiteten Vorlagen überschrieben werden können:

• Laufzeittextvorlage "BaseTemplate.tt" (vorverarbeitete Vorlage):

  This is the common header.
  <# 
    SpecificFragment1(); 
  #>
  A common central text.
  <# 
    SpecificFragment2(); 
  #>
  This is the common footer.
  <#+ 
    // Declare abstract methods
    protected virtual void SpecificFragment1() { }
    protected virtual void SpecificFragment2() { }
  #>
  

• Laufzeittextvorlage "DerivedTemplate1.tt" (vorverarbeitete Vorlage):

  <#@ template language="C#" inherits="BaseTemplate" #>
  <# 
    // Run the base template:
    base.TransformText();
  #>
  <#+
  // Provide fragments specific to this derived template:
  protected override void SpecificFragment1()
  {
  #>
     Fragment 1 for DerivedTemplate1
  <#+
  }
  protected override void SpecificFragment2()
  {
  #>
     Fragment 2 for DerivedTemplate1
  <#+
  }
  #>
  

• Anwendungscode zum Aufruf von "DerivedTemplate1":

  Console.WriteLine(new DerivedTemplate().TransformText());
  

• Ergebnis:

  This is the common header.
     Fragment 1 for DerivedTemplate1
  A common central text.
     Fragment 2 for DerivedTemplate1
  This is the common footer.
  

Sie können die Basisklassen und die abgeleiteten Klassen in verschiedenen Projekten erstellen. Fügen Sie das Basisprojekt oder die Assembly den Verweisen des abgeleiteten Projekts hinzu.

Sie können auch eine gewöhnliche, von Hand geschriebene Klasse als Basisklasse verwenden. Die Basisklasse muss die von der abgeleiteten Klasse verwendeten Methoden beinhalten.

Vererbung in einer Entwurfszeittextvorlage

Eine Entwurfszeittextvorlage ist eine Datei, für die Benutzerdefiniertes Tool auf TextTemplatingFileGenerator festgelegt wird. Die Vorlage generiert eine Ausgabedatei mit Code oder Text, die einen Teil des Visual Studio-Projekts bildet. Um die Ausgabedatei zu generieren, wird die Vorlage zuerst in eine Zwischenprogrammcodedatei übersetzt, die normalerweise nicht sichtbar ist. Das inherits-Attribut gibt die Basisklasse für den Zwischencode an.

Für eine Entwurfszeittextvorlage können Sie jede Basisklasse angeben, die von Microsoft.VisualStudio.TextTemplating.TextTransformation abgeleitet wird. Verwenden Sie die <#@assembly#>-Direktive, um die Assembly oder das Projekt zu laden, das die Basisklasse enthält.

Weitere Informationen finden Sie unter "Vererbung in Textvorlagen" im Blog von Gareth Jones.

Änderungsprotokoll

Datum	Versionsgeschichte	Grund
März 2011	Vom übergeordnetem Thema aufgeteilt. compilerOptions hinzugefügt. Link zu Blogeintrag für Textvorlagenvererbung hinzugefügt.	Informationsergänzung.