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

Wenn das - Attribut debugtrue ist, enthält die Zwischencodedatei Informationen, die den Debugger ermöglicht, die Position in der Vorlage genauer zu identifizieren, in der eine Unterbrechung oder eine Ausnahme aufgetreten ist.

Für Entwurfszeitvorlagen wird die Zwischencodedatei in das % TEMP%-Verzeichnis geschrieben.

Um eine Entwurfszeitvorlage im Debugger auszuführen, öffnen Sie das Kontextmenü des Textvorlage im Projektmappen-Explorer 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 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).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 inherits und hostspecific-Attribute zusammen verwenden, geben Sie host= " trueFromBase" in der abgeleiteten Klasse und " echten" host= das in der Basisklasse auf.Dies vermeidet eine doppelte Definition der Host-Eigenschaft 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.

Vorsicht
Wenn Sie die inherits und hostspecific-Attribute zusammen verwenden, geben Sie hostspecific= " trueFromBase" in der abgeleiteten Klasse und im host= an in der Basisklasse ", die" erfüllt sind.Dies vermeidet eine doppelte Definition der Host-Eigenschaft 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 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.

LinePragmas-Attribut

• Beispiel:
  linePragmas="false"

• Gültige Werte:
  true (Standardwert)

  false

Dieses Attribut auf false festlegen, entfernt die Tags, die die Zeilennummern innerhalb des generierten Codes identifizieren.Dies bedeutet, dass der Compiler alle Fehler meldet, indem er Zeilennummern des generierten Codes verwendet. Dies gibt Ihnen mehr Debugoptionen einstellen, wie Sie wählen können, um entweder die Textvorlage oder den generierten Code zu debuggen.

Dieses Attribut kann auch leichter, wenn Sie absolute Dateinamen in den Pragmas verursachen suchen, Zusammenführungen unter Quellcodeverwaltung ablenkend.

Sichtbarkeitsattribut

• Beispiel:
  visibility="internal"

• Gültige Werte:
  public (Standardwert)

  internal

In einer Laufzeittextvorlage legt dies das Sichtbarkeitsattribut der generierten Klasse fest.Standardmäßig ist die - Klasse Teil der öffentlichen APIs des Codes, aber, indem Sie visibility="internal" festlegen, können Sie sicherstellen, dass nur Ihr Code die Text-generierende Klasse verwenden kann.