Instrucciones para escribir plantillas de texto T4

Artículo
06/09/2015

Estas directrices generales pueden resultar útiles si genera código de programa u otros recursos de la aplicación en Visual Studio. No son reglas fijas.

Instrucciones para las plantillas T4 en tiempo de diseño

Las plantillas T4 en tiempo de diseño son plantillas que generan código en el proyecto de Visual Studio en tiempo de diseño. Para obtener más información, vea Generación de código en tiempo de diseño usando las plantillas de texto T4.

Genere aspectos variables de la aplicación.
La generación de código es muy útil para los aspectos de la aplicación que pueden cambiar durante el proyecto o que cambiarán entre las distintas versiones de la aplicación. Separe estos aspectos variables de los aspectos más permanentes para poder determinar con mayor facilidad lo que se tiene que generar. Por ejemplo, si la aplicación proporciona un sitio web, separe la página estándar que proporciona funciones de la lógica que define las rutas de navegación entre las páginas.
Codifique los aspectos variables en uno o más modelos de origen.
Un modelo es un archivo o base de datos que cada plantilla lee para obtener valores concretos para las partes variables del código que se va a generar. Los modelos pueden ser bases de datos, archivos XML de diseño propio, diagramas o lenguajes específicos de dominio. Normalmente, un modelo se utiliza para generar muchos archivos en un proyecto de Visual Studio. Cada archivo se genera en una plantilla independiente.

Puede utilizar más de un modelo en un proyecto. Por ejemplo, puede definir un modelo para la navegación entre páginas web y un modelo independiente para el diseño de las páginas.
Centre el modelo en las necesidades y vocabulario de los usuarios, no en su implementación.
Por ejemplo, en una aplicación de sitio web, se espera el modelo para hacer referencia a páginas web e hipervínculos.

Lo ideal sería elegir un formato de presentación adecuado para el tipo de información que el modelo representa. Por ejemplo, un modelo de rutas de navegación en un sitio web puede ser un diagrama de cuadros y flechas.
Pruebe el código generado.
Use pruebas manuales o automatizadas para comprobar que el código resultante funciona cuando los usuarios lo necesitan. Evite generar pruebas del mismo modelo del que se genera el código.

En algunos casos, se pueden realizar pruebas generales directamente en el modelo. Por ejemplo, puede escribir una prueba para asegurarse de que se puede navegar a cada página del sitio web desde todas las demás páginas.
Permita código personalizado: genere clases parciales.
Permita código escrito a mano además del código generado. Es raro que un esquema de generación de código pueda responder a todas las posibles variaciones que podrían surgir. Por tanto, debe esperar agregar a, o reemplazar, parte del código generado. Si el material generado está en un lenguaje .NET como Visual C# o Visual Basic, existen dos estrategias especialmente útiles:
- Las clases generadas deben ser parciales. Esto permite agregar contenido al código generado.
- Las clases se deben generar por pares y una debe heredar de la otra. La clase base debe contener todos los métodos y propiedades generados, y la clase derivada debe contener solo los constructores. Esto permite que el código escrito a mano reemplace los métodos generados.
En otros lenguajes generados como XML, utilice la directiva <#@include#> para realizar combinaciones simples de contenido escrito a mano y contenido generado. En casos más complejos, es posible que deba escribir un paso posterior al procesamiento que combine el archivo generado con los archivos escritos a mano.
Mueva el material común dentro de archivos de inclusión o plantillas en tiempo de ejecución
Para evitar la repetición de bloques similares de texto y código en varias plantillas, use la directiva <#@ include #>. Para obtener más información, vea Directiva Include T4.

También puede compilar plantillas de texto en tiempo de ejecución en un proyecto independiente, y luego llamarlas desde la plantilla en tiempo de diseño. Para ello, use la directiva <#@ assembly #> para obtener acceso al proyecto independiente. Para obtener ejemplos, vea "Inheritance in Text Templates" en el blog de Gareth Jones.
Considere mover grandes bloques de código a un ensamblado independiente.
Si hay grandes bloques de código y bloques de característica de clase, puede ser útil mover parte de este código a los métodos que se compilan en un proyecto independiente. Puede usar la directiva <#@ assembly #> para obtener acceso al código en la plantilla. Para obtener más información, vea Directiva de ensamblado T4.

Puede colocar métodos en una clase abstracta que puede heredar la plantilla. La clase abstracta debe heredar de TextTransformation. Para obtener más información, vea Directiva de plantilla T4.
Genere código, no archivos de configuración
Un método para escribir una aplicación variable consiste en escribir código de programa genérico que acepte un archivo de configuración. Una aplicación escrita de esta manera es muy flexible y se puede volver a configurar cuando cambien los requisitos comerciales, sin necesidad de recompilar la aplicación. Sin embargo, una desventaja de este enfoque es que la aplicación tendrá un rendimiento menor que una aplicación más específica. Además, su código de programa será más difícil de leer y mantener, en parte porque siempre tiene que tratar con los tipos más genéricos.

Por el contrario, una aplicación cuyas partes variables se generan antes de la compilación puede estar fuertemente tipada. Esto hace que resulte más fácil y confiable escribir código a mano e integrarlo con las partes generadas del software.

Para obtener todas las ventajas de la generación de código, intente generar código de programa en lugar de archivos de configuración.
Use una carpeta de código generado
Coloque las plantillas y los archivos generados en una carpeta de proyecto denominada Código generado, para dejar claro que estos archivos no se deben editar directamente. Si crea código personalizado para reemplazar, o agregar a, las clases generadas, coloque estas clases en una carpeta que se denomine Código personalizado. La estructura de un proyecto típico tiene el siguiente aspecto:
```
MyProject
   Custom Code
      Class1.cs
      Class2.cs
   Generated Code
      Class1.tt
          Class1.cs
      Class2.tt
          Class2.cs
   AnotherClass.cs
```

Instrucciones para plantillas T4 (preprocesadas) en tiempo de ejecución

Mueva el material común a las plantillas heredadas
Puede utilizar la herencia para compartir métodos y bloques de texto entre plantillas T4 de texto. Para obtener más información, vea Directiva de plantilla T4.

También puede utilizar archivos de inclusión que tienen plantillas en tiempo de ejecución.
Mueva grandes cuerpos de código a una clase parcial.
Cada plantilla en tiempo de ejecución genera una definición de clase parcial con el mismo nombre que la plantilla. Puede escribir un archivo de código que contiene otra definición parcial de la misma clase. De esta manera, puede agregar métodos, campos y constructores a la clase. Se puede llamar a estos miembros desde los bloques de código en la plantilla.

Una ventaja de hacer esto es que el código es más sencillo de escribir, porque IntelliSense está disponible. Asimismo, puede lograr una mejor separación entre la presentación y la lógica subyacente.

Por ejemplo, en MyReportText.tt:

The total is: <#= ComputeTotal() #>

En MyReportText-Methods.cs:

private string ComputeTotal() { ... }
Permita código personalizado: proporcione puntos de extensión
Considere la posibilidad de generar métodos virtuales en<#+ class feature blocks #>. Esto permite utilizar una plantilla única en muchos contextos sin modificación. En lugar de modificar la plantilla, puede crear una clase derivada que proporciona la lógica adicional mínima. La clase derivada puede ser código normal o una plantilla en tiempo de ejecución.

Por ejemplo, en MyStandardRunTimeTemplate.tt:
```
This page is copyright <#= CompanyName() #>.
<#+ protected virtual string CompanyName() { return ""; } #>
```
En el código de una aplicación:
```
class FabrikamTemplate : MyStandardRunTimeTemplate
{
  protected override string CompanyName() { return "Fabrikam"; }
}
...
  string PageToDisplay = new FabrikamTemplate().TextTransform();
```

Instrucciones para todas las plantillas T4

Separe la recolección de datos de la generación de texto
Intente evitar mezclar bloques de texto y cálculo. En cada plantilla de texto, utilice el primero<# code block #> para establecer las variables y realizar los cómputos complejos. Del primer bloque de texto hasta el final de la plantilla o el primer<#+ class feature block #>, evite expresiones largas, así como bucles y condiciones a menos que contengan bloques de texto. Este ejercicio facilita la lectura y el mantenimiento de la plantilla.
Evite el uso de la extensión .tt para archivos de inclusión
Utilice una extensión de nombre de archivo diferente como .ttinclude para los archivos de inclusión. Utilice la extensión .tt solo para los archivos que desea que se procesen como plantillas de texto en tiempo de ejecución o en tiempo de diseño. En algunos casos, Visual Studio reconoce archivos .tt y establece automáticamente sus propiedades para procesar.
Inicie cada plantilla como un prototipo fijo.
Escriba un ejemplo del código o texto que desea generar y asegúrese de que es correcto. A continuación, cambie su extensión a .tt e inserte incrementalmente código que modifique el contenido leyendo el modelo.
Considere el uso de modelos con tipo.
Aunque puede crear un archivo XML o esquema de la base de datos para los modelos, puede ser útil crear un lenguaje específico del dominio (ADSL). Un ADSL tiene la ventaja de que genera una clase para representar cada nodo en el esquema, así como propiedades que representan a los atributos. Esto significa que puede programar en términos del modelo de negocio. Por ejemplo:
```
Team Members:
<# foreach (Person p in team.Members) 
 { #> 
    <#= p.Name #> 
<# } #>
```
Considerar el uso de diagramas para los modelos.
Muchos modelos se presentan y administran eficazmente simplemente como tablas de texto, sobre todo si son muy grandes.

Sin embargo, para algunos tipos de requisitos comerciales, es importante clarificar conjuntos complejos de relaciones y flujos de trabajo, y los diagramas son el medio que mejor se adapta. Una ventaja de un diagrama es que es fácil debatir con usuarios y otras partes interesadas. Mediante la generación de código de un modelo en el nivel de requisitos comerciales, el código se hace más flexible cuando los requisitos cambian.

Con frecuencia, las clases UML y los diagramas de actividad pueden estar adaptados para estos fines. También puede diseñar su propio tipo de diagrama como un lenguaje específico del dominio (ADSL). El código se puede generar a partir de clases UML y lenguajes específicos del dominio (ADSL). Para obtener más información, vea Modelar la aplicación y Modelar la aplicación.

Vea también

Conceptos

Generación de código en tiempo de diseño usando las plantillas de texto T4

Generación de texto en tiempo de ejecución con plantillas de texto T4

Compartir a través de