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

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

Existem algumas diferenças no que as tarefas de build conseguem fazer, dependendo do motor de build que usas. Quando constrói a solução no Visual Studio, um modelo de texto pode aceder à API do Visual Studio (EnvDTE) se o atributo hostspecific="true" estiver definido. Mas isso não é verdade quando constróis a solução a partir da linha de comandos ou quando inicias uma build de servidor através do Visual Studio. Nesses casos, a build é realizada pelo MSBuild e é utilizado um host T4 diferente. Isto significa que não podes aceder a coisas como nomes de ficheiros de projeto da mesma forma quando constróis um template de texto usando o MSBuild. No entanto, pode passar a informação do ambiente para modelos de texto e processadores de diretivas usando parâmetros de compilação.

Configura as tuas máquinas

Para ativar tarefas de compilação no seu computador de desenvolvimento, instale o SDK de Modelação para o Visual Studio.

Se o seu servidor de compilação correr num computador que não tenha o Visual Studio instalado, copie os seguintes ficheiros para o computador de compilação a partir da sua máquina 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 o ficheiro do seu projeto para configurar algumas funcionalidades no MSBuild, por exemplo, importar os alvos de transformação de texto.

No Explorador de Soluções, escolha Descarregar no menu do botão direito do seu projeto. Isso permite editar o ficheiro .csproj ou .vbproj no editor XML. Quando terminares de editar, escolhe Recarregar.

Importar os alvos de transformação de texto

No ficheiro .vbproj ou .csproj, encontre a última Import Project linha.

Depois dessa linha, se existir, insira a importação de Templamento de Texto:

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

Transformar modelos numa compilação

Existem algumas propriedades que pode inserir no seu ficheiro de projeto para controlar a tarefa de transformação:

• Execute a tarefa de Transformação no início de cada build.

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

• Por exemplo, sobreescreva ficheiros que são apenas leitura porque não são requisitados:

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

• Transforme todos os templates sempre que necessário.

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

  Por defeito, a tarefa T4 do MSBuild regenera um ficheiro de saída se for mais antigo do que:

  • o seu ficheiro modelo
  • quaisquer ficheiros que estejam incluídos
  • quaisquer ficheiros que tenham sido previamente lidos pelo template ou por um processador de diretivas que este utilize

  Este é um teste de dependência mais poderoso do que o utilizado pelo comando Transformar Todos os Templates no Visual Studio, que apenas compara as datas do template e do ficheiro de saída.

Para realizar apenas as transformações de texto no 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"

Pode usar curingas no TransformFile:

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

Controlo de origem

Não existe uma integração integrada específica com um sistema de controlo de versão. No entanto, pode adicionar as suas próprias extensões, por exemplo, para fazer check-out e check-in num ficheiro gerado. Por defeito, a tarefa de transformação de texto evita sobrescrever um ficheiro marcado como só de leitura. Quando tal ficheiro é encontrado, um erro é registado na Lista de Erros do Visual Studio e a tarefa falha.

Para especificar que os ficheiros somente de leitura devem ser sobrescritos, insira esta propriedade:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

A menos que personalize a etapa de pós-processamento, um aviso será registado na Lista de Erros quando um ficheiro for sobrescrito.

Personalize o processo de construção

A transformação de texto acontece antes de outras tarefas no processo de construção. 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, pode referenciar listas de ficheiros:

• GeneratedFiles - uma lista de ficheiros escritos pelo processo. Para aqueles ficheiros que sobrescreveram ficheiros de só leitura existentes, %(GeneratedFiles.ReadOnlyFileOverwritten) será verdade. Estes ficheiros podem ser retirados do controlo de versão.

• NonGeneratedFiles - uma lista de ficheiros de apenas leitura que não foram sobrescritos.

Por exemplo, defines uma tarefa para consultar os GeneratedFiles.

OutputFilePath (CaminhoDoArquivoSaída) e OutputFileName (NomeDoArquivoSaída)

Estas propriedades são usadas apenas pela MSBuild. Não afetam a geração de código no Visual Studio. Eles redirecionam o ficheiro de saída gerado para uma pasta ou ficheiro 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 redirecionar é $(IntermediateOutputPath).

Se especificar um nome de ficheiro de saída, ele tem precedência sobre a extensão especificada na diretiva de saída nos templates.

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

Não é recomendado especificar um OutputFileName ou OutputFilePath se também estiver a transformar templates dentro do Visual Studio usando o Transform All ou a executar o gerador de ficheiros únicos. Vais acabar com caminhos de ficheiro diferentes dependendo de como desencadeaste a transformação. Isto pode ser confuso.

Adicionar referência e incluir caminhos

O host tem um conjunto predefinido de caminhos onde procura assemblies referenciados em modelos. Para acrescentar a este conjunto:

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

Para definir as pastas que serão pesquisadas incluindo ficheiros, forneça uma lista separada por ponto e vírgula. Normalmente adiciona à lista de pastas existente.

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

Passar os dados do contexto da build para os templates

Podes definir valores de parâmetros no ficheiro do projeto. Por exemplo, pode passar propriedades de construção e variáveis de ambiente:

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

Num modelo de texto, defina hostspecific na diretiva do modelo. Use a diretiva de parâmetros para obter valores:

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

Num processador de diretivas, pode chamar ITextTemplatingEngineHost.ResolveParameterValue:

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

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

Utilizar propriedades do projeto na montagem e incluir diretivas

Macros do Visual Studio como o $(SolutionDir) não funcionam no MSBuild. Podes usar propriedades do projeto em vez disso.

Edite o seu ficheiro .csproj ou .vbproj para definir uma propriedade do 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 pode usar a sua propriedade de projeto na montagem e incluir instruções:

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

Estas diretivas obtêm valores de T4parameterValues tanto no MSBuild como nos hosts do Visual Studio.

Perguntas e Respostas

Porque é que eu haveria de querer transformar templates no servidor de compilação? Já transformei templates no Visual Studio antes de verificar o meu código.

Se atualizar um ficheiro incluído ou outro ficheiro lido pelo modelo, o Visual Studio não transforma automaticamente o ficheiro. Transformar templates como parte da build garante que tudo está atualizado.

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

• A ferramenta TextTransform pode ser usada em scripts de comando. Na maioria dos casos, é mais fácil usar o MSBuild.

• Invocar Transformação de Texto numa extensão do Visual Studio.

• Os modelos de texto durante o design são transformados pelo Visual Studio.

• Os modelos de texto em tempo de execução são transformados durante a execução na aplicação.

Conteúdo relacionado

• Escreva um modelo de texto T4