Compartir vía

Activar la transformación de textos en el proceso de compilación

La transformación de texto se puede invocar como parte del proceso de compilación de una solución de Visual Studio. Hay tareas de construcción especializadas destinadas a la transformación de texto. Las tareas de compilación de T4 ejecutan plantillas de texto en tiempo de diseño y también compilan plantillas de texto en tiempo de ejecución (preprocesadas).

Existen algunas diferencias en lo que pueden hacer las tareas de compilación, en función del motor de compilación que use. Al compilar la solución en Visual Studio, una plantilla de texto puede acceder a la API de Visual Studio (EnvDTE) si se establece el atributo hostspecific="true". Pero eso no es cierto al compilar la solución desde la línea de comandos o al iniciar una compilación de servidor a través de Visual Studio. En esos casos, MSBuild realiza la compilación y se usa un host T4 diferente. Esto significa que no se puede acceder a cosas como los nombres de archivo de proyecto de la misma manera al compilar una plantilla de texto mediante MSBuild. Sin embargo, puede pasar información de entorno a plantillas de texto y procesadores de directivas mediante parámetros de compilación.

Configuración de las máquinas

Para habilitar las tareas de compilación en el equipo de desarrollo, instale el SDK de modelado para Visual Studio.

Nota:

El componente Transformación de Plantillas de Texto se instala automáticamente como parte de la tarea Desarrollo de Extensiones de Visual Studio. También puede instalarlo desde la pestaña Componentes individuales del Instalador de Visual Studio, en la categoría SDK, bibliotecas y marcos . Instale el componente SDK de modelado desde la pestaña Componentes individuales .

Si el servidor de compilación se ejecuta en un equipo que no tiene Instalado Visual Studio, copie los archivos siguientes en el equipo de compilación desde el equipo de desarrollo:

  • %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

Sugerencia

Si recibe un MissingMethodException para un método de Microsoft.CodeAnalysis al ejecutar los destinos de compilación de TextTemplating en un servidor de compilación, asegúrese de que los ensamblados de Roslyn se encuentren en un directorio llamado Roslyn dentro del mismo directorio que el ejecutable de compilación (por ejemplo, msbuild.exe).

Edición del archivo del proyecto

Edite el archivo de proyecto para configurar algunas de las características de MSBuild, por ejemplo, importando los destinos de transformación de texto.

En el Explorador de soluciones, elija Descargar en el menú contextual de su proyecto. Esto le permite editar el archivo .csproj o .vbproj en el editor XML. Cuando haya terminado de editarse, elija Volver a cargar.

Importar los destinos de transformación de texto

En el archivo .vbproj o .csproj, busque la última Import Project línea.

Después de esa línea, si existe, inserte la importación de Text Templating:

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

Transformar plantillas durante una compilación

Hay algunas propiedades que puede insertar en el archivo de proyecto para controlar la tarea de transformación:

  • Ejecute la tarea de Transformación al principio de cada compilación.

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

  • Sobrescribir los archivos que son de solo lectura, por ejemplo, porque no están desprotegidos:

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

  • Transforme cada plantilla cada vez:

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

    De forma predeterminada, la tarea T4 MSBuild vuelve a generar un archivo de salida si es anterior a:

    • su archivo de plantilla
    • todos los archivos que se incluyen
    • cualquier archivo que haya sido leído previamente por la plantilla o por un procesador de directivas que utiliza

    Se trata de una prueba de dependencia más eficaz que la que usa el comando Transformar todas las plantillas en Visual Studio, que solo compara las fechas del archivo de salida y la plantilla.

Para realizar solo las transformaciones de texto en el proyecto, invoque la tarea TransformAll:

msbuild myProject.csproj /t:TransformAll

Para transformar una plantilla de texto específica:

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

Puede usar caracteres comodín en TransformFile:

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

Control de código fuente

No hay ninguna integración integrada específica con un sistema de control de código fuente. Sin embargo, puede agregar sus propias extensiones, por ejemplo, para extraer y registrar un archivo generado. De forma predeterminada, la tarea de transformación de texto evita sobrescribir un archivo marcado como de solo lectura. Cuando se encuentra este archivo, se registra un error en la lista de errores de Visual Studio y se produce un error en la tarea.

Para especificar que se deben sobrescribir los archivos de solo lectura, inserte esta propiedad:

<OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>

A menos que personalice el paso de postprocesamiento, se registrará una advertencia en la lista de errores cuando se sobrescribe un archivo.

Personalización del proceso de compilación

La transformación de texto se produce antes de otras tareas en el proceso de compilación. Puede definir las tareas que se invocan antes y después de la transformación estableciendo las propiedades $(BeforeTransform) y $(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>

En AfterTransform, puede hacer referencia a listas de archivos:

  • GeneratedFiles: una lista de archivos escritos por el proceso. En el caso de los archivos que sobrescriban los archivos de solo lectura existentes, %(GeneratedFiles.ReadOnlyFileOverwritten) será verdadero. Estos archivos se pueden desprotegir del control de código fuente.

  • NonGeneratedFiles - una lista de archivos de solo lectura que no fueron sobrescritos.

Por ejemplo, se define una tarea para revisar ArchivosGenerados.

Ruta del archivo de salida y Nombre del archivo de salida

Estas propiedades solo las usa MSBuild. No afectan a la generación de código en Visual Studio. Redirigen el archivo de salida generado a una carpeta o archivo diferente. La carpeta de destino ya debe existir.

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

Una carpeta útil a la que redirigir es $(IntermediateOutputPath).

Si especifica un nombre de archivo de salida, tiene prioridad sobre la extensión especificada en la directiva de salida de las plantillas.

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

No se recomienda especificar outputFileName o OutputFilePath si también está transformando plantillas dentro de Visual Studio mediante Transformar todo o ejecutar el generador de archivos único. Terminarás teniendo diferentes rutas de acceso de archivo en función de cómo hayas desencadenado la transformación. Esto puede resultar confuso.

Añadir rutas de acceso de referencia e incluir

El host tiene un conjunto predeterminado de rutas de acceso en las que busca ensamblados a los que se hace referencia en las plantillas. Para agregar a este conjunto:

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

Para establecer las carpetas que se buscarán para los archivos incluidos, proporcione una lista separada por punto y coma. Normalmente, se agrega a la lista de carpetas existente.

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

Pasar datos de contexto de compilación a las plantillas

Puede establecer valores de parámetro en el archivo del proyecto. Por ejemplo, puede pasar propiedades de compilación y variables de entorno:

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

En una plantilla de texto, establezca hostspecific en la directiva de plantilla. Use la directiva de parámetros para obtener valores:

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

En un procesador de directivas, puede llamar a ITextTemplatingEngineHost.ResolveParameterValue:

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

Nota:

ResolveParameterValue obtiene datos de T4ParameterValues solo cuando se usa MSBuild. Al transformar la plantilla mediante Visual Studio, los parámetros tienen valores predeterminados.

Uso de propiedades de proyecto en directivas de ensamblado e inclusión

Las macros de Visual Studio como $(SolutionDir) no funcionan en MSBuild. En su lugar, puede usar las propiedades del proyecto.

Edite el archivo .csproj o .vbproj para definir una propiedad de proyecto. En este ejemplo se define una propiedad denominada 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>

Ahora puede usar la propiedad del proyecto en las directivas de ensamblado e inclusión:

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

Estas directivas obtienen valores de T4parameterValues tanto en MSBuild como en hosts de Visual Studio.

Preguntas y respuestas

¿Por qué querría transformar plantillas en el servidor de compilación? Ya transformé plantillas en Visual Studio antes de confirmar mi código.

Si actualiza un archivo incluido u otro archivo leído por la plantilla, Visual Studio no transforma el archivo automáticamente. La transformación de plantillas como parte de la compilación garantiza que todo esté actualizado.

¿Qué otras opciones hay para transformar plantillas de texto?

Contenido relacionado

  • Hay una buena guía en la plantilla de T4 MSBuild en %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VisualStudio\v17.0\TextTemplating\Microsoft.TextTemplating.targets
  • Last updated on