Generación de código en un proceso de compilación
Puede invocar la transformación de texto como parte del proceso de compilación de una solución de Visual Studio. Puede utilizar esto para garantizar que los archivos generados de las plantillas están actualizados antes de que se compilen. Esto le permite evitar una situación en la que el usuario se olvide de hacer clic en Transformar todas las plantillas antes de compilar el proyecto o comprobar en código. Las tareas de transformación de texto pueden ser realizadas tanto por Visual Studio o MSBuild y en un servidor de compilación.
Incluir tareas de transformación de texto en archivos de proyecto
Instalar el SDK de visualización y modelado
Para habilitar las tareas de compilación en el equipo de desarrollo, instale Visual Studio Visualization and Modeling SDK.
Para habilitar las tareas de compilación en un servidor de compilación, vea Transformación de texto en un servidor de compilación.
Editar el archivo de proyecto
Para invocar la transformación de texto, tiene que editar el archivo que define el proyecto. Estas propiedades no se pueden editar en el editor de propiedades de proyecto. Por tanto, debe cerrar el proyecto y editarlo como un archivo de texto.
Para editar el texto del archivo de proyecto
En el Explorador de soluciones, haga clic con el botón secundario en el proyecto y, a continuación, seleccione Descargar el proyecto.
Haga clic con el botón secundario de nuevo en el proyecto y, a continuación, haga clic en Editar proyecto.
El texto del archivo de proyecto aparece en el editor XML.
Para volver a abrir el proyecto después de finalizar la edición
Cierre el editor de XML.
En el Explorador de soluciones, haga clic con el botón secundario en el proyecto y, a continuación, seleccione Volver a cargar el proyecto.
Importar los destinos de transformación de texto
Las tareas de compilación de transformación de texto se definen en un único archivo. Debe importarlo después de los destinos estándar de C# o Visual Basic.
Para importar los destinos de transformación de texto
Busque en el archivo una línea similar a una de estas líneas:
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
-O bien-
<Import Project="$(MSBuildToolsPath)\Microsoft.VisualBasic.targets" />
Después de esa línea, inserte la importación de TextTemplating:
<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\TextTemplating\v10.0\Microsoft.TextTemplating.targets" />
Establecer propiedades para controlar cómo se realiza la compilación
Inserte el siguiente texto en el archivo de proyecto. Vea las siguientes secciones para conocer otras propiedades que se pueden insertar en este grupo de propiedades.
<PropertyGroup>
<TransformOnBuild>true</TransformOnBuild>
<!-- Other properties can be inserted here -->
</PropertyGroup>
TransformOnBuild hace que todas las plantillas del proyecto se ejecuten al compilar el proyecto.
Invocar una transformación
Transformar todas las plantillas en una compilación de proyecto
Si incluye la siguiente propiedad en el archivo de proyecto, todas las plantillas de texto del proyecto se ejecutarán cada vez que compile el proyecto, en función de la característica de compilación incremental.
<TransformOnBuild>true</TransformOnBuild>
Puede invocar las transformaciones presionando F5 en Visual Studio o mediante MSBuild. Por ejemplo:
msbuild myproject.csproj
Si omite TransformOnBuild o lo establece en false, las plantillas no se transformarán como una parte automática de la compilación del proyecto.
Agregar rutas de acceso de referencia
Puede agregar rutas de acceso al conjunto de rutas de acceso donde el host busca los ensamblados a los que se hace referencia en las plantillas. Por ejemplo:
<ItemGroup>
<!-- Add VS\...\PublicAssemblies to the list of places
to look for assemblies used by templates. -->
<T4ReferencePath Include="$(VsIdePath)PublicAssemblies\" />
</ItemGroup>
Transformar plantillas específicas
Puede transformar archivos especificados si invoca la Transform tarea con la utilidad msbuild. Esta tarea no depende de la propiedad TransformOnBuild y no compila los archivos de proyecto. Debe importar el archivo de destinos de la plantilla de texto tal como se ha descrito en una sección anterior.
Por ejemplo, para transformar un archivo específico:
msbuild myproj.proj /t:Transform /p:TransformFile=MyTemplate.tt
También puede utilizar caracteres comodín en el parámetro TransformFile. Por ejemplo, este comando transforma todos los archivos .tt de la carpeta GeneratedCode:
msbuild dsl.csproj /t:Transform /p:TransformFile="GeneratedCode\**\*.tt"
Generación incremental
De forma predeterminada, el administrador de la compilación evita ejecutar una plantilla si su archivo de salida está actualizado. Para ello, supervisa el sistema de archivos para ver qué archivos se leen en el código de plantilla. En ocasiones posteriores, compara las fechas de modificación de estos archivos con la fecha del archivo de salida. Ejecuta la plantilla si algún archivo de entrada se modificó más recientemente que el archivo de salida. La plantilla también se ejecuta si no hay ninguna información sobre las ejecuciones anteriores de esta plantilla.
El resultado es que el archivo de salida se volverá a generar si es anterior a cualquiera de los siguientes archivos:
El archivo de plantilla de texto
Archivos que se especifican en directivas <#@include#>
Archivos que se leen en el código de la plantilla
Archivos que se incluyen o se leen en un procesador de directivas utilizado en la plantilla
Si desea asegurarse de que todas las plantillas se ejecutan en cada compilación, inserte esta propiedad:
<TransformOutOfDateOnly>false</TransformOutOfDateOnly>
Control de código fuente
No hay ninguna integración específica con un sistema de control de código fuente. Sin embargo, puede agregar sus propias extensiones, por ejemplo para desproteger y proteger un archivo generado.
De forma predeterminada, la tarea de transformación de texto evita sobrescribir un archivo marcado como solo lectura; cuando se encuentra un archivo de este tipo, se registra un error en la lista de errores de Visual Studio y se produce un error en la tarea.
Para especificar que los archivos de solo lectura se deben sobrescribir, inserte esta propiedad:
<OverwriteReadOnlyOuputFiles>true</OverwriteReadOnlyOuputFiles>
A menos que personalice el paso de procesamiento posterior, se registrará una advertencia en la lista de errores cuando se sobrescriba un archivo.
Personalizar el proceso de compilación
Puede personalizar el proceso de compilación, por ejemplo para desproteger archivos que se han sobrescrito. Se proporcionan dos puntos de personalización, a los que se llama antes y después de la transformación.
Para definir estos puntos, defina las propiedades $(BeforeTransform) y $(AfterTransform).
Por ejemplo:
<PropertyGroup>
<BeforeTransform>CustomPreTransform</BeforeTransform>
<AfterTransform>CustomPostTransform;$(AfterTransform)</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 las siguientes listas:
GeneratedFiles: lista de archivos en los que ha escrito el proceso. En los archivos que sobrescribieron archivos de solo lectura existentes, %(GeneratedFiles.ReadOnlyFileOverwritten) será true. Estos archivos se pueden desproteger del control de código fuente.
NonGeneratedFiles: lista de archivos de solo lectura que no se sobrescribieron.
Con estas listas puede, por ejemplo, desproteger los archivos sobrescritos.
Transformación de texto en un servidor de compilación
Si el servidor de compilación se ejecuta en un equipo en el que no está instalado Visual Studio, debe copiar los siguientes archivos en el equipo de compilación de un equipo en el que está instalado Visual Studio SDK:
\Archivos de programa\Microsoft Visual Studio 2010 SDK\VisualStudioIntegration\Common\Assemblies\v4 .0 \
Microsoft.VisualStudio.TextTemplating.10.0.dll
Microsoft.VisualStudio.TextTemplating.Interfaces.10.0.dll
Microsoft.VisualStudio.TextTemplating.VSHost.10.0.dll
\Archivos de programa\MSBuild\Microsoft\VisualStudio\TextTemplating\v10.0\
- Microsoft.VisualStudio.TextTemplating.Sdk.Host.10.0.dll
\Archivos de programa\Microsoft Visual Studio 10.0\Common7\IDE\PublicAssemblies\
- Microsoft.VisualStudio.TextTemplating.Modeling.10.0.dll
Para obtener más información, vea Crear y trabajar con un controlador de compilación.