Sdílet prostřednictvím

Řídicí bloky textových šablon

  • Článek

Řídicí bloky umožňují psát kód v textové šabloně, aby se výstup mohl lišit. Existují tři druhy řídicích bloků, které jsou odlišeny jejich levými závorkami:

  • <# Standard control blocks #> může obsahovat příkazy.

  • <#= Expression control blocks #> může obsahovat výrazy.

  • <#+ Class feature control blocks #> může obsahovat metody, pole a vlastnosti.

Standardní řídicí blok

Standardní řídicí bloky obsahují příkazy. Například následující standardní blok získá názvy všech atributů v dokumentu 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);
       }
     }
#>

Prostý text můžete vložit do složeného příkazu, například if nebo for. Tento fragment například vygeneruje výstupní řádek v každé iteraci smyčky:

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

Upozorňující

K oddělovači vnořených příkazů obsahujících vložený prostý text vždy používejte {...}. Následující příklad nemusí správně fungovat:

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

Místo toho byste měli zahrnout {braces}, a to takto:


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

Blok ovládacího prvku výrazu

Řídicí bloky výrazů se používají pro kód, který poskytuje řetězce, které se mají zapisovat do výstupního souboru. Například s výše uvedeným příkladem můžete vytisknout názvy atributů do výstupního souboru tak, že upravíte blok kódu následujícím způsobem:

<#
    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 řízení funkcí třídy

Řídicí bloky funkcí třídy můžete použít k přidání metod, vlastností, polí nebo dokonce vnořených tříd do textové šablony. Nejběžnějším použitím bloků funkcí tříd je poskytování pomocných funkcí pro kód v jiných částech textové šablony. Například následující blok funkce třídy velká písmena názvu atributu (nebo pokud název obsahuje prázdné znaky, velká písmena každého slova):

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

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

Poznámka:

Za blokem řízení funkcí třídy nesmí následovat standardní řídicí bloky ve stejném souboru šablony. Toto omezení se však nevztahuje na výsledek direktiv using <#@include#> . Každý zahrnutý soubor může obsahovat standardní bloky následované bloky funkcí třídy.

Funkci, která generuje výstup, můžete vytvořit vložením bloků textu a výrazů do řídicího bloku funkce třídy. Příklad:

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

Tuto funkci můžete volat ze standardního bloku nebo z jiného bloku funkce třídy:

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

Jak používat řídicí bloky

Veškerý kód ve všech standardních blocích ovládacích prvků a řídicích bloků výrazů v jedné šabloně (včetně veškerého kódu v zahrnutých šablonách) se zkombinuje a vytvoří TransformText() metodu vygenerovaného kódu. (Další informace o zahrnutí dalších textových šablon s direktivou include naleznete v tématu Direktivy textových šablon T4.)

Při použití řídicích bloků byste měli mít na paměti následující aspekty:

  • Jazyk. V textové šabloně můžete použít kód jazyka C# nebo Visual Basic. Výchozí jazyk je jazyk C#, ale jazyk Visual Basic můžete zadat pomocí language parametru direktivy template . (Další informace o direktivě template naleznete v tématu T4 – direktivy textových šablon.)

    Jazyk, který používáte v řídicích blocích, nemá nic společného s jazykem nebo formátem textu, který vygenerujete v textové šabloně. Jazyk C# můžete vygenerovat pomocí kódu jazyka Visual Basic nebo naopak.

    V dané textové šabloně můžete použít pouze jeden jazyk, včetně všech textových šablon, které do direktivy include zahrnete.

  • Místní proměnné. Vzhledem k tomu, že veškerý kód ve standardních blocích ovládacích prvků a řídicích bloků výrazů v textové šabloně je generován jako jedna metoda, měli byste mít jistotu, že neexistují žádné konflikty s názvy místních proměnných. Pokud zahrnete další textové šablony, musíte zajistit, aby názvy proměnných byly jedinečné pro všechny zahrnuté šablony. Jedním ze způsobů, jak zajistit, aby se do každého názvu místní proměnné přidal řetězec identifikující textovou šablonu, ve které byla deklarována.

    Je také vhodné inicializovat místní proměnné na rozumné hodnoty, když je deklarujete, zejména když zahrnete více textových šablon.

  • Vnoření řídicích bloků Řídicí bloky nemusí být vnořené do sebe. Před otevřením jiného řídicího bloku musíte vždy ukončit daný řídicí blok. Následující příklad ukazuje, jak vytisknout nějaký text v bloku výrazu jako součást standardního řídicího bloku.

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

  • Refactoring. Aby byly textové šablony krátké a snadno pochopitelné, důrazně doporučujeme vyhnout se opakovanému kódu tím, že do pomocných funkcí v blocích funkcí třídy založíte opakovaně použitelný kód nebo vytvoříte vlastní třídu textové šablony, která dědí z Třídy Microsoft.VisualStudio.TextTemplating.TextTransformation.