Freigeben über

Steuerblöcke für Textvorlagen

Mithilfe von Steuerelementblöcken können Sie Code in Ihrer Textvorlage schreiben, um die Ausgabe zu variieren. Es gibt drei Arten von Steuerelementblöcken, die durch ihre öffnenden 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

Standard-Kontrollblöcke enthalten Anweisungen. Der folgende Standardblock ruft beispielsweise die Namen aller Attribute im XML-Dokument ab:

<#@ 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 einfachen Text in eine zusammengesetzte Anweisung wie if oder for einbetten. Beispielsweise generiert dieses Fragment 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 kennzeichnen, die eingebetteten reinen Text enthalten. Das folgende Beispiel funktioniert möglicherweise nicht ordnungsgemäß:

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

Stattdessen sollten Sie {geschweifte Klammern} wie folgt verwenden:


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

Ausdruckssteuerelementblock

Ausdruckssteuerungsblöcke werden für Code verwendet, der Zeichenfolgen erzeugt, die in die Ausgabedatei geschrieben werden sollen. Mit dem obigen Beispiel können Sie beispielsweise die Namen der Attribute in der Ausgabedatei drucken, 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 #><#
       }
    }
#>

Klassenfeature-Steuerelementblock

Sie können Klassenfeature-Steuerelementblöcke verwenden, um Ihrer Textvorlage Methoden, Eigenschaften, Felder oder sogar geschachtelte Klassen hinzuzufügen. Die häufigste Verwendung von Klassenfeatureblöcken besteht darin, Hilfsfunktionen für Code in anderen Teilen der Textvorlage bereitzustellen. Mit dem folgenden Klassenfeatureblock wird beispielsweise der erste Buchstabe des Attributnamens großgeschrieben (oder wenn der Name Leerzeichen enthält, wird der erste Buchstabe jedes Worts großgeschrieben):

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

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

Hinweis

Ein Klassenfeature-Steuerelementblock darf nicht von Standardsteuerelementblöcken in derselben Vorlagendatei gefolgt werden. Diese Einschränkung gilt jedoch nicht für das Ergebnis der Verwendung von <#@include#>-Direktiven. Jede enthaltene Datei kann Standardblöcke aufweisen, gefolgt von Klassenfeatureblöcken.

Sie können eine Funktion erstellen, die eine Ausgabe generiert, indem Sie Text- und Ausdrucksblöcke in einen Klassenfeature-Steuerelementblock einbetten. Beispiel:

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

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

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

So verwenden Sie Steuerungsblöcke

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

Beachten Sie bei der Verwendung von Steuerelementblöcken die folgenden Überlegungen:

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

    Die Sprache, die Sie in Steuerelementblöcken verwenden, hat nichts mit der Sprache oder dem Format des Texts zu tun, den Sie in einer Textvorlage generieren. Sie können C# mithilfe von Visual Basic-Code generieren oder umgekehrt.

    Sie können nur eine Sprache in einer bestimmten Textvorlage verwenden, einschließlich aller Textvorlagen, die Sie in die include Direktive aufnehmen.

  • Lokale Variablen. Da der gesamte Code in den Standard- und Ausdruckssteuerelementblöcken in einer Textvorlage als einzelne Methode generiert wird, sollten Sie sicherstellen, dass es keine Konflikte mit den Namen lokaler Variablen gibt. Wenn Sie andere Textvorlagen einschließen, müssen Sie sicherstellen, dass Variablennamen in allen enthaltenen Vorlagen eindeutig sind. Eine Möglichkeit, dies sicherzustellen, besteht darin, jedem lokalen Variablennamen eine Zeichenfolge hinzuzufügen, die die Textvorlage identifiziert, in der sie deklariert wurde.

    Außerdem empfiehlt es sich, die lokalen Variablen beim Deklarieren auf sinnvolle Werte zu initialisieren, insbesondere wenn Sie mehrere Textvorlagen einschließen.

  • Verschachtelung von Steuerblöcken. Steuerelementblöcke werden möglicherweise nicht miteinander verschachtelt. Sie müssen immer einen bestimmten Steuerelementblock beenden, bevor Sie eine andere öffnen. Im folgenden Beispiel wird gezeigt, wie Text in einem Ausdrucksblock als Teil eines Standardsteuerelementblocks gedruckt wird.

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

  • Umgestaltung. Damit Ihre Textvorlagen kurz und einfach zu verstehen sind, wird dringend empfohlen, sich wiederholenden Code zu vermeiden, indem Sie den wiederverwendbaren Code entweder in Hilfsfunktionen in Klassenfeatureblöcken aufteilen oder eine eigene Textvorlagenklasse erstellen, die von der Microsoft.VisualStudio.TextTemplating.TextTransformation-Klasse erbt.

  • Last updated on