Escribir una plantilla de texto T4Writing a T4 Text Template

Una plantilla de texto contiene el texto que se generará a partir de ella.A text template contains the text that will be generated from it. Por ejemplo, una plantilla que crea una página web contendrá "<html >..." y todas las demás partes estándar de una página HTML.For example, a template that creates a web page will contain "<html>..." and all the other standard parts of an HTML page. Inserta en la plantilla son bloques de control, que son fragmentos de código de programa.Inserted into the template are control blocks, which are fragments of program code. Los bloques de control proporcionan valores variables y permiten que partes del texto sean condiciones y se repitan.Control blocks provide varying values and allow parts of the text to be conditional and repeated.

Esta estructura hace que una plantilla sea fácil de desarrollar, porque se puede comenzar con un prototipo del archivo generado e incrementalmente insertar bloques de control que modifican el resultado.This structure makes a template easy to develop, because you can start with a prototype of the generated file, and incrementally insert control blocks that vary the result.

Las plantillas de texto se componen de las siguientes partes:Text templates are composed of the following parts:

  • Directivas -elementos que controlan cómo se procesa la plantilla.Directives - elements that control how the template is processed.

  • Bloques de texto : contenido que se copia directamente en la salida.Text blocks - content that is copied directly to the output.

  • Bloques de control -código de programa que inserta valores variables en el texto y controla las partes condicionales o repetidas del texto.Control blocks - program code that inserts variable values into the text, and controls conditional or repeated parts of the text.

Para probar los ejemplos de este tema, cópielos en un archivo de plantilla como se describe en generación de código de tiempo de diseño mediante el uso de plantillas de texto T4.To try the examples in this topic, copy them into a template file as described in Design-Time Code Generation by using T4 Text Templates. Después de editar el archivo de plantilla, guárdelo y, a continuación, inspeccione la salida .txt archivo.After editing the template file, save it, and then inspect the output .txt file.

DirectivasDirectives

Las directivas de plantilla de texto proporcionan instrucciones generales al motor de creación de plantillas de texto sobre cómo generar el código de transformación y el archivo de salida.Text template directives provide general instructions to the text templating engine about how to generate the transformation code and the output file.

Por ejemplo, la siguiente directiva especifica que el archivo de salida debe tener una extensión .txt:For example, the following directive specifies that the output file should have a .txt extension:

<#@ output extension=".txt" #>

Para obtener más información sobre las directivas, consulte directivas de plantilla de texto T4.For more information about directives, see T4 Text Template Directives.

Bloques de textoText blocks

Un bloque de texto inserta texto directamente en el archivo de salida.A text block inserts text directly into the output file. No existe ningún formato especial para los bloques de texto.There is no special formatting for text blocks. Por ejemplo, la siguiente plantilla de texto generará un archivo de texto con la palabra "Hello":For example, the following text template will produce a text file that contains the word "Hello":

<#@ output extension=".txt" #>
Hello

Bloques de controlControl blocks

Los bloques de control son secciones de código de programa que se utilizan para transformar las plantillas.Control blocks are sections of program code that are used to transform the templates. El lenguaje predeterminado es C#, pero para utilizar Visual BasicVisual Basic puede escribir esta directiva al principio del archivo:The default language is C#, but to use Visual BasicVisual Basic, you can write this directive at the beginning of the file:

<#@ template language="VB" #>

El lenguaje en el que escribe el código de los bloques de control no está relacionado con el lenguaje del texto que se genera.The language in which you write the code in the control blocks is unrelated to the language of the text that is generated.

Bloques de control estándarStandard control blocks

Un bloque de control estándar es una sección de código de programa que genera parte del archivo de salida.A standard control block is a section of program code that generates part of the output file.

Puede mezclar cualquier número de bloques de texto y bloques de control estándar en un archivo de plantilla.You can mix any number of text blocks and standard control blocks in a template file. Sin embargo, no puede colocar un bloque de control dentro de otro.However, you cannot place one control block inside another. Cada bloque de control estándar se delimita con los símbolos <# ... #>.Each standard control block is delimited by the symbols <# ... #>.

Por ejemplo, los bloques siguientes de control y de texto establecen que el archivo de salida contenga la línea "0, 1, 2, 3, 4 Hello!":For example, the following control block and text block cause the output file to contain the line "0, 1, 2, 3, 4 Hello!":

<#
    for(int i = 0; i < 4; i++)
    {
        Write(i + ", ");
    }
    Write("4");
#> Hello!

En lugar de utilizar instrucciones Write() explícitas, puede intercalar texto y código.Instead of using explicit Write() statements, you can interleave text and code. En el ejemplo siguiente se imprime "¡Hello!"The following example prints "Hello!" cuatro veces:four times:

<#
    for(int i = 0; i < 4; i++)
    {
#>
Hello!
<#
    }
#>

Puede insertar un bloque de texto en cualquier posición del código donde se podría incluir una instrucción Write();.You can insert a text block wherever a Write(); statement would be allowed in the code.

Note

Al incrustar un bloque de texto dentro de una instrucción compuesta como un bucle o condicional, debe usar siempre corchetes {...}When you embed a text block within a compound statement such as a loop or conditional, always use braces {...} para contener el bloque de texto.to contain the text block.

Bloques de control de expresionesExpression control blocks

Un bloque de control de expresiones da como resulta una expresión y la convierte en una cadena.An expression control block evaluates an expression and converts it to a string. Esta cadena se inserta en el archivo de salida.This is inserted into the output file.

Los bloques de control de expresiones se delimitan mediante los símbolos <#= ... #>.Expression control blocks are delimited by the symbols <#= ... #>

Por ejemplo, el siguiente bloque de control hace que el archivo de salida contenga "5":For example, the following control block causes the output file to contain "5":

<#= 2 + 3 #>

Observe que el símbolo de apertura tiene tres caracteres "<#=".Notice that the opening symbol has three characters "<#=".

La expresión puede incluir cualquier variable que esté en el ámbito.The expression can include any variable that is in scope. Por ejemplo, este bloque imprime líneas con números:For example, this block prints lines with numbers:

<#@ output extension=".txt" #>
<#
    for(int i = 0; i < 4; i++)
    {
#>
This is hello number <#= i+1 #>: Hello!
<#
    }
#>

Bloques de control de características de claseClass feature control blocks

Un bloque de control de características de clase define propiedades, métodos o cualquier otro código que no se debe incluir en la transformación principal.A class feature control block defines properties, methods, or any other code that should not be included in the main transform. Los bloques de características de clase se utilizan con frecuencia para las funciones del asistente.Class feature blocks are frequently used for helper functions. Normalmente, los bloques de características de clase se colocan en archivos independientes para que se pueden incluyen por más de una plantilla de texto.Typically, class feature blocks are placed in separate files so that they can be included by more than one text template.

Los bloques de control de características de clase se delimitan con los símbolos <#+ ... #>.Class feature control blocks are delimited by the symbols <#+ ... #>

Por ejemplo, el siguiente archivo de plantilla declara y utiliza un método:For example, the following template file declares and uses a method:

<#@ output extension=".txt" #>
Squares:
<#
    for(int i = 0; i < 4; i++)
    {
#>
    The square of <#= i #> is <#= Square(i+1) #>.
<#
    }
#>
That is the end of the list.
<#+   // Start of class feature block
private int Square(int i)
{
    return i*i;
}
#>

Las características de clase se deben colocar al final del archivo donde se escriben.Class features must be placed at the end of the file in which they are written. Sin embargo, puede utilizar <#@include#> para un archivo que incluye una característica de clase, aunque la directiva include vaya seguida de bloques estándar y texto.However, you can <#@include#> a file that contains a class feature, even if the include directive is followed by standard blocks and text.

Para obtener más información acerca de los bloques de control, vea bloques de Control de plantilla de texto.For more information about control blocks, see Text Template Control Blocks.

Los bloques de características de clase pueden contener bloques de textoClass feature blocks can contain text blocks

Puede escribir un método que genere texto.You can write a method that generates text. Por ejemplo:For example:

List of Squares:
<#
   for(int i = 0; i < 4; i++)
   {  WriteSquareLine(i); }
#>
End of list.
<#+   // Class feature block
private void WriteSquareLine(int i)
{
#>
   The square of <#= i #> is <#= i*i #>.
<#+
}
#>

Resulta especialmente útil para colocar un método que genera texto en un archivo independiente que se puede incluir con más de una plantilla.It is particularly useful to place a method that generates text in a separate file that can be included by more than one template.

Utilizar definiciones externasUsing external definitions

EnsambladosAssemblies

Los bloques de código de la plantilla pueden utilizar tipos que se definen en los ensamblados de uso más frecuente de .NET, como System.dll.The code blocks of your template can use types that are defined the most frequently used .NET assemblies such as System.dll. Además, puede hacer referencia a otros ensamblados .NET o a sus propios ensamblados.In addition, you can reference other .NET assemblies or your own assemblies. Puede proporcionar un nombre de ruta de acceso o el nombre seguro de un ensamblado:You can provide a pathname, or the strong name of an assembly:

<#@ assembly name="System.Xml" #>

Debería utilizar nombres de ruta de acceso absolutos o utilizar nombres de macro estándar en el nombre de ruta.You should use absolute path names, or use standard macro names in the path name. Por ejemplo:For example:

<#@ assembly name="$(SolutionDir)library\MyAssembly.dll" #>

La directiva de ensamblado no tiene ningún efecto un plantilla de texto preprocesada.The assembly directive has no effect in a preprocessed text template.

Para obtener más información, consulte directiva de ensamblado T4.For more information, see T4 Assembly Directive.

Espacios de nombresNamespaces

La directiva de importación es igual que la cláusula using en C# o la cláusula imports en Visual Basic.The import directive is the same as the using clause in C# or the imports clause in Visual Basic. Permite hacer referencia a tipos del código sin utilizar un nombre completo:It allows you to refer to types in your code without using a fully qualified name:

<#@ import namespace="System.Xml" #>

Puede utilizar tantas directivas assembly e import como desee.You can use as many assembly and import directives as you want. Debe colocarlas antes de los bloques del texto y de control.You must place them before text and control blocks.

Para obtener más información, consulte directiva de importación T4.For more information, see T4 Import Directive.

Incluir código y textoIncluding code and text

La directiva include inserta texto de otro archivo de plantilla.The include directive inserts text from another template file. Por ejemplo, esta directiva inserta el contenido de test.txt.For example, this directive inserts the content of test.txt.

<#@ include file="c:\test.txt" #>

El contenido incluido se procesa casi como si formase parte de la plantilla de texto que lo incluye.The included content is processed almost as if it were part of the including text template. Sin embargo, puede incluir un archivo que contenga un bloque de características de clase <#+...#> aunque la directiva de inclusión vaya seguida de texto normal y de bloques de control estándar.However, you can include a file that contains a class feature block <#+...#> even if the include directive is followed by ordinary text and standard control blocks.

Para obtener más información, consulte directiva Include de T4.For more information, see T4 Include Directive.

Métodos de utilidadUtility methods

Existen varios métodos como Write() que siempre están disponibles en un bloque de control.There are several methods such as Write() that are always available to you in a control block. Incluyen métodos para ayudarle a aplicar sangría al resultado y para notificar errores.They include methods for helping you indent the output, and for reporting errors.

También puede escribir su propio conjunto de métodos de utilidad.You can also write your own set of utility methods.

Para obtener más información, consulte métodos de utilidad de plantilla de texto.For more information, see Text Template Utility Methods.

Transformar datos y modelosTransforming Data and Models

La aplicación más útil para una plantilla de texto consiste en generar material basado en el contenido de un origen como un modelo, una base de datos o un archivo de datos.The most useful application for a text template is to generate material based on the content of a source such as a model, database, or data file. La plantilla extrae y cambia el formato de los datos.Your template extracts and reformats the data. Una colección de plantillas puede transformar este origen en varios archivos.A collection of templates can transform such a source into multiple files.

Hay varios enfoques para leer el archivo de origen.There are several approaches to reading the source file.

Leer un archivo en la plantilla de texto.Read a file in the text template. Esta es manera más sencilla de incluir los datos en la plantilla:This is simplest way to get data into the template:

<#@ import namespace="System.IO" #>
<# string fileContent = File.ReadAllText(@"C:\myData.txt"); ...

Cargar un archivo como un modelo navegable.Load a file as a navigable model. Un método más eficaz consiste en leer los datos como un modelo, en el que el código de la plantilla de texto puede navegar.A more powerful method is to read the data as a model, which your text template code can navigate. Por ejemplo, puede cargar un archivo XML y navegar en él con expresiones XPath.For example, you can load an XML file and navigate it with XPath expressions. También puede usar xsd.exe para crear un conjunto de clases con las que puede leer los datos XML.You could also use xsd.exe to create a set of classes with which you can read the XML data.

Edite el archivo de modelo en un diagrama o formulario.Edit the model file in a diagram or form. Domain-Specific Language ToolsDomain-Specific Language Tools proporciona herramientas que permiten editar un modelo como un diagrama o formulario de Windows.provides tools that let you edit a model as a diagram or Windows form. Así resulta más fácil analizar el modelo con los usuarios de la aplicación generada.This makes it easier to discuss the model with users of the generated application. Domain-Specific Language ToolsDomain-Specific Language Tools también crea un conjunto de clases fuertemente tipadas que reflejan la estructura del modelo.also creates a set of strongly-typed classes that reflect the structure of the model. Para obtener más información, consulte generar código desde un lenguaje específico de dominio.For more information, see Generating Code from a Domain-Specific Language.

Rutas de acceso de archivo relativas en plantillas en tiempo de diseñoRelative file paths in design-time templates

En un plantilla de texto en tiempo de diseño, si desea hacer referencia a un archivo en una ubicación relativa a la plantilla de texto, use this.Host.ResolvePath().In a design-time text template, if you want to reference a file in a location relative to the text template, use this.Host.ResolvePath(). También debe establecer hostspecific="true" en la directiva template:You must also set hostspecific="true" in the template directive:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ import namespace="System.IO" #>
<#
 // Find a path within the same project as the text template:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of MyFile.txt is:
<#= myFile #>

Además, puede obtener otros servicios que proporciona el host.You can also obtain other services that are provided by the host. Para obtener más información, consulte acceso a Visual Studio u otros Hosts desde una plantilla.For more information, see Accessing Visual Studio or other Hosts from a Template.

Plantillas de texto en tiempo de diseño que se ejecutan en un AppDomain independienteDesign-time Text Templates run in a separate AppDomain

Debe tener en cuenta que un plantilla de texto en tiempo de diseño se ejecuta en un AppDomain que es independiente de la aplicación principal.You should be aware that a design-time text template runs in an AppDomain that is separate from the main application. En la mayoría de los casos esto no es importante, pero se pueden detectar restricciones en ciertos casos complejos.In most cases this is not important, but you might discover restrictions in certain complex cases. Por ejemplo, si desea pasar datos dentro o fuera de la plantilla de un servicio independiente, el servicio debe proporcionar una API serializable.For example, if you want to pass data in or out of the template from a separate service, then the service must provide a serializable API.

(Esto no es verdadero para un plantilla de texto de tiempo de ejecución, que proporciona el código que se compila junto con el resto del código.)(This isn't true of a run-time text template, which provides code that is compiled along with the rest of your code.)

Editar plantillasEditing Templates

Se pueden descargar editores de plantillas del texto especializados de la Galería en línea del Administrador de extensiones.Specialized text template editors can be downloaded from the Extension Manager Online Gallery. En el herramientas menú, haga clic en Administrador de extensiones.On the Tools menu, click Extension Manager. Haga clic en Galería en líneay, a continuación, use la herramienta de búsqueda.Click Online Gallery, and then use the search tool.

TareaTask TemaTopic
Escribir una plantilla.Writing a template. Instrucciones para escribir plantillas de texto T4Guidelines for Writing T4 Text Templates
Genere texto utilizando código de programa.Generate text by using program code. Estructura de la plantilla de textoText Template Structure
Generar archivos en una solución de Visual Studio.Generate files in a Visual Studio solution. Generación de código en tiempo de diseño mediante plantillas de texto T4Design-Time Code Generation by using T4 Text Templates
Ejecute la generación de texto fuera de Visual Studio.Run text generation outside Visual Studio. Generar archivos con la utilidad TextTransformGenerating Files with the TextTransform Utility
Transforme los datos al formato de un lenguaje específico de dominio.Transform your data in the form of a domain-specific language. Generar código a partir de lenguajes específicos de dominioGenerating Code from a Domain-Specific Language
Escriba procesadores de directivas para transformar sus propios orígenes de datos.Write directive processors to transform your own data sources. Personalizar la transformación de texto T4Customizing T4 Text Transformation