Diretiva de inclusão T4

Em um modelo de texto no Visual Studio, você pode incluir texto de outro arquivo usando uma diretiva <#@include#>. Você pode colocar diretivas include em qualquer lugar de um modelo de texto antes do primeiro bloco de recursos da classe <#+ ... #>. Os arquivos incluídos também podem conter diretivas include e outras diretivas. Isso permite que você compartilhe código de modelo e texto constante entre modelos.

Usando diretivas de inclusão

<#@ include file="filePath" [once="true"] #>

• filePath pode ser absoluto ou relativo ao arquivo de modelo atual.

  Além disso, as extensões específicas do Visual Studio podem especificar seus próprios diretórios para pesquisar arquivos de inclusão. Por exemplo, quando você instalou o SDK de Visualização e Modelagem (Ferramentas DSL), a seguinte pasta foi adicionada à lista de inclusão: Program Files\Microsoft Visual Studio 10.0\Common7\IDE\Extensions\Microsoft\DSL SDK\DSL Designer\11.0\TextTemplates.

  Essas pastas de inclusão adicionais podem depender da extensão do arquivo de inclusão. Por exemplo, a pasta de inclusão das Ferramentas DSL só é acessível a arquivos de inclusão com a extensão de arquivo .tt

• filePath pode incluir variáveis de ambiente delimitadas com "%". Por exemplo:

  <#@ include file="%HOMEPATH%\MyIncludeFile.t4" #>
  

• O nome de um arquivo incluído não precisa usar a extensão ".tt".

  Você pode usar outra extensão como ".t4" para arquivos incluídos. Isso ocorre porque, quando você adiciona um arquivo .tt a um projeto, o Visual Studio define automaticamente a propriedade de Ferramenta Personalizada como TextTemplatingFileGenerator. Geralmente, você não quer que os arquivos incluídos sejam transformados individualmente.

  Por outro lado, você deve estar ciente de que, em alguns casos, a extensão do arquivo afeta as pastas adicionais em que os arquivos de inclusão serão pesquisados. Isso pode ser importante quando você tem um arquivo incluído que contenha outros arquivos.

• O conteúdo incluído é processado quase como se fizesse parte do modelo de texto de inclusão. Entretanto, você pode incluir um arquivo que contenha um bloco de recurso de classe <#+...#> mesmo se a diretiva include for seguida por blocos de texto comum ou de controle padrão.

• Use once="true" para garantir que um modelo seja incluído somente uma vez, mesmo se for invocado de mais de um arquivo de inclusão.

  Esse recurso facilita a criação de uma biblioteca de snippets T4 reutilizáveis que você pode incluir à vontade sem se preocupar que algum outro snippet já os tenha incluído. Por exemplo, suponha que você tenha uma biblioteca de snippets muito refinados que lidam com processamento de modelo e geração de C#. Por sua vez, eles são usados por alguns utilitários mais específicos da tarefa, como a geração de exceções, que você pode usar de qualquer modelo mais específico do aplicativo. Se você desenhar o grafo de dependência, verá que alguns snippets poderiam ser incluídos várias vezes. Mas o parâmetro once evita as inclusões subsequentes.

  MyTextTemplate.tt:

<#@ output extension=".txt" #>
Output message 1 (from top template).
<#@ include file="TextFile1.t4"#>
Output message 5 (from top template).
<#
   GenerateMessage(6); // defined in TextFile1.t4
   AnotherGenerateMessage(7); // defined in TextFile2.t4
#>

TextFile1.t4:

   Output Message 2 (from included file).
<#@ include file="TextFile2.t4" #>
   Output Message 4 (from included file).
<#+ // Start of class feature control block.
void GenerateMessage(int n)
{
#>
   Output Message <#= n #> (from GenerateMessage method).
<#+
}
#>

TextFile2.t4:

        Output Message 3 (from included file 2).
<#+ // Start of class feature control block.
void AnotherGenerateMessage(int n)
{
#>
       Output Message <#= n #> (from AnotherGenerateMessage method).
<#+
}
#>

O arquivo gerado resultante, MyTextTemplate.txt:

Output message 1 (from top template).
   Output Message 2 (from included file).
        Output Message 3 (from included file 2).

   Output Message 4 (from included file).

Output message 5 (from top template).
   Output Message 6 (from GenerateMessage method).
       Output Message 7 (from AnotherGenerateMessage method).

Usando propriedades do projeto no MSBuild e no Visual Studio

Embora você possa usar macros do Visual Studio, como $(SolutionDir) em uma diretiva de inclusão, elas não funcionam no MSBuild. Se você quiser transformar modelos no computador de compilação, use as propriedades do projeto como alternativa.

Edite seu arquivo .csproj ou .vbproj para definir uma propriedade do projeto. Este exemplo define uma propriedade chamada myIncludeFolder:

<!-- Define a project property, myIncludeFolder: -->
<PropertyGroup>
    <myIncludeFolder>$(MSBuildProjectDirectory)\..\libs</myIncludeFolder>
</PropertyGroup>

<!-- Tell the MSBuild T4 task to make the property available: -->
<ItemGroup>
    <T4ParameterValues Include="myIncludeFolder">
      <Value>$(myIncludeFolder)</Value>
    </T4ParameterValues>
  </ItemGroup>

Agora você pode usar a propriedade do projeto em modelos de texto, que se transformam corretamente no Visual Studio e no MSBuild:

<#@ include file="$(myIncludeFolder)\defs.tt" #>