Bloki formantów szablonów tekstowych

Artykuł
08/25/2023

Bloki sterujące umożliwiają pisanie kodu w szablonie tekstowym w celu zmiany danych wyjściowych. Istnieją trzy rodzaje bloków sterujących, które są rozróżniane przez nawiasy otwierające:

<# Standard control blocks #> może zawierać instrukcje.
<#= Expression control blocks #> może zawierać wyrażenia.
<#+ Class feature control blocks #> może zawierać metody, pola i właściwości.

Standardowy blok sterowania

Standardowe bloki sterujące zawierają instrukcje. Na przykład następujący standardowy blok pobiera nazwy wszystkich atrybutów w dokumencie XML:

<#@ 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);
       }
     }
#>

Możesz osadzić zwykły tekst wewnątrz instrukcji złożonej, takiej jak if lub for. Na przykład ten fragment generuje wiersz wyjściowy w każdej iteracji pętli:

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

Ostrzeżenie

Zawsze używaj elementu {...}, aby rozdzielić zagnieżdżone instrukcje zawierające osadzony zwykły tekst. Poniższy przykład może nie działać prawidłowo:

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

Zamiast tego należy uwzględnić {nawiasy klamrowe}, w następujący sposób:


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

Blok kontrolek wyrażeń

Bloki kontrolek wyrażeń służą do pisania ciągów w pliku wyjściowym. Na przykład w powyższym przykładzie można wydrukować nazwy atrybutów do pliku wyjściowego, modyfikując blok kodu w następujący sposób:

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

Blok sterowania cechami klasy

Bloki kontrolek funkcji klasy umożliwiają dodawanie metod, właściwości, pól, a nawet zagnieżdżonych klas do szablonu tekstowego. Najczęstszym zastosowaniem bloków funkcji klasy jest zapewnienie funkcji pomocnika dla kodu w innych częściach szablonu tekstu. Na przykład następujący blok funkcji klasy wielkich liter nazwy atrybutu (lub, jeśli nazwa zawiera biały znak, wielkich liter każdego słowa):

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

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

Uwaga

Blok sterowania cechami klasy nie może być zgodny ze standardowymi blokami sterującymi w tym samym pliku szablonu. Jednak to ograniczenie nie ma zastosowania do wyniku dyrektyw stosowania <#@include#> . Każdy dołączony plik może zawierać standardowe bloki, a następnie bloki funkcji klasy.

Możesz utworzyć funkcję, która generuje dane wyjściowe, osadzając bloki tekstu i wyrażenia wewnątrz bloku sterowania cechami klasy. Na przykład:

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

Tę funkcję można wywołać z bloku standardowego lub z innego bloku funkcji klasy:

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

Jak używać bloków sterujących

Cały kod we wszystkich blokach kontrolek standardowych i wyrażeń w jednym szablonie (łącznie ze wszystkim kodem w dołączonych szablonach) jest połączony w celu utworzenia TransformText() metody wygenerowanego kodu. (Aby uzyskać więcej informacji na temat dołączania innych szablonów tekstowych z dyrektywą include , zobacz T4 Dyrektywy szablonu tekstowego).

Podczas korzystania z bloków sterowania należy pamiętać o następujących kwestiach:

Język. Możesz użyć kodu w języku C# lub Visual Basic w szablonie tekstowym. Język domyślny to C#, ale można określić język Visual Basic z parametrem languagetemplate dyrektywy. (Aby uzyskać więcej informacji na temat template dyrektywy, zobacz T4 Dyrektywy szablonu tekstowego).

Język używany w blokach sterowania nie ma nic wspólnego z językiem ani formatem tekstu wygenerowanego w szablonie tekstowym. Język C# można wygenerować przy użyciu kodu Języka Visual Basic lub odwrotnie.

W danym szablonie tekstowym można używać tylko jednego języka, w tym wszystkich szablonów tekstowych uwzględninych w include dyrektywie.
Zmienne lokalne. Ponieważ cały kod w blokach kontrolek standardowych i wyrażeń w szablonie tekstowym jest generowany jako jedna metoda, należy upewnić się, że nie ma konfliktów z nazwami zmiennych lokalnych. Jeśli dołączasz inne szablony tekstowe, upewnij się, że nazwy zmiennych są unikatowe we wszystkich dołączonych szablonach. Jednym ze sposobów zapewnienia, że jest dodanie ciągu do każdej lokalnej nazwy zmiennej identyfikującej szablon tekstowy, w którym został zadeklarowany.

Dobrym pomysłem jest również zainicjowanie zmiennych lokalnych do rozsądnych wartości podczas ich deklarowania, szczególnie w przypadku dołączania wielu szablonów tekstu.
Zagnieżdżanie bloków sterowania. Bloki sterujące mogą nie być zagnieżdżone wewnątrz siebie. Przed otwarciem innego bloku kontrolnego należy zawsze przerwać działanie danego bloku kontrolnego. Na przykład poniżej pokazano, jak wydrukować jakiś tekst w bloku wyrażeń w ramach standardowego bloku sterowania.
```
<#
int x = 10;
while (x-- > 0)
{
#>
<#= x #>
<# } #>
```
Refaktoryzacji. Aby zachować krótkie i łatwe zrozumienie szablonów tekstu, zdecydowanie zaleca się unikanie powtarzalnego kodu przez uwzględnienie kodu wielokrotnego użytku w funkcjach pomocnika w blokach funkcji klasy lub przez utworzenie własnej klasy szablonu tekstu dziedziczonej z klasy Microsoft.VisualStudio.TextTemplating.TextTransformation.

Udostępnij za pośrednictwem