Blocos de controle de modelo de texto

Os blocos de controle permitem que você escreva código em seu modelo de texto para variar a saída. Há três tipos de blocos de controle, que são diferenciados por seus colchetes de abertura:

• <# Standard control blocks #> pode conter instruções.

• <#= Expression control blocks #> pode conter expressões.

• <#+ Class feature control blocks #> pode conter métodos, campos e propriedades.

Bloco de controle padrão

Os blocos de controle padrão contêm instruções. Por exemplo, o seguinte bloco padrão obtém os nomes de todos os atributos no documento 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);
       }
     }
#>

Você pode inserir texto sem formatação dentro de uma instrução composta, como if ou for. Por exemplo, esse fragmento gera uma linha de saída em cada iteração de loop:

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

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

Bloco de controle de expressão

Os blocos de controle de expressão são usados para código que fornece cadeias de caracteres a serem gravadas no arquivo de saída. Por exemplo, com o exemplo acima, você pode imprimir os nomes dos atributos no arquivo de saída modificando o bloco de código da seguinte maneira:

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

Bloco de controle de características de classe

Você pode usar blocos de controle de recursos de classe para adicionar métodos, propriedades, campos ou até mesmo classes aninhadas ao modelo de texto. O uso mais comum de blocos de recursos de classe é fornecer funções auxiliares para código em outras partes do modelo de texto. Por exemplo, o bloco de recursos de classe a seguir capitaliza a primeira letra do nome do atributo (ou, se o nome contiver espaço em branco, ele capitaliza a primeira letra de cada palavra):

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

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

Você pode criar uma função que gera saída inserindo blocos de texto e expressão dentro de um bloco de controle de recursos de classe. Por exemplo:

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

Você pode chamar essa função de um bloco padrão ou de outro bloco de recursos de classe:

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

Como usar blocos de controle

Todo o código em todos os blocos de controle padrão e de expressão em um único modelo (incluindo todo o código em modelos incluídos) é combinado para formar o TransformText() método do código gerado. (Para obter mais informações sobre como incluir outros modelos de texto com a include diretiva, consulte diretivas de modelo de texto T4.)

Você deve ter em mente as seguintes considerações ao usar blocos de controle:

• Idioma. Você pode usar código C# ou Visual Basic em um modelo de texto. O idioma padrão é C#, mas você pode especificar o Visual Basic com o language parâmetro da template diretiva. (Para obter mais informações sobre a template diretiva, consulte diretivas de modelo de texto T4.)

  O idioma que você usa em blocos de controle não tem nada a ver com o idioma ou o formato do texto gerado em um modelo de texto. Você pode gerar C# usando o código do Visual Basic ou vice-versa.

  Você pode usar apenas um idioma em um determinado modelo de texto, incluindo todos os modelos de texto incluídos com a include diretiva.

• Variáveis locais. Como todo o código nos blocos de controle padrão e de expressão em um modelo de texto é gerado como um único método, você deve garantir que não haja conflitos com os nomes das variáveis locais. Se você estiver incluindo outros modelos de texto, verifique se os nomes de variáveis são exclusivos em todos os modelos incluídos. Uma maneira de garantir isso é adicionar uma cadeia de caracteres a cada nome de variável local identificando o modelo de texto no qual ele foi declarado.

  Também é uma boa ideia inicializar suas variáveis locais para valores sensatos quando você as declara, especialmente quando você está incluindo vários modelos de texto.

• Aninhamento de blocos de controle. Os blocos de controle não podem estar aninhados entre si. Você sempre deve encerrar um determinado bloco de controle antes de abrir outro. Por exemplo, o seguinte mostra como imprimir algum texto em um bloco de expressão como parte de um bloco de controle padrão.

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

• Refatoração. Para manter seus modelos de texto curtos e fáceis de entender, é altamente recomendável que você evite código repetitivo ao considerar o código reutilizável em funções auxiliares em blocos de recursos de classe ou criando sua própria classe de modelo de texto que herda da classe Microsoft.VisualStudio.TextTemplating.TextTransformation.