Escrever um modelo de texto T4

Artigo
08/01/2011

Um modelo de texto contém o texto que será gerado a partir dele. Por exemplo, um modelo que cria uma página da web irá conter "<html> …" e todas as outras partes padrão de uma página HTML. Inserido no modelo são blocos de controle de, que são fragmentos de código de programa. Blocos de controle fornecem valores de variáveis e permitir que partes do texto a ser condicional e repetidos.

Essa estrutura facilita desenvolver, pois você pode iniciar com um protótipo do arquivo gerado e inserir incrementalmente de blocos de controle para variam o resultado de um modelo.

Modelos de texto são compostos das seguintes partes:

As diretivas -elementos que controlam como o modelo é processado.
Blocos de texto - conteúdo que é copiada diretamente para a saída.
Blocos de controle -código que insere os valores de variáveis no texto e controles condicionais ou repetidas de partes do texto de programa.

Para testar os exemplos neste tópico, copiá-los em um arquivo de modelo conforme descrito em Geração de código de tempo de design usando modelos de texto T4. Após editar o arquivo de modelo, salve-o e, em seguida, inspecionar a saída .txt arquivo.

Diretivas

Diretivas de modelo de texto fornecem instruções gerais para o mecanismo de modelagem de texto sobre como gerar o código de transformação e o arquivo de saída.

Por exemplo, a diretiva a seguir especifica que o arquivo de saída deve ter uma extensão. txt:

<#@ output extension=".txt" #>

Para obter mais informações sobre diretivas, consulte T4 Diretivas de modelo de texto.

Blocos de texto

Um bloco de texto insere o texto diretamente no arquivo de saída. Não há nenhuma formatação especial para blocos de texto. Por exemplo, o modelo de texto a seguir produzirá um arquivo de texto que contém a palavra "Hello":

<#@ output extension=".txt" #>
Hello

Blocos de controle

Os blocos de controle são seções de código de programa que são usadas para transformar os modelos. O idioma padrão é C#, mas para usar Visual Basic, você pode escrever essa diretiva no início do arquivo:

<#@ template language="VB" #>

O idioma no qual você escreve o código nos blocos de controle não está relacionado ao idioma do texto que é gerado.

Blocos de controle padrão

Um bloco de controle padrão é uma seção de código de programa que gera a parte do arquivo de saída.

Você pode combinar qualquer número de blocos de texto e blocos de controle padrão em um arquivo de modelo. No entanto, você pode colocar um bloco de controle dentro de outro. Cada bloco de controle padrão é delimitado por símbolos <# ... #>.

Por exemplo, o seguinte bloco de controle e o bloco de texto causam o arquivo de saída conter a linha "0, 1, 2, 3, 4 Hello!":

<#
    for(int i = 0; i < 4; i++)
    {
        Write(i + ", ");
    }
    Write("4");

#> Hello!

Em vez de usar explícita Write() instruções, é possível intercalar o texto e código. O exemplo a seguir imprime "Olá!". quatro vezes:

<#
    for(int i = 0; i < 4; i++)
    {
#>
Hello!
<#
    } 
#>

Você pode inserir um texto Bloquear sempre que uma Write(); instrução seria permitida no código.

Observação
Quando você incorpora um bloco de texto dentro de uma declaração composta como, por exemplo, um loop ou condicional, sempre use chaves {...} para conter o bloco de texto.

Blocos de controle de expressão

Um bloco de controle da expressão avalia uma expressão e o converte em uma seqüência de caracteres. Isso é inserido no arquivo de saída.

Blocos de controle de expressão são delimitado pelos símbolos<#= ... #>

Por exemplo, o seguinte bloco de controle faz com que o arquivo de saída conter "5":

<#= 2 + 3 #>

Observe que o símbolo de abertura tem três caracteres "< # =".

A expressão pode incluir qualquer variável que está no escopo. Por exemplo, este bloco imprime as linhas com números:

<#@ output extension=".txt" #>
<#
    for(int i = 0; i < 4; i++)
    {
#>
This is hello number <#= i+1 #>: Hello!
<#
    } 
#>

Blocos de controle de recurso de classe

Um bloco de controle de recurso de classe define as propriedades, métodos ou qualquer outro código que não deve ser incluído na transformação principal. Blocos de recurso de classe são freqüentemente usados para funções auxiliares. Normalmente, os blocos de recurso de classe são colocados em arquivos separados para que eles possam ser incluídos por mais de um modelo de texto.

Blocos de controle de recurso de classe são delimitados por símbolos<#+ ... #>

Por exemplo, o arquivo de modelo a seguir declara e usa um método:

<#@ output extension=".txt" #>
Squares:
<#
    for(int i = 0; i < 4; i++)
    {
#>
    The square of <#= i #> is <#= Square(i+1) #>.
<#
    } 
#>
That is the end of the list.
<#+   // Start of class feature block
private int Square(int i)
{
    return i*i;
}
#>

Recursos de classe devem ser colocados no final do arquivo no qual são gravados. Entretanto, você pode <#@include#> um arquivo que contém um recurso de classe, mesmo se o include diretiva é seguida de blocos padrão e o texto.

Para obter mais informações sobre os blocos de controle, consulte T4 Blocos de controle de modelo de texto.

Blocos de recurso de classe podem conter blocos de texto

Você pode escrever um método que gera o texto. Por exemplo:

List of Squares:
<#
   for(int i = 0; i < 4; i++)
   {  WriteSquareLine(i); }
#>
End of list.
<#+   // Class feature block
private void WriteSquareLine(int i)
{
#>
   The square of <#= i #> is <#= i*i #>.
<#   
}
#>

É particularmente útil colocar um método que gera o texto em um arquivo separado que pode ser incluído por mais de um modelo.

Usando definições externas

Conjuntos de Módulos (Assemblies)

Os blocos de código do modelo podem usar tipos definidos usados com mais freqüência.NET assemblies como, por exemplo, System. dll. Além disso, você pode referenciar outros.NET assemblies ou seus próprios assemblies. Você pode fornecer um nome de caminho ou nome de alta segurança de um assembly:

<#@ assembly name="System.Xml" #>

Você deve usar nomes de caminho absoluto ou usar nomes de macro padrão no nome do caminho. Por exemplo:

<#@ assembly name="$(SolutionDir)library\MyAssembly.dll" #>

Para obter uma lista de macros, consulte Macros para construir comandos e propriedades.

A diretiva de assembly não tem efeito em um pré-processado o modelo de texto.

Para obter mais informações, consulte T4 Diretiva de Assembly.

Namespaces

A diretiva de importação é igual a using cláusula C# ou o imports cláusula Visual Basic. Ele permite que você consulte tipos no seu código sem usar um nome totalmente qualificado:

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

Você pode usar quantas assembly e import diretivas como desejar. Você deve colocá-los antes de blocos de texto e de controle.

Para obter mais informações, consulte T4 a diretiva de importação.

Incluindo o código e texto

O include diretiva insere o texto de outro arquivo de modelo. Por exemplo, essa diretiva insere o conteúdo do test.txt.

<#@ include file="c:\test.txt" #>

O conteúdo incluído é processado como se fosse parte do modelo de texto incluindo. No entanto, você pode incluir um arquivo que contém um bloco de recurso de classe <#+...#> , mesmo se a diretiva de inclusão é seguida pelo texto comum e de controle padrão blocos.

Para obter mais informações, consulte T4 Diretiva de inclusão.

Métodos de utilitário

Há vários métodos, como Write() que estão sempre disponíveis para você em um bloco de controle. Eles incluem métodos para ajudá-lo a saída de recuo e para relatar erros.

Você também pode escrever seu próprio conjunto de métodos de utilitário.

Para obter mais informações, consulte T4 Métodos de utilitário do modelo de texto.

Transformação de dados e modelos

O aplicativo mais úteis para um modelo de texto é gerar o material com base no conteúdo de uma fonte como, por exemplo, um modelo, o banco de dados ou o arquivo de dados. Seu modelo extrai e reformata os dados. Uma coleção de modelos pode transformar a tal fonte de em vários arquivos.

Há várias abordagens para ler o arquivo de origem.

Ler um arquivo do modelo de texto. Esta é a maneira mais simples de obter dados para o modelo:

<#@ import namespace="System.IO" #>
<# string fileContent = File.ReadAllText(@"C:\myData.txt"); ...

Carregar um arquivo como um modelo navegável. Um método mais eficiente é ler os dados como um modelo, seu código de modelo de texto pode navegar. Por exemplo, você pode carregar um arquivo XML e navegar por ela com expressões XPath. Você também pode usar xsd. exe para criar um conjunto de classes com o qual você pode ler os dados XML.

Edite o arquivo de modelo em um diagrama ou o formulário. Ferramentas de linguagem específica do domínio fornece ferramentas que permitem que você editar um modelo como um diagrama ou formulário do Windows. Isso facilita discutir o modelo com usuários do aplicativo gerado. Ferramentas de linguagem específica do domíniotambém cria um conjunto de classes com rigidez de tipos que refletem a estrutura do modelo. Para obter mais informações, consulte Using Text Templates in Domain-Specific Language Solutions.

Usar um modelo UML. Você pode gerar código de um modelo UML. Isso tem a vantagem de que o modelo pode ser editado como um diagrama de uma notação familiar. Além disso, é necessário que criar o diagrama. Para obter mais informações, consulte Como: Gerar arquivos a partir de um modelo UML.

Caminhos de arquivo relativos

Se você deseja fazer referência a um arquivo em um local em relação ao modelo de texto, use this.Host.ResolvePath(). Você também deve definir hostspecific="true" na template diretiva:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ import namespace="System.IO" #>
<#
 // Find a path within the same project as the text template:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of MyFile.txt is:
<#= myFile #>

Você também pode obter outros serviços que são fornecidos pelo host. Para obter mais informações, consulte Acessando Visual Studio ou outros Hosts a partir de um modelo de texto T4.

Modelos de texto executar em um AppDomain separado

Você deve estar ciente de que um modelo de texto é executado em um AppDomain separado do aplicativo principal. Na maioria dos casos isso não é importante, mas você poderá descobrir as restrições em determinados casos complexos. Por exemplo, se você quiser passar dados dentro ou fora do modelo de um serviço separado, o serviço deve fornecer uma API serializável.

Edição de modelos

Editores de texto especializado modelo podem ser baixados na Galeria Online do Extension Manager. Sobre o Ferramentas menu, clique em Extension Manager. Clique em Galeria Onlinee em seguida, use a ferramenta de pesquisa.

Tópicos relacionados

Tarefa	Tópico
Escrevendo um modelo.	Diretrizes para a criação de modelos de texto T4
Gere o texto usando o código de programa.	Escrever um modelo de texto T4
Gerar arquivos em um Visual Studio solução.	Geração de código de tempo de design usando modelos de texto T4
Executar a geração de texto fora Visual Studio.	Gerando arquivos com o utilitário TextTransform
Transforme seus dados na forma de uma linguagem específica do domínio.	Using Text Templates in Domain-Specific Language Solutions
Processadores de diretriz para transformar suas próprias fontes de dados de gravação.	Personalizando a transformação de texto T4

Histórico de alterações

Date	History	Motivo
Março de 2011	Use macros na diretiva de Assembly.	Comentários do cliente.

Março de 2011

Use macros na diretiva de Assembly.

Comentários do cliente.

Compartilhar via