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. Existem três tipos de blocos de controlo, que se distinguem pelos seus parênteses de abertura:

• <# Standard control blocks #> pode conter declaraçõ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 incorporar texto sem formatação dentro de uma instrução composta, como if ou for. Por exemplo, este 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 para o 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ística de classe

Você pode usar blocos de controle de recurso de classe para adicionar métodos, propriedades, campos ou até mesmo classes aninhadas ao seu 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 coloca em maiúscula a primeira letra do nome do atributo (ou, se o nome contiver espaço em branco, coloca em maiúscula 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 incorporando blocos de texto e expressão dentro de um bloco de controle de recurso 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 expressão em um único modelo (incluindo todo o código nos 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 T4 Text Template Directives.)

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

• Idioma. Você pode usar o código C# ou Visual Basic em um modelo de texto. A linguagem 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 T4 Text Template Directives.)

  O idioma que você usa nos 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 na include diretiva.

• Variáveis locais. Como todo o código nos blocos de controle padrão e expressão em um modelo de texto é gerado como um único método, você deve certificar-se de que não há conflitos com os nomes das variáveis locais. Se você estiver incluindo outros modelos de texto, deverá certificar-se de que os nomes das variáveis sejam 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 ela foi declarada.

  Também é uma boa ideia inicializar suas variáveis locais para valores sensíveis ao declará-las, especialmente quando você estiver incluindo vários modelos de texto.

• Aninhamento de blocos de controle. Os blocos de controlo não podem estar aninhados uns nos outros. Você sempre deve encerrar um determinado bloco de controle antes de abrir outro. Por exemplo, a seguir 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 fatorando 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.