Invocar a transformação de texto no processo de compilação

A transformação de texto pode ser invocada como parte do processo de build de uma solução do Visual Studio. Há tarefas de build especializadas para transformação de texto. As tarefas de build T4 executam modelos de texto em tempo de design e também compilam modelos de texto em tempo de execução (pré-processados).

Há algumas diferenças no que as tarefas de build podem fazer, dependendo de qual mecanismo de build você usa. Quando você cria a solução no Visual Studio, um modelo de texto pode acessar a API do Visual Studio (EnvDTE) se o atributo hostspecific="true" estiver definido. Mas isso não é verdade quando você cria a solução a partir da linha de comando ou quando inicia um build de servidor por meio do Visual Studio. Nesses casos, o build é executado pelo MSBuild e um host T4 diferente é usado. Isso significa que você não pode acessar coisas como nomes de arquivo de projeto da mesma maneira ao criar um modelo de texto usando o MSBuild. No entanto, você pode passar informações de ambiente para modelos de texto e processadores de diretiva usando parâmetros de build.

Configurar seus computadores

Para habilitar tarefas de build em seu computador de desenvolvimento, instale o SDK de Modelagem para Visual Studio.

Se o servidor de build for executado em um computador que não tenha o Visual Studio instalado, copie os seguintes arquivos para o computador de build do computador de desenvolvimento:

• %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VisualStudio\v16.0\TextTemplating

  • Microsoft.VisualStudio.TextTemplating.Sdk.Host.15.0.dll
  • Microsoft.TextTemplating.Build.Tasks.dll
  • Microsoft.TextTemplating.targets

• %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\VSSDK\VisualStudioIntegration\Common\Assemblies\v4.0

  • Microsoft.VisualStudio.TextTemplating.15.0.dll
  • Microsoft.VisualStudio.TextTemplating.Interfaces.15.0.dll
  • Microsoft.VisualStudio.TextTemplating.VSHost.15.0.dll

• %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community\Common7\IDE\PublicAssemblies

  • Microsoft.VisualStudio.TextTemplating.Modeling.15.0.dll

Editar o arquivo de projeto

Edite seu arquivo de projeto para configurar alguns dos recursos no MSBuild, por exemplo, importando os destinos de transformação de texto.

No Gerenciador de Soluções, escolha Descarregar no menu de clique com o botão direito do mouse do projeto. Isso permite editar o arquivo .csproj ou .vbproj no editor XML. Quando terminar de editar, escolha Recarregar.

Importar os destinos de transformação de texto

No arquivo .vbproj ou .csproj, localize a última Import Project linha.

Depois dessa linha, se existir, insira a importação de Text Templating:

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets" />

Transformar modelos em um build

Há algumas propriedades que você pode inserir no arquivo de projeto para controlar a tarefa de transformação:

• Execute a tarefa Transform no início de cada build:

  <PropertyGroup>
      <TransformOnBuild>true</TransformOnBuild>
  </PropertyGroup>
  

• Substitua arquivos que são somente leitura, por exemplo, porque eles não são verificados:

  <PropertyGroup>
      <OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>
  </PropertyGroup>
  

• Transforme cada modelo todas as vezes:

  <PropertyGroup>
      <TransformOutOfDateOnly>false</TransformOutOfDateOnly>
  </PropertyGroup>
  

  Por padrão, a tarefa T4 MSBuild regenera um arquivo de saída se for mais antigo que:

  • seu arquivo de modelo
  • todos os arquivos incluídos
  • todos os arquivos que foram lidos anteriormente pelo modelo ou por um processador de diretiva que ele usa

  Esse é um teste de dependência mais poderoso do que é usado pelo comando Transformar Todos os Modelos no Visual Studio, que compara apenas as datas do modelo e do arquivo de saída.

Para executar apenas as transformações de texto em seu projeto, invoque a tarefa TransformAll:

msbuild myProject.csproj /t:TransformAll

Para transformar um modelo de texto específico:

msbuild myProject.csproj /t:Transform /p:TransformFile="Template1.tt"

Você pode usar curingas no "TransformFile".

msbuild dsl.csproj /t:Transform /p:TransformFile="GeneratedCode\**\*.tt"

Controle do código-fonte

Não há nenhuma integração interna específica com um sistema de controle do código-fonte. No entanto, você pode adicionar suas próprias extensões, por exemplo, para extrair e integrar um arquivo gerado. Por padrão, a tarefa de transformação de texto evita sobrescrever um arquivo marcado como somente leitura. Quando esse arquivo é encontrado, um erro é registrado na Lista de Erros do Visual Studio e a tarefa falha.

Para especificar que os arquivos somente leitura devem ser substituídos, insira esta propriedade:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

A menos que você personalize a etapa de pós-processamento, um aviso será registrado na Lista de Erros quando um arquivo for substituído.

Personalizar o processo de build

A transformação de texto ocorre antes de outras tarefas no processo de build. Você pode definir tarefas que são invocadas antes e depois da transformação, definindo as propriedades $(BeforeTransform) e $(AfterTransform):

<PropertyGroup>
    <BeforeTransform>CustomPreTransform</BeforeTransform>
    <AfterTransform>CustomPostTransform</AfterTransform>
</PropertyGroup>
<Target Name="CustomPreTransform">
    <Message Text="In CustomPreTransform..." Importance="High" />
</Target>
<Target Name="CustomPostTransform">
    <Message Text="In CustomPostTransform..." Importance="High" />
</Target>

Em AfterTransform, você pode referenciar listas de arquivos:

• GeneratedFiles - uma lista de arquivos gravados pelo processo. Para os arquivos que substituem os arquivos somente leitura existentes, %(GeneratedFiles.ReadOnlyFileOverwritten) será verdadeiro. Esses arquivos podem ser verificados fora do controle do código-fonte.

• NonGeneratedFiles - uma lista de arquivos somente leitura que não foram sobrescritos.

Por exemplo, você define uma tarefa para verificar os arquivos gerados em GeneratedFiles.

CaminhoDoArquivoDeSaída e NomeDoArquivoDeSaída

Essas propriedades são usadas apenas pelo MSBuild. Elas não afetam a geração de código no Visual Studio. Eles redirecionam o arquivo de saída gerado para uma pasta ou arquivo diferente. A pasta de destino já deve existir.

<ItemGroup>
  <None Include="MyTemplate.tt">
    <Generator>TextTemplatingFileGenerator</Generator>
    <OutputFilePath>MyFolder</OutputFilePath>
    <LastGenOutput>MyTemplate.cs</LastGenOutput>
  </None>
</ItemGroup>

Uma pasta útil para a qual redirecionar é $(IntermediateOutputPath).

Se você especificar um nome de arquivo de saída, ele terá precedência sobre a extensão especificada na diretiva de saída nos modelos.

<ItemGroup>
  <None Include="MyTemplate.tt">
    <Generator>TextTemplatingFileGenerator</Generator>
    <OutputFileName>MyOutputFileName.cs</OutputFileName>
    <LastGenOutput>MyTemplate.cs</LastGenOutput>
  </None>
</ItemGroup>

Especificar um OutputFileName ou OutputFilePath não será recomendado se você também estiver transformando modelos dentro do Visual Studio usando Transformar Tudo ou executando o gerador de arquivo único. Você acabará com caminhos de arquivo diferentes dependendo de como você disparou a transformação. Isso pode ser confuso.

Adicionar referência e incluir caminhos

O host possui um conjunto padrão de caminhos onde busca por assemblies referenciados em modelos. Para adicionar a este conjunto:

<ItemGroup>
    <T4ReferencePath Include="$(VsIdePath)PublicAssemblies\" />
    <!-- Add more T4ReferencePath items here -->
</ItemGroup>

Para definir as pastas que serão pesquisadas para incluir arquivos, forneça uma lista separada por ponto-e-vírgula. Normalmente, você adiciona à lista de pastas existente.

<PropertyGroup>
    <IncludeFolders>
$(IncludeFolders);$(MSBuildProjectDirectory)\Include;AnotherFolder;And\Another</IncludeFolders>
</PropertyGroup>

Passar dados de contexto de build para os templates

Você pode definir valores de parâmetro no arquivo de projeto. Por exemplo, você pode passar propriedades de build e variáveis de ambiente:

<ItemGroup>
  <T4ParameterValues Include="ProjectFolder">
    <Value>$(ProjectDir)</Value>
    <Visible>false</Visible>
  </T4ParameterValues>
</ItemGroup>

Em um modelo de texto, defina hostspecific na diretiva de modelo. Use a diretiva de parâmetro para obter valores:

<#@template language="c#" hostspecific="true"#>
<#@ parameter type="System.String" name="ProjectFolder" #>
The project folder is: <#= ProjectFolder #>

Em um processador de diretiva, você pode chamar ITextTemplatingEngineHost.ResolveParameterValue:

string value = Host.ResolveParameterValue("-", "-", "parameterName");

Dim value = Host.ResolveParameterValue("-", "-", "parameterName")

Usar propriedades do projeto no assembly e incluir diretivas

Macros do Visual Studio como $(SolutionDir) não funcionam no MSBuild. Em vez disso, você pode usar as propriedades do projeto.

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

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

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

Agora você pode usar a propriedade do projeto no assembly e incluir diretivas:

<#@ assembly name="$(myLibFolder)\MyLib.dll" #>
<#@ include file="$(myLibFolder)\MyIncludeFile.t4" #>

Essas diretivas obtêm valores de T4parameterValues no MSBuild e em hosts do Visual Studio.

Perguntas e Respostas

Por que eu gostaria de transformar modelos no servidor de build? Já transformei modelos no Visual Studio antes de integrar meu código.

Se você atualizar um arquivo incluído ou outro arquivo lido pelo modelo, o Visual Studio não transformará o arquivo automaticamente. A transformação de modelos como parte do build garante que tudo esteja atualizado.

Quais outras opções existem para transformar modelos de texto?

• O utilitário TextTransform pode ser usado em scripts de comando. Na maioria dos casos, é mais fácil usar o MSBuild.

• Invoque a Transformação de Texto em uma extensão do Visual Studio.

• Modelos de texto em tempo de design são transformados pelo Visual Studio.

• Os modelos de texto são transformados em tempo de execução em seu aplicativo.

Conteúdo relacionado

• Escrever um modelo de texto T4