Kontrollblöcke für Textvorlagen

Kontrollblöcke ermöglichen das Schreiben von Code in die Textvorlage, um die Ausgabe zu verändern. Es gibt drei Arten von Kontrollblöcken, die anhand ihrer öffnenden eckigen Klammern unterschieden werden:

• <# Standard control blocks #> kann Anweisungen enthalten.

• <#= Expression control blocks #> kann Ausdrücke enthalten.

• <#+ Class feature control blocks #> kann Methoden, Felder und Eigenschaften enthalten.

Standardkontrollblock

Standardkontrollblöcke enthalten Anweisungen. Durch den folgenden Standardblock werden z. B. die Namen aller Attribute im XML-Dokument abgerufen:

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

<#
    List<string> allAttributes = new List<string>();
    XmlDocument xDoc = new XmlDocument();
    xDoc.Load(@"E:\CSharp\Overview.xml");
    XmlAttributeCollection attributes = xDoc.Attributes;
    if (attributes.Count > 0)
    {
       foreach (XmlAttribute attr in attributes)
       {
           allAtributes.Add(attr.Name);
       }
     }  
#>

Sie können Nur-Text in einer Verbundanweisung einbetten, z. B. if oder for. Dieses Fragment generiert z. B. eine Ausgabezeile in jeder Schleifeniteration:

<#
       foreach (XmlAttribute attr in attributes)
       {
#>
Found another one!
<#
           allAtributes.Add(attr.Name);
       }
#>

Warnung

Verwenden Sie immer {...}, um geschachtelte Anweisungen zu begrenzen, die eingebetteten Nur-Text enthalten.Das folgende Beispiel funktioniert möglicherweise nicht ordnungsgemäß:

<# if (ShouldPrint) #> Some text. -- WRONG

Stattdessen sollten Sie {geschweifte Klammern} wie folgt einschließen:

 
<#
 if (ShouldPrint)
 {   //  "{" REQUIRED
#>
Some text.
<#
 } 
#>

Ausdruckskontrollblock

Ausdruckskontrollblöcke werden für Code verwendet, der in die Ausgabedatei zu schreibende Zeichenfolgen bereitstellt. Im obigen Beispiel können Sie z. B. die Namen der Attribute in die Ausgabedatei ausgeben, indem Sie den Codeblock wie folgt ändern:

<#
    XmlDocument xDoc = new XmlDocument();
    xDoc.Load(@"E:\CSharp\Overview.xml");
    XmlAttributeCollection attributes = xDoc.Attributes;
    if (attributes != null)
    {
       foreach (XmlAttribute attr in attributes)
       { 
#> 
        <#= attr.Name #> 
<#
       }
    }
#>

Klassenfunktionskontrollblock

Klassenfunktionskontrollblöcke können verwendet werden, um der Textvorlage Methoden, Eigenschaften, Felder oder sogar geschachtelte Klassen hinzuzufügen. Am häufigsten werden Klassenfunktionsblöcke zum Bereitstellen von Hilfsfunktionen für Code in anderen Teilen der Textvorlage verwendet. Durch den folgenden Klassenfunktionsblock wird z. B. der erste Buchstabe des Attributnamens groß geschrieben (oder der erste Buchstabe jedes Worts, wenn der Name Leerstellen enthält):

<#@ import namespace="System.Globalization" #>

<#+
    private string FixAttributeName(string name)
    {
        return CultureInfo.CurrentCulture.TextInfo.ToTitleCase(name);
    }
#>

Hinweis

Auf einen Klassenfunktions-Kontrollblock dürfen innerhalb einer Vorlagendatei keine standardmäßigen Kontrollblöcke folgen.Diese Einschränkung gilt jedoch nicht für das Ergebnis der Verwendung von <#@include#>-Direktiven.Jede eingeschlossene Datei kann über Standardblöcke verfügen, auf die Klassenfunktionsblöcke folgen.

Sie können eine Funktion erstellen, mit der Ausgaben generiert werden. Betten Sie dazu Text- und Ausdrucksblöcke in einen Klassenfunktions-Kontrollblock ein. Beispiele:

<#+
    private string OutputFixedAttributeName(string name)
    {
#>
 Attribute:  <#= CultureInfo.CurrentCulture.TextInfo.ToTitleCase(name) #>
<#+  // <<< Notice that this is also a class feature block.
    }
#>

Sie können diese Funktion von einem Standardblock oder von einem anderen Klassenfunktionsblock aus aufrufen:

<# foreach (Attribute attribute in item.Attributes)
{
  OutputFixedAttributeName(attribute.Name);
}
#>

Verwenden von Kontrollblöcken

Der gesamte Code in allen Standard- und Ausdruckskontrollblöcken in einer Vorlage (einschließlich des gesamten Codes für eingeschlossene Vorlagen) wird kombiniert, um die TransformText()-Methode des generierten Codes zu bilden. (Weitere Informationen zum Einschließlich anderer Textvorlagen mit der include-Direktive finden Sie unter T4-Textvorlagendirektiven.)

Beachten Sie bei der Verwendung von Kontrollblöcken die folgenden Hinweise:

• Sprache: Sie können in einer Textvorlage C#- oder Visual Basic-Code verwenden. Die Standardsprache ist C#, Sie können mit dem language-Parameter der template-Direktive aber Visual Basic angeben. (Weitere Informationen zur template-Direktive finden Sie unter T4-Textvorlagendirektiven.)

  Die in Kontrollblöcken verwendete Sprache hat keinen Einfluss auf die Sprache oder das Format des Texts, den Sie in einer Textvorlage generieren. Sie können mit Visual Basic-Code C# generieren oder umgekehrt.

  In einer Textvorlage und allen mit der include-Direktive eingeschlossenen Textvorlagen kann nur eine Sprache verwendet werden.

• Lokale Variablen. Da der gesamte Code für die Standard- und Ausdruckskontrollblöcke in einer Textvorlage als nur eine Methode generiert wird, müssen Sie sicherstellen, dass keine Konflikte mit den Namen lokaler Variablen entstehen. Wenn Sie andere Textvorlagen einschließen, müssen Sie sicherstellen, dass Variablennamen in allen eingeschlossenen Vorlagen eindeutig sind. Zu diesem Zweck können Sie dem Namen jeder lokalen Variable eine Zeichenfolge zur Angabe der Textvorlage hinzufügen, in der sie deklariert wurde.

  Es empfiehlt sich auch, die lokalen Variablen beim Deklarieren mit sinnvollen Werten zu initialisieren. Dies gilt besonders dann, wenn Sie mehrere Textvorlagen einschließen.

• Schachteln von Kontrollblöcken. Kontrollblöcke können nicht ineinander geschachtelt werden. Jeder Kontrollblock muss beendet werden, bevor Sie einen anderen Kontrollblock beginnen. Das folgende Beispiel zeigt, wie Text in einem Ausdrucksblock als Teil eines Standardkontrollblocks ausgegeben wird.

  <# 
  int x = 10;
  while (x-- > 0)
  {
  #>
  <#= x #>
  <# } #>
  

• Umgestaltung. Um die Textvorlagen kurz und leicht verständlich zu halten, sollten Sie sich wiederholenden Code vermeiden, indem Sie den wiederverwendbaren Code in Hilfsfunktionen in Klassenfunktionsblöcken zerlegen oder eine eigene Textvorlagenklasse erstellen, die von der Microsoft.VisualStudio.TextTemplating.TextTransformation-Klasse erbt.