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 Programa para la mejoraVisual Studio.These general guidelines might be helpful if you are generating program code or other application resources in Programa para la mejoraVisual Studio. Las reglas no son fijas.They are not fixed rules.

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

Plantillas T4 en tiempo de diseño son plantillas que generan código en su Programa para la mejoraVisual Studio proyecto en tiempo de diseño.Design-time T4 templates are templates that generate code in your Programa para la mejoraVisual Studio project at design time. Para obtener más información, consulte generación de código de 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 pueden 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 invariables para que se puede determinar con mayor facilidad lo que se va a generar.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 website, 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 lee cada plantilla para obtener los 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 su propio diseño, los 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 Programa para la mejoraVisual Studio proyecto.Typically, one model is used to generate many files in a Programa para la mejoraVisual 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.

Centrar el modelo de necesidades de los usuarios y el vocabulario y no de 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, cabría esperar el modelo para hacer referencia a las páginas web e hipervínculos.For example, in a website application, you would expect the model to refer to web pages and hyperlinks.

Lo ideal es elegir un formato de presentación que se adapte a la clase 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 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 website could be a diagram of boxes and arrows.

Probar el código generado.Test the generated code. Use pruebas manuales o automatizadas para comprobar que el código resultante funciona según los usuarios necesitan.Use manual or automated tests to verify that the resulting code works as the users require. Evite 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 se pueden llegar desde desde cualquier otro.For example, you could write a test that ensures that every page in the website 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 además del 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 que pueda tener en cuenta todas las variaciones 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 .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.

  • Las clases deben generarse en parejas, 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 las 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 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 combina 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 a los 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 crear plantillas de texto en tiempo de ejecución en un proyecto independiente y, a continuación, llame 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 el <#@ assembly #> directiva de 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 cantidades de código en un ensamblado independiente.Consider moving large blocks of code into a separate assembly. Si dispone de los bloques de código de gran tamaño y bloques de características de clase, podría ser útil mover parte de este código en métodos que se compilación 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 tener acceso al código en 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 T4.For more information, see T4 Template Directive.

    Generar código, no archivos un método de configuración de la escritura de una aplicación de la variable es 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 configurarse cuando cambian 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 llevará a cabo bien que 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 genéricos más.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 facilita mucho más fáciles y más confiables para escribir código escrito a mano y cómo integrarlo con generado 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 la generación de código, intente generar código de programa en lugar de los archivos de configuración.To obtain the full benefit of code generation, try to generate program code instead of configuration files.

    Use una carpeta Generated Code coloque las plantillas y los archivos generados en una carpeta de proyecto denominada código generado, para asegurarse de desactive que estos 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 este 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 las plantillas T4 de tiempo de ejecución (preprocesada)Guidelines for Run-Time (Preprocessed) T4 Templates

Mover material común en las plantillas heredadas puede usar la herencia para compartir los métodos y los bloques de texto entre las 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 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 cantidades 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 pueden llamarse desde los bloques de código en la plantilla.These members can be called from the code blocks in the template.

Una ventaja de hacerlo es que el código es más fácil de 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 que considere la posibilidad de generación de métodos virtuales en <bloquea la característica de clase #+ #>.Allow for custom code: provide extension points Consider generating virtual methods in <#+ class feature blocks #>. Esto permite que una sola 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 intentan evitar la mezcla de 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, use la primera <código # Bloquear #> 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 instrucciones condicionales y bucles a menos que contengan los 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 sea más fácil de leer y mantener la plantilla.This practice makes the template easier to read and maintain.

No use .tt para incluir archivos de 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 desea que se puede procesan las plantillas de texto como tiempo de ejecución o tiempo de diseño.Use .tt only for files that you want to be processed either as run-time or design-time text templates. En algunos casos, Programa para la mejoraVisual Studio reconoce .tt archivos y automáticamente se establecen sus propiedades para su procesamiento.In some cases, Programa para la mejoraVisual Studio recognizes .tt files and automatically sets their properties for processing.

Cada plantilla de inicio 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, lea el modelo.Then change its extension to .tt and incrementally insert code that modifies the content by reading the model.

Considere la posibilidad de usar modelos tipados.Consider using typed models. Aunque puede crear un esquema XML o base de datos para los modelos, podría 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 no tiene la ventaja 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 se presenta la forma más eficaz 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 de tratar con los usuarios y otras partes interesadas.An advantage of a diagram is that it is easy to discuss with users and other stakeholders. Al generar código a partir de un modelo en el nivel de los requisitos empresariales, hará que el código más flexible cuando cambien 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). Puede generar código de UML y lenguajes DSL.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