T4 Diretriz de modelo

A Visual Studio modelo de texto T4 normalmente começa com uma template diretiva, que especifica como o modelo deve ser processado. Deve haver não mais de uma diretriz de modelo em um modelo de texto e todos os arquivos que ele contém.

Para obter uma visão geral da escrita de modelos de texto, consulte Escrever um modelo de texto T4.

Usando a diretiva de modelo

<#@ template [language="VB"] [compilerOptions="options"] [culture="code"] [debug="true"] [hostspecific="true"] [inherits="templateBaseClass"] #>

O template diretiva tem vários atributos que permitem especificar diferentes aspectos da transformação. Todos os atributos são opcionais.

atributo compilerOptions

• Exemplo:
  compilerOptions="optimize+"

• Valores válidos:
  Quaisquer opções de compilador válido. Para obter mais informações, consulte TRANSLATION FROM VPE FOR CSHARP compilador Opções listadas por categoria e Opções do compilador do Visual Basic listadas por categoria.

  Ignorada para modelos de tempo de execução (pré-processado).

Essas opções são aplicadas quando o modelo foi convertido em Visual C# ou Visual Basic, e o código resultante é compilado.

atributo de cultura

• Exemplo:
  culture="de-CH"

• Valores válidos:
  "", a cultura invariável, que é o padrão.

  Uma cultura, expressa como uma seqüência em que o formulário no modo xx-XX. Por exemplo, en-US, ja-JP, de-CH, de-DE. Para obter mais informações, consulte System.Globalization.CultureInfo.

O atributo de cultura Especifica a cultura a ser usada quando um bloco de expressão é convertido em texto.

atributo Debug

• Exemplo:

  debug="true"
  

• Valores válidos:
  true, false. O padrão é False.

O debug atributo especifica a depuração está ativado ou não. Se for true, o arquivo de código intermediário conterá informações que permitem que o depurador identificar a posição no modelo onde uma interrupção ou exceção ocorreu. Para modelos de regulares (não pré-processado modelos), o arquivo de código intermediário será gravado para o diretório % TEMP %.

Para iniciar o depurador em determinado ponto na execução de um modelo, inserir uma chamada a Launch. Para interromper a execução em pontos subseqüentes, inserir uma chamada a Break. Por exemplo:

<#@ template debug="true" language="C#" #>
<#@ output extension=".txt" #>
Output something.
<# 
 // Break here:
 System.Diagnostics.Debugger.Launch();  
#>
Output more.
<#
 // Break here also:
 System.Diagnostics.Debugger.Break();  
#>
Output more.

Para obter mais informações, consulte Demonstra Passo a passo: Depuração de um modelo de texto.

atributo de HostSpecific

• Exemplo:

  hostspecific="true"
  

• Valores válidos:
  true, false. O padrão é False.

Se você definir o valor desse atributo para true, uma propriedade chamada Host é adicionado à classe gerada pelo seu modelo de texto. A propriedade é uma referência para o host do mecanismo de transformação e é declarada como Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost. Se você tiver definido um host personalizado, você pode ser convertido para o tipo de host personalizado.

Como o tipo desta propriedade depende do tipo de host, só é útil se você estiver escrevendo um modelo de texto só funciona com um host específico.

Quando hostspecific é true e você estiver usando Visual Studio, você pode converter os this.Host para IServiceProvider para acessar Visual Studio recursos. Você também pode usar Host.ResolvePath(filename) para obter o caminho absoluto de um arquivo no projeto. Por exemplo:

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<# // Get the Visual Studio API as a service:
 DTE dte = ((IServiceProvider)this.Host).GetService(typeof(DTE)) as DTE;  
#>
Number of projects in this solution: <#=  dte.Solution.Projects.Count #>

<#
 // Find a path within the current project:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of myFile is:
<#= myFile #>

atributo de idioma

• Exemplo:
  language="VB"

• Valores válidos:
  C# (padrão)

  VB

  (Os valores VBv3.5 e C#v3.5 estão obsoletos nesta versão, mas será interpretado como VB e C#.)

O atributo de idioma especifica o idioma (Visual Basic ou Visual C#) para usar o código de origem em blocos de instrução e expressão. O arquivo de código intermediário do qual a saída é gerada usará esse idioma. Essa linguagem não está relacionada ao idioma gera seu modelo, que pode ser qualquer tipo de texto.

Por exemplo:

<#@ template language="VB" #>
<#@ output extension=".txt" #>
Squares of numbers:
<#
  Dim number As Integer
  For number = 1 To 4
#>
  Square of <#= number #> is <#= number * number #>
<#
  Next number
#>

atributo Inherits

Você pode especificar que o código de programa do modelo pode herdar de outra classe, também pode ser gerada a partir de um modelo de texto.

Herança de um modelo de texto (pré-processado) de tempo de execução

Você pode usar a herança entre os modelos de texto de tempo de execução para criar um modelo básico que tem diversas variantes derivadas. Os modelos de tempo de execução são aqueles que têm o Ferramenta personalizada propriedade definida como TextTemplatingFilePreprocessor. Um modelo de tempo de execução gera o código que você pode chamar em seu aplicativo para criar o texto definido no modelo. Para obter mais informações, consulte Geração de texto de tempo de execução usando os modelos de texto T4.

Se você não especificar um inherits attribute, uma classe base e uma classe derivada são geradas a partir de seu modelo de texto. Quando você especificar um inherits atributo, somente a classe derivada é gerado. Você pode escrever uma classe base à mão, mas ele deve fornecer os métodos que são usados pela classe derivada.

Mais geralmente, você deve especificar outro modelo pré-processado como a classe base. O modelo de base fornece comuns blocos de texto, que podem ser intercaladas com texto modelos derivados. Você pode usar blocos de recurso de classe <#+ ... #> para definir os métodos que contenham fragmentos de texto. Por exemplo, você pode colocar a estrutura do texto de saída no modelo básico, fornecendo métodos virtuais que podem ser substituídos nos modelos derivados:

• Modelo de texto de tempo de execução (pré-processado) BaseTemplate.tt:

  This is the common header.
  <# 
    SpecificFragment1(); 
  #>
  A common central text.
  <# 
    SpecificFragment2(); 
  #>
  This is the common footer.
  <#+ 
    // Declare abstract methods
    protected virtual void SpecificFragment1() { }
    protected virtual void SpecificFragment2() { }
  #>
  

• Modelo de texto de tempo de execução (pré-processado) DerivedTemplate1.tt:

  <#@ template language="C#" inherits="BaseTemplate" #>
  <# 
    // Run the base template:
    base.TransformText();
  #>
  <#+
  // Provide fragments specific to this derived template:
  protected override void SpecificFragment1()
  {
  #>
     Fragment 1 for DerivedTemplate1
  <#+
  }
  protected override void SpecificFragment2()
  {
  #>
     Fragment 2 for DerivedTemplate1
  <#+
  }
  #>
  

• Código do aplicativo para chamar DerivedTemplate1:

  Console.WriteLine(new DerivedTemplate().TransformText());
  

• Saída resultante:

  This is the common header.
     Fragment 1 for DerivedTemplate1
  A common central text.
     Fragment 2 for DerivedTemplate1
  This is the common footer.
  

Você pode criar as classes básicas e derivadas de diferentes projetos. Lembre-se de adicionar o projeto base ou um assembly referências do projeto derivado.

Você também pode usar uma classe de escrita à mão comuns, como a classe base. A classe base deve fornecer os métodos usados pela classe derivada.

Herança de um modelo de texto em tempo de design

Um modelo de texto em tempo de design é um arquivo para o qual Ferramenta personalizada for definido como TextTemplatingFileGenerator. O modelo gera um arquivo de saída de código ou texto, que forma parte de sua Visual Studio project. Para gerar o arquivo de saída, o modelo primeiro é convertido em um arquivo de código de programa intermediário, que geralmente não vê. O inherits atributo especifica a classe base para este código intermediário.

Para um modelo de texto normal, você pode especificar qualquer classe de base que é derivada de Microsoft.VisualStudio.TextTemplating.TextTransformation. Use o <#@assembly#> diretiva para carregar o assembly ou um projeto que contém a classe de base.

Para obter mais informações, consulte "herança em modelos de texto" blog de Gareth Jones.

Histórico de alterações