Instrucciones para escribir plantillas de texto T4Guidelines for Writing T4 Text Templates

Estas directrices generales que pueden resultar útiles si va a generar código de programa u otros recursos de la aplicación en Visual StudioVisual Studio.These general guidelines might be helpful if you are generating program code or other application resources in Visual StudioVisual Studio. No son fijas reglas.They are not fixed rules.

Directrices para plantillas T4 en tiempo de diseñoGuidelines for Design-Time T4 Templates

Plantillas T4 en tiempo de diseño son plantillas que se va a generar código en su Visual StudioVisual Studio proyecto en tiempo de diseño.Design-time T4 templates are templates that generate code in your Visual StudioVisual Studio project at design time. Para obtener más información, consulte generación de código en tiempo de diseño mediante el uso de plantillas de texto T4.For more information, see Design-Time Code Generation by using T4 Text Templates.

Genere aspectos variables de la aplicación.Generate variable aspects of the application. Generación de código es muy útil para los aspectos de la aplicación que puede cambiar durante el proyecto o cambiará entre diferentes versiones de la aplicación.Code generation is most useful for those aspects of the application that might change during the project, or will change between different versions of the application. Separar estos aspectos variables de los aspectos más permanentes para que se puede determinar con mayor facilidad lo que debe generarse.Separate these variable aspects from the more invariant aspects so that you can more easily determine what has to be generated. 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 de una página a otra.For example, if your application provides a Web site, separate the standard page serving functions from the logic that defines the navigation paths from one page to another.

Codifique los aspectos variables en uno o varios modelos de origen.Encode the variable aspects in one or more source models. Un modelo es un archivo o una base de datos que cada plantilla lee para obtener valores específicos para las partes variables del código que se va a generar.A model is a file or database that each template reads to obtain specific values for variable parts of the code that is to be generated. Los modelos pueden ser bases de datos, archivos XML de diseño, diagramas o lenguajes específicos de dominio.Models can be databases, XML files of your own design, diagrams, or domain-specific languages. Normalmente, se utiliza un modelo para generar varios archivos en un Visual StudioVisual Studio proyecto.Typically, one model is used to generate many files in a Visual StudioVisual Studio project. Cada archivo se genera a partir de una plantilla independiente.Each file is generated from a separate template.

Puede usar más de un modelo en un proyecto.You can use more than one model in a project. Por ejemplo, podría definir un modelo para la navegación entre páginas Web y un modelo independiente para el diseño de las páginas.For example, you might define a model for navigation between Web pages, and a separate model for the layout of the pages.

El modelo se centran en las necesidades y el vocabulario de los usuarios, no en su implementación.Focus the model on the users' needs and vocabulary, not on your implementation. Por ejemplo, en una aplicación de sitio Web, podría esperar el modelo para hacer referencia a las páginas Web e hipervínculos.For example, in a Web site application, you would expect the model to refer to Web pages and hyperlinks.

Idealmente, elija un formato de presentación adecuado para el tipo de información que representa el modelo.Ideally, choose a form of presentation that suits the kind of information that the model represents. Por ejemplo, un modelo de rutas de acceso de navegación a través de un sitio Web podría ser un diagrama de cuadros y flechas.For example, a model of navigation paths through a Web site could be a diagram of boxes and arrows.

Probar el código generado.Test the generated code. Usar pruebas manuales o automatizadas para comprobar que el código resultante funciona tal y como se requieren los usuarios.Use manual or automated tests to verify that the resulting code works as the users require. Evitar la generación de pruebas desde el mismo modelo desde el que se genera el código.Avoid generating tests from the same model from which the code is generated.

En algunos casos, las pruebas generales pueden realizarse directamente en el modelo.In some cases, general tests can be performed on the model directly. Por ejemplo, podría escribir una prueba que garantiza que todas las páginas en el sitio Web pueden tener acceso mediante la navegación desde cualquier otro.For example, you could write a test that ensures that every page in the Web site can be reached by navigation from any other.

Permitir código personalizado: generar clases parciales.Allow for custom code: generate partial classes. Permitir el código que se escribe a mano asimismo el código generado.Allow for code that you write by hand in addition to the generated code. Es raro que un esquema de generación de código para que pueda tener en cuenta todas las variantes posibles que pueden surgir.It is unusual for a code generation scheme to be able to account for all possible variations that might arise. Por lo tanto, debe esperar agregar o reemplazar parte del código generado.Therefore, you should expect to add to or override some of the generated code. Donde el material generado está en un lenguaje de .NET como Visual C#Visual C# o Visual BasicVisual Basic, dos estrategias son especialmente útiles:Where the generated material is in a .NET language such as Visual C#Visual C# or Visual BasicVisual Basic, two strategies are especially useful:

  • Las clases generadas deben ser parciales.The generated classes should be partial. Esto permite agregar contenido al código generado.This lets you to add content to the generated code.

  • Clases deben generarse en pares, uno heredar de la otra.Classes should be generated in pairs, one inheriting from the other. La clase base debe contener todos los métodos generados y propiedades, y la clase derivada debe contener solo los constructores.The base class should contain all the generated methods and properties, and the derived class should contain only the constructors. Esto permite que el código escrito a mano para reemplazar cualquiera de los métodos generados.This allows your hand-written code to override any of the generated methods.

    En otros lenguajes generados como XML, utilice el <#@include#> directiva para realizar combinaciones simples de contenido escrito a mano y generado.In other generated languages such as XML, use the <#@include#> directive to make simple combinations of hand-written and generated content. 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.In more complex cases, you might have to write a post-processing step that combines the generated file with any hand-written files.

    Mover material común en archivos de inclusión o plantillas en tiempo de ejecución para evitar repetir similar bloques de texto y código en varias plantillas, usan el <#@ include #> directiva.Move common material into include files or run-time templates To avoid repeating similar blocks of text and code in multiple templates, use the <#@ include #> directive. Para obtener más información, consulte directiva Include de T4.For more information, see T4 Include Directive.

    Puede también generar plantillas de texto en tiempo de ejecución en un proyecto independiente y, a continuación, llamar a partir de la plantilla en tiempo de diseño.You can also build run-time text templates in a separate project, and then call them from the design-time template. Para ello, use la <#@ assembly #> directiva para tener acceso al proyecto independiente.To do this, use the <#@ assembly #> directive to access the separate project. Para obtener ejemplos, vea "Herencia en plantillas de texto" en el Blog de Gareth Jones.For examples, see "Inheritance in Text Templates" in Gareth Jones' Blog.

    Considere la posibilidad de mover grandes bloques de código en un ensamblado independiente.Consider moving large blocks of code into a separate assembly. Si tiene bloques de código grande y bloques de características de clase, puede ser útil mover algunas de este código en métodos que se compilan en un proyecto independiente.If you have large code blocks and class feature blocks, it might be useful to move some of this code into methods that you compile in a separate project. Puede usar el <#@ assembly #> directiva para obtener acceso al código de la plantilla.You can use the <#@ assembly #> directive to access the code in the template. Para obtener más información, consulte directiva de ensamblado T4.For more information, see T4 Assembly Directive.

    Puede colocar los métodos en una clase abstracta que puede heredar la plantilla.You can put the methods in an abstract class that the template can inherit. La clase abstracta debe heredar de Microsoft.VisualStudio.TextTemplating.TextTransformation.The abstract class must inherit from Microsoft.VisualStudio.TextTemplating.TextTransformation. Para obtener más información, consulte directiva de plantilla de T4.For more information, see T4 Template Directive.

    Generar el código, no archivos un método de configuración de la escritura de una aplicación variable consiste en escribir código de programa genérico que acepta un archivo de configuración.Generate code, not configuration files One method of writing a variable application is to write generic program code that accepts a configuration file. Una aplicación escrita de esta manera es muy flexible y puede volver a configurar cuando cambien los requisitos empresariales, sin volver a generar la aplicación.An application written in this manner is very flexible, and can be reconfigured when the business requirements change, without rebuilding the application. Sin embargo, un inconveniente de este enfoque es que la aplicación realizará peor rendimiento de una aplicación más específica.However, a drawback of this approach is that the application will perform less well than a more specific application. 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.Also, its program code will be more difficult to read and maintain, partly because it has always to deal with the most generic types.

    Por el contrario, una aplicación cuyas partes variables se generan antes de la compilación puede estar fuertemente tipada.By contrast, an application whose variable parts are generated before compilation can be strongly typed. Esto hace mucho más fácil y confiables escribir código escrita a mano e integrar con las partes del software.This makes it much easier and more reliable to write hand-written code and integrate it with the generated parts of the software.

    Para obtener todas las ventajas de generación de código, intente generar código de programa en lugar de archivos de configuración.To obtain the full benefit of code generation, try to generate program code instead of configuration files.

    Use una carpeta de código generado por colocar las plantillas y los archivos generados en una carpeta de proyecto denominada código generado, de modo que lo desactive que éstos no son archivos que deben editarse directamente.Use a Generated Code folder Place the templates and the generated files in a project folder named Generated Code, to make it clear that these are not files that should be edited directly. Si crea código personalizado para invalidar o agregar a las clases generadas, coloque estas clases en una carpeta que se denomina código personalizado.If you create custom code to override or add to the generated classes, place those classes in a folder that is named Custom Code. La estructura de un proyecto típico tiene el siguiente aspecto:The structure of a typical project looks like this:

MyProject
   Custom Code
      Class1.cs
      Class2.cs
   Generated Code
      Class1.tt
          Class1.cs
      Class2.tt
          Class2.cs
   AnotherClass.cs

Directrices para plantillas T4 de tiempo de ejecución (preprocesada)Guidelines for Run-Time (Preprocessed) T4 Templates

Mover material común en plantillas heredadas pueden usar la herencia para compartir los métodos y bloques de texto entre plantillas de texto T4.Move common material into inherited templates You can use inheritance to share methods and text blocks between T4 text templates. Para obtener más información, consulte directiva de plantilla de T4.For more information, see T4 Template Directive.

También puede usar incluyen archivos que tienen plantillas en tiempo de ejecución.You can also use include files that have run-time templates.

Mover grandes cuerpos de código en una clase parcial.Move large bodies of code into a partial class. Cada plantilla en tiempo de ejecución genera una definición de clase parcial que tiene el mismo nombre que la plantilla.Each run-time template generates a partial class definition that has the same name as the template. Puede escribir un archivo de código que contiene otra definición parcial de la misma clase.You can write a code file that contains another partial definition of the same class. Puede agregar métodos, campos y constructores para la clase de esta manera.You can add methods, fields, and constructors to the class in this manner. Estos miembros se pueden llamar desde los bloques de código en la plantilla.These members can be called from the code blocks in the template.

La ventaja de hacerlo es que el código sea más fácil escribir, porque IntelliSense está disponible.An advantage of doing this is that the code is easier to write, because IntelliSense is available. Además, puede lograr una mejor separación entre la presentación y la lógica subyacente.Also, you can achieve a better separation between the presentation and the underlying logic.

Por ejemplo, en MyReportText.tt:For example, in MyReportText.tt:

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

En MyReportText Methods.cs:In MyReportText-Methods.cs:

private string ComputeTotal() { ... }

Permitir código personalizado: proporcionar puntos de extensión considere la posibilidad de generación de métodos virtuales en <bloques de características de clase #+ #>.Allow for custom code: provide extension points Consider generating virtual methods in <#+ class feature blocks #>. Esto permite que una única plantilla para su uso en muchos contextos sin ninguna modificación.This allows a single template to be used in many contexts without modification. En lugar de modificar la plantilla, puede construir una clase derivada que proporciona la lógica adicional mínima.Instead of modifying the template, you can construct a derived class which supplies the minimum additional logic. La clase derivada puede ser cualquier código normal, o puede ser una plantilla en tiempo de ejecución.The derived class can be either regular code, or it can be a run-time template.

Por ejemplo, en MyStandardRunTimeTemplate.tt:For example, in MyStandardRunTimeTemplate.tt:

This page is copyright <#= CompanyName() #>.
<#+ protected virtual string CompanyName() { return ""; } #>

En el código de una aplicación:In the code of an application:

class FabrikamTemplate : MyStandardRunTimeTemplate
{
  protected override string CompanyName() { return "Fabrikam"; }
}
...
  string PageToDisplay = new FabrikamTemplate().TextTransform();

Directrices para todas las plantillas T4Guidelines for All T4 Templates

Recopilación de datos independiente de la generación de texto intente evitar mezclar cálculo y bloques de texto.Separate data-gathering from text generation Try to avoid mixing computation and text blocks. En cada plantilla de texto, utilice la primera <# de bloque de código de # > para establecer las variables y realizar cálculos complejos.In each text template, use the first <# code block #> to set variables and perform complex computations. Desde el primer bloque de texto hasta el final de la plantilla o la primera <característica de clase #+ Bloquear #>, evitar expresiones largas y evitar condicionales y bucles a menos que contengan bloques de texto.From the first text block down to the end of the template or the first <#+ class feature block #>, avoid long expressions, and avoid loops and conditionals unless they contain text blocks. Esta práctica hace que la plantilla sea más fácil de leer y mantener.This practice makes the template easier to read and maintain.

No utilice .tt para incluir archivos usan una extensión de nombre de archivo diferente como .ttinclude archivos de inclusión.Don't use .tt for include files Use a different file name extension such as .ttinclude for include files. Use .tt solamente los archivos que se vayan a ser procesan ya sea como tiempo de ejecución o en tiempo de diseño de plantillas de texto.Use .tt only for files that you want to be processed either as run-time or design-time text templates. En algunos casos, Visual StudioVisual Studio reconoce .tt archivos y configura automáticamente sus propiedades para su procesamiento.In some cases, Visual StudioVisual Studio recognizes .tt files and automatically sets their properties for processing.

Inicie cada plantilla como un prototipo fijo.Start each template as a fixed prototype. Escribir un ejemplo del código o el texto que desea generar y asegúrese de que es correcta.Write an example of the code or text that you want to generate, and make sure that it is correct. A continuación, cambie su extensión a .tt e incrementalmente insertar código que modifica el contenido leyendo el modelo.Then change its extension to .tt and incrementally insert code that modifies the content by reading the model.

Considere el uso de modelos con tipo.Consider using typed models. Aunque puede crear un esquema XML o base de datos para los modelos, puede ser útil crear un lenguaje específico de dominio (DSL).Although you can create an XML or database schema for your models, it might be useful to create a domain specific language (DSL). Un DSL tiene la ventaja de que genera una clase para representar cada nodo en el esquema y propiedades para representar los atributos.A DSL has the advantage that it generates a class to represent each node in the schema, and properties to represent the attributes. Esto significa que se puede programar en términos del modelo de negocio.This means that you can program in terms of the business model. Por ejemplo:For example:

Team Members:
<# foreach (Person p in team.Members)
 { #>
    <#= p.Name #>
<# } #>

Considere el uso de diagramas para los modelos.Consider using diagrams for your models. Muchos modelos de forma más eficaz se presentan y se administran simplemente como tablas de texto, especialmente si son muy grandes.Many models are most effectively presented and managed simply as text tables, especially if they are very large.

Sin embargo, para algunos tipos de requisitos empresariales, es importante aclarar conjuntos complejos de relaciones y flujos de trabajo y los diagramas son el mejor medio adecuado.However, for some kinds of business requirements, it is important to clarify complex sets of relationships and work flows, and diagrams are the best suited medium. Una ventaja de un diagrama es que resulta fácil debatir con los usuarios y otras partes interesadas.An advantage of a diagram is that it is easy to discuss with users and other stakeholders. Mediante la generación de código de un modelo en el nivel de los requisitos empresariales, el código resulta más flexible cuando cambian los requisitos.By generating code from a model at the level of business requirements, you make your code more flexible when the requirements change.

También puede diseñar su propio tipo de diagrama como un lenguaje específico de dominio (DSL).You can also design your own type of diagram as a domain-specific language (DSL). UML y lenguajes DSL puede generar código.Code can be generated from both UML and DSLs. Para obtener más información, consulte analizar y modelar la arquitectura.For more information, see Analyzing and Modeling Architecture.

Vea tambiénSee Also