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"] [visibility="internal"] [linePragmas="false"] #>

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 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. "False" ist der Standardwert.

Wenn das debug-Attribut true ist, enthält die Zwischencodedatei Informationen, mit denen der Debugger genauer 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 eine Entwurfszeitvorlage im Debugger ausführen, speichern Sie die Textvorlage, öffnen Sie das Kontextmenü der Textvorlage im Projektmappen-Explorer, und wählen Sie T4-Vorlage debuggen aus.

hostspecific-Attribut

• Beispiel:

  hostspecific="true"
  

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

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 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. Sie kann auf Entwurfszeitvorlagen, jedoch nicht auf Laufzeitvorlagen angewendet werden.

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).GetCOMService(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 #>

Wenn Sie die Attribute inherits und hostspecific zusammen verwenden, geben Sie host="trueFromBase" in der abgeleiteten Klasse sowie host="true" in der Basisklasse an. Dies vermeidet eine doppelte Definition der Eigenschaft Host im generierten Code.

language-Attribut

• Beispiel:
  language="VB"

• Gültige Werte:
  C# (Standardwert)

  VB

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 Laufzeittextgenerierung mithilfe von 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.

Warnung

Wenn Sie die Attribute inherits und hostspecific zusammen verwenden, geben Sie hostspecific="trueFromBase" in der abgeleiteten Klasse sowie host="true" in der Basisklasse an.Dies vermeidet eine doppelte Definition der Eigenschaft Host im generierten Code.

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 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.

LinePragmas-Attribut

• Beispiel:
  linePragmas="false"

• Gültige Werte:
  true (Standardwert)

  false

Wenn dieses Attribut auf "false" festgelegt ist, werden die Tags entfernt, die die Zeilennummern im generierten Codes identifizieren. Dies bedeutet, dass der Compiler alle Fehler anhand der Zeilennummern des generierten Codes meldet. Damit erhalten Sie mehr Debugoptionen, da Sie entweder die Textvorlage oder den generierten Code debuggen können.

Dieses Attribut ist auch hilfreich, wenn Sie erkennen, dass die absoluten Dateinamen in Pragmas irritierende Zusammenführungen unter Quellcodeverwaltung verursachen.

Sichtbarkeitsattribut

• Beispiel:
  visibility="internal"

• Gültige Werte:
  public (Standardwert)

  internal

In einer Laufzeittextvorlage wird hiermit das Sichtbarkeitsattribut der generierten Klasse festgelegt. Standardmäßig ist die Klasse Teil der öffentliche API des Codes, aber indem Sie visibility="internal" festlegen, können Sie sicherstellen, dass nur der Code die textgenerierende Klasse verwenden kann.