Geração de código de tempo de design usando modelos de texto T4

Artigo
02/25/2013

Os modelos de tempo de design de texto T4 permitem que você gerar o código de programa e outros arquivos em Visual Studio para seu projeto.normalmente, você escreve os modelos de modo que variem o código que geram de acordo com dados de um modelo.Um modelo é um arquivo ou um banco de dados que contém as informações sobre os seus requisitos de aplicativo.

Por exemplo, você poderia ter um modelo que define um fluxo de trabalho, como uma tabela ou um diagrama.O modelo, você pode produzir o software que executa o fluxo de trabalho.Quando os requisitos de usuários mudarem, é fácil discutir o novo fluxo de trabalho com os usuários.Regenerar o código de fluxo de trabalho é mais confiável de atualizar manualmente o código.

Observação
Um modelo é uma fonte de dados que descreve um aspecto específico de um aplicativo.Pode ser qualquer formulário, em qualquer tipo de arquivo ou do banco de dados.Não tem que estar em qualquer formulário específico, como um modelo modelo ou específica de domínio de UML da linguagem.Os modelos são típicos na forma de tabelas ou arquivos XML.

Você provavelmente já familiar com a geração de código.Quando você define recursos em .resx arquivo em sua solução de Visual Studio , um conjunto de classes e métodos são gerados automaticamente.O arquivo de recursos torna mais fácil e mais confiável para editar os recursos do que seria se você tivesse que editar as classes e métodos.Com modelos de texto, você pode gerar código da mesma forma de uma fonte de seu próprio design.

Um modelo de texto contém uma mistura de texto que você deseja gerar, e o código de programa que gera quatro variáveis de texto.O código de programa e permite que você repita ou omitir condicional partes de texto gerado.O texto gerado pode ser próprio código de programa que fará parte do seu aplicativo.

Criando um modelo em tempo de design de texto T4

Para criar um modelo T4 tempo de design no Visual Studio

Crie um projeto de Visual Studio , ou abra um arquivo existente.

Por exemplo, no menu de Arquivo , escolha Novo, Projeto.
Adicione um arquivo de modelo de texto a seu projeto e dê-lhe um nome que possui a extensão .tt.

Para fazer isso, em Gerenciador de Soluções, no menu de atalho do seu projeto, escolha Adicionar, Novo Item.Em a caixa de diálogo Modelo de texto selecione de Adicionar novo item do painel médio.

Observe que a propriedade de Ferramenta Personalizada do arquivo é TextTemplatingFileGenerator.
Abra o arquivo.Ainda conterá as diretivas a seguir:
```
<#@ template hostspecific="false" language="C#" #>
<#@ output extension=".txt" #>
```
Se você adicionou o modelo para um projeto de Visual Basic , o atributo de idioma será “VB”.
Adicionar algum texto no final do arquivo.Por exemplo:
```
Hello, world!
```
Salve o arquivo.

Você pode ver uma caixa de mensagem de Alerta de Segurança que pede que você confirme que você deseja executar o modelo.Clique em OK.
Em Gerenciador de Soluções, expanda o nó do arquivo de modelo e você verá um arquivo que possui a extensão .txt.O arquivo contém o texto gerado do modelo.

Observação

Se seu projeto é um projeto Visual Basic, você deve clicar Mostrar todos os arquivos para ver o arquivo de saída.

Observação
Se seu projeto é um projeto Visual Basic, você deve clicar Mostrar todos os arquivos para ver o arquivo de saída.

regenerando o código

Um modelo será executado, gerando o arquivo subsidiário, em qualquer um dos seguintes casos:

Edite o modelo e alterar o foco em uma janela diferente de Visual Studio .
Salve o modelo.
Clique Transformar Todos os Modelos no menu de Compilar .Isso fará com que todos os modelos na solução de Visual Studio .
Em Gerenciador de Soluções, no menu de atalho de qualquer arquivo, escolha Executar Ferramenta Personalizada.Use este método para transformar um subconjunto de modelos selecionado.

Você também pode configurar um projeto de Visual Studio de modo que modelos sejam executados quando os arquivos de dados que lê foram alterados.Para obter mais informações, consulte regenerando o código automaticamente.

gerando o texto variável

Os modelos de texto permitem que você use o código de programa para variar o conteúdo do arquivo gerado.

Para gerar o texto usando código de programa

Modificar o conteúdo do arquivo de .tt :

<#@ template hostspecific="false" language="C#" #>
<#@ output extension=".txt" #>
<#int top = 10;

for (int i = 0; i<=top; i++) { #>
The square of <#= i #> is <#= i*i #>
<# } #>

<#@ template hostspecific="false" language="VB" #>
<#@ output extension=".txt" #>
<#Dim top As Integer = 10

For i As Integer = 0 To top
#>
    The square of <#= i #> is <#= i*i #>
<#
Next
#>

Salve o arquivo de .tt, e inspecione o arquivo gerado de .txt novamente.Lista os quadrados os números de 0 a 9.

Observe que as instruções são incluídas em <#...#>, e somente dentro de expressões <#=...#>.Para obter mais informações, consulte Escrever um modelo de texto T4.

Se você escreve o código de geração em Visual Basic, a política de template deve conter language="VB"."C#" é o padrão.

Depurando um modelo em tempo de design de texto T4

Para criar um modelo de texto:

Inserir debug="true" na diretiva de template .Por exemplo:

<#@ template debug="true" hostspecific="false" language="C#" #>
Definir pontos de interrupção no modelo, da mesma forma de que que você para o código comum.
Escolha depurar o modelo T4 menu de atalho do arquivo de modelo de texto no solution Explorer.

O modelo será executado e irá parar nos pontos de interrupção.Você pode examinar variáveis e avançar no código da maneira habitual.

Dica
debug="true" faz o mapa de código gerado mais precisamente o modelo de texto, inserindo mais linha diretivas de numeração no código gerado.Se você deixar o check-out, os pontos de interrupção pode interromper a execução no estado incorreto. Mas você pode deixar a cláusula na diretiva do modelo mesmo quando você não estiver depurando.Isso faz com que apenas uma operação de soltar muito pequena no desempenho.

debug="true" faz o mapa de código gerado mais precisamente o modelo de texto, inserindo mais linha diretivas de numeração no código gerado.Se você deixar o check-out, os pontos de interrupção pode interromper a execução no estado incorreto.

Mas você pode deixar a cláusula na diretiva do modelo mesmo quando você não estiver depurando.Isso faz com que apenas uma operação de soltar muito pequena no desempenho.

Gerando o código ou recursos para sua solução

Você pode gerar os arquivos de programas que variam, como um modelo.Um modelo é uma entrada como um banco de dados, arquivo de configuração, UML modelos, DSL modelos, ou outra fonte.Geralmente você gerar vários arquivos de programa é do mesmo modelo.Para obter isso, você cria um arquivo de modelo para cada arquivo de programa gerado, e tem todos os modelos ler o mesmo modelo.

Para gerar código de programa ou recursos

Altere a diretiva de saída para gerar um arquivo do tipo apropriado, como .cs, .vb, .resx, ou .xml.

Insira o código que irá gerar o código de solução que você precisa.Por exemplo, se você desejar gerar três declarações de campo inteiro em uma classe:

                  <#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".cs" #>
<# var properties = new string [] {"P1", "P2", "P3"}; #>
class MyGeneratedClass {
<# 
  foreach (string propertyName in properties)
  { #>
  private int <#= propertyName #> = 0;
<# } #>
}

<#@ template debug="false" hostspecific="false" language="VB" #>
<#@ output extension=".cs" #>
<# Dim properties = {"P1", "P2", "P3"} #>
class MyGeneratedClass {
<# 
   For Each propertyName As String In properties
#>
  private int <#= propertyName #> = 0;
<#
   Next
#>
}

Salve o arquivo e inspecione o arquivo gerado, que agora contém o código a seguir:

class MyGeneratedClass {
  private int P1 = 0; 
  private int P2 = 0;
  private int P3 = 0;
}

Gerando o código gerado e o texto

Quando você gera código de programa, é o mais importante evitar confundir geração de código que executa no seu modelo, e o código gerado resultante que se torna parte da solução.Os dois idiomas não precisam ser os mesmos.

o exemplo anterior tem duas versões.em uma versão, o código de geração está em C#.Em outra versão, o código de geração é o Visual Basic.Mas o texto gerado por ambos eles é o mesmo, e é uma classe C#.

De a mesma forma, você pode usar um modelo de Visual C# para gerar código em qualquer idioma.O texto gerado não tem que estar em qualquer linguagem específica, e não tem que ser código de programa.

Modelos de estruturação de texto

Como uma questão de boa prática, nós tendemos para separar o código do modelo em duas partes:

Uma parte da configuração ou de coletar dados, que define os valores de em variáveis, mas não contêm blocos de texto.Em o exemplo anterior, essa parte é a inicialização de properties.

Isso é às vezes chamado da seção “modelo”, porque constrói um modelo de em- armazenamento, e ler normalmente um arquivo de modelo.
A parte do texto - geração (foreach(...){...} no exemplo), que usa os valores das variáveis.

Isso é não uma separação necessárias, mas é um estilo que torna mais fácil ler o modelo reduzindo a complexidade da parte que inclui o texto.

Arquivos de leitura ou outras fontes

Para acessar um arquivo de modelo ou um banco de dados, seu código de modelo pode usar assemblies como System.XML.Para obter acesso a esses assemblies, você deve inserir diretivas como estes:

<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#@ import namespace="System.IO" #>

A política de assembly faz o assembly especificado disponível ao código do modelo, da mesma forma que a seção de referências de um projeto de Visual Studio .Você não precisa incluir uma referência a System.dll, que é referenciado automaticamente.A política de import permite que você use tipos sem usar seus nomes totalmente qualificados, da mesma forma que a política de using em um arquivo de programa comum.

Por exemplo, após importado System.IO, você pode escrever:

          <# var properties = File.ReadLines("C:\\propertyList.txt");#>
...
<# foreach (string propertyName in properties) { #>
...

<# For Each propertyName As String In 
             File.ReadLines("C:\\propertyList.txt")
#>

abrindo um arquivo com um nome de caminho relativo

Para carregar um arquivo de um local relativo ao modelo de texto, você pode usar this.Host.ResolvePath().Para usar isso. Hosts, você deve definir hostspecific="true" em template:

<#@ template debug="false" hostspecific="true" language="C#" #>

Em seguida você pode escrever, por exemplo:

<# string fileName = this.Host.ResolvePath("filename.txt");
  string [] properties = File.ReadLines(filename);
#>
...
<#  foreach (string propertyName in properties { #>
...

<# Dim fileName = Me.Host.ResolvePath("propertyList.txt")
   Dim properties = File.ReadLines(filename)
#>
...
<#   For Each propertyName As String In properties
...
#>

Você também pode usar this.Host.TemplateFile, que identifica o nome do arquivo de modelo atual.

o tipo de this.Host (em VB, em Me.Host) é Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost.

obtendo dados de Visual Studio

Para usar serviços fornecidos em Visual Studio, defina o atributo de hostSpecific e carrega o conjunto de EnvDTE .Você pode usar IServiceProvider.GetCOMService() para acessar o DTE e outros serviços.Por exemplo:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#
  IServiceProvider serviceProvider = (IServiceProvider)this.Host;
  EnvDTE.DTE dte = (EnvDTE.DTE) serviceProvider.GetCOMService(typeof(EnvDTE.DTE));
#>

Number of projects in this VS solution:  <#= dte.Solution.Projects.Count #>

Dica
Um modelo de texto em execução no seu próprio domínio de app, e os serviços são acessados empacotamento.Em essa circunstância, GetCOMService() é mais confiável de GetService().

regenerando o código automaticamente

Normalmente, vários arquivos em uma solução de Visual Studio são gerados com um modelo conectado.Cada arquivo é gerado de seu próprio modelo, mas todos os modelos referem-se ao mesmo modelo.

Se o modelo de origem mudar, você deve executar novamente todos os modelos na solução.Para fazer isso Transformar Todos os Modelos manualmente, escolha no menu de Compilar .

Se você instalou o visualizador de Visual Studio SDK e modelagem, você pode ter todos os modelos convertidos automaticamente sempre que você executa uma compilação.Para fazer isso, edite o arquivo de projeto (.csproj ou .vbproj) em um editor de texto e adicione as seguintes linhas pela o final do arquivo, após quaisquer outras declarações de <import> :

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v11.0\TextTemplating\Microsoft.TextTemplating.targets" />
<PropertyGroup>
   <TransformOnBuild>true</TransformOnBuild>
   <!-- Other properties can be inserted here -->
</PropertyGroup>

Para obter mais informações, consulte Geração de código em um processo de compilação.

relatório de erros

Para colocar o erro e mensagens de aviso na janela de erro de Visual Studio , você pode usar esses métodos:

Error("An error message");
Warning("A warning message");

convertendo um arquivo existente a um modelo

Um recurso útil dos modelos é que se parecem muito como arquivos que geram, juntamente com qualquer código de programa inserido.Isso sugere um método útil para criar um modelo.Primeiro crie um arquivo comum como um protótipo, como um arquivo de Visual C# , e então introduz gradualmente o código de geração que varia o arquivo resultante.

Para converter um arquivo existente a um modelo em tempo de design

A o seu projeto de Visual Studio , adicione um arquivo do tipo que você deseja gerar, como .cs, .vb, ou arquivo de .resx .
Testar o novo arquivo para certificar-se de que ele funciona.
Em o solution Explorer, altere a extensão de nome de arquivo para .tt.
Verifique as seguintes propriedades do arquivo de .tt :

Ferramenta personalizada =

TextTemplatingFileGenerator

Ação de compilação =

Nenhum
Insira as seguintes linhas no início do arquivo:
```
<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".cs" #>
```
Se você deseja gravar o código de geração do modelo em Visual Basic, defina o atributo de language a "VB" em vez de "C#".

Defina o atributo de extension a extensão de nome de arquivo para o tipo de arquivo que você deseja gerar, por exemplo .cs, .resx, ou .xml.
Salve o arquivo.

um arquivo subsidiário é criado, com a extensão especificada.Suas propriedades estiverem corretas para o tipo de arquivo.Por exemplo, a propriedade de Ação de Compilação de um arquivo .cs seria Compilar.

Verifique se o arquivo gerado contém o conteúdo mesmo que o arquivo original.
Identifica uma parte do arquivo que você deseja variar.Por exemplo, uma parte que aparecem somente sob certas condições, ou parte que é repetida, ou onde os valores específicos variam.Inserção que gera código.Salve o arquivo e verifique se o arquivo subsidiário está corretamente gerado.Repita esta etapa.

Diretrizes para a geração de código

Por favor consulte Instruções para criar modelos de texto T4.

Próximas etapas

A próxima etapa	Tópico
Gravar e depurar um modelo mais avançado de texto, com código que usa funções auxiliares, arquivos incluídos, e dados persistentes.	Escrever um modelo de texto T4
Gerar documentos dos modelos em tempo de execução.	Geração de texto de tempo de execução com modelos de texto T4
Executar a geração de texto fora de Visual Studio.	Gerando arquivos com o utilitário TextTransform
Transformar os dados na forma de uma linguagem específica de domínio.	Gerando código a partir de uma linguagem específica de domínio
Escreva processadores de diretiva para transformar suas próprias fontes de dados.	Personalizando a transformação de texto T4

Consulte também

Conceitos

Instruções para criar modelos de texto T4

Compartilhar via