Directiva de plantilla T4T4 Template Directive

Una plantilla de texto T4 de Visual Studio normalmente comienza con un template directiva, que especifica cómo se debe procesar la plantilla.A Visual Studio T4 text template usually starts with a template directive, which specifies how the template should be processed. No debería haber más de una directiva de plantilla en una plantilla de texto y cualquier archivo que incluye.There should be no more than one template directive in a text template and any files that it includes.

Para obtener una descripción general de la escritura de plantillas de texto, consulte escribir una plantilla de texto T4.For a general overview of writing text templates, see Writing a T4 Text Template.

Usar la directiva de plantillaUsing the Template Directive

<#@ template [language="VB"] [compilerOptions="options"] [culture="code"] [debug="true"] [hostspecific="true"] [inherits="templateBaseClass"] [visibility="internal"] [linePragmas="false"] #>

La directiva template tiene varios atributos que permiten especificar distintos aspectos de la transformación.The template directive has several attributes that allow you to specify different aspects of the transformation. Todos los atributos son opcionales.All the attributes are optional.

compilerOptions (atributo)compilerOptions attribute

Ejemplo: compilerOptions="optimize+"Example: compilerOptions="optimize+"

Los valores válidos: cualquier opción del compilador válida.Valid values: Any valid compiler options.

Se omite para plantillas (preprocesadas) en tiempo de ejecución.Ignored for run-time (preprocessed) templates.

Estas opciones se aplican cuando la plantilla se ha convertido en Visual C#Visual C# o Visual BasicVisual Basic, y el código resultante está compilado.These options are applied when the template has been converted into Visual C#Visual C# or Visual BasicVisual Basic, and the resulting code is compiled.

culture (atributo)culture attribute

Ejemplo: culture="de-CH"Example: culture="de-CH"

Los valores válidos: "", la referencia cultural invariable, que es el valor predeterminado.Valid values: "", the invariant culture, which is the default.

Una referencia cultural expresada como una cadena con el formato xx-XX.A culture expressed as a string in the form xx-XX. Por ejemplo, es-ES, ja-JP, de-CH, de-DE.For example, en-US, ja-JP, de-CH, de-DE. Para obtener más información, consulta System.Globalization.CultureInfo.For more information, see System.Globalization.CultureInfo.

El atributo culture especifica la referencia cultural para utilizar cuando un bloque de expresión se convierte en texto.The culture attribute specifies the culture to use when an expression block is converted to text.

debug (atributo)debug attribute

Ejemplo:Example:

debug="true"

Los valores válidos: true, false.Valid values: true, false. False es la opción predeterminada.False is the default.

Si el atributo debug es true, el archivo de código intermedio contiene información que permite al depurador identificar con más precisión la posición de la plantilla donde se produjo una interrupción o una excepción.If the debug attribute is true, the intermediate code file will contain information that enables the debugger to identify more accurately the position in your template where a break or exception occurred.

Para plantillas en tiempo de diseño se escribirá el archivo de código intermedio para su % TEMP % directory.For design-time templates the intermediate code file will be written to your %TEMP% directory.

Para ejecutar una plantilla en tiempo de diseño en el depurador, guarde la plantilla de texto, a continuación, abra el menú contextual de la plantilla de texto en el Explorador de soluciones y elija depurar plantilla T4.To run a design-time template in the debugger, save the text template, then open the shortcut menu of the text template in Solution Explorer, and choose Debug T4 Template.

hostspecific (atributo)hostspecific attribute

Ejemplo:Example:

hostspecific="true"

Los valores válidos: true, false, trueFromBase.Valid values: true, false, trueFromBase. False es la opción predeterminada.False is the default.

Si establece el valor de este atributo en true, una propiedad denominada Host se agrega a la clase generada por la plantilla de texto.If you set the value of this attribute to true, a property named Host is added to the class generated by your text template. La propiedad es una referencia al host del motor de transformación y se declara como ITextTemplatingEngineHost.The property is a reference to the host of the transformation engine, and is declared as ITextTemplatingEngineHost. Si ha definido un host personalizado, puede convertirlo al tipo de host personalizado.If you have defined a custom host, you can cast it to the custom host type.

Dado que el tipo de esta propiedad depende del tipo de host, solamente es útil si está escribiendo una plantilla de texto que únicamente trabaja con un host concreto.Because the type of this property depends on the type of host, it is only useful if you are writing a text template that works only with a specific host. Es aplicable a plantillas en tiempo de diseño, pero no plantillas en tiempo de ejecución.It's applicable to design-time templates, but not run-time templates.

Cuando hostspecific es true y que está usando Visual Studio, puede convertir this.Host a IServiceProvider para tener acceso a características de Visual Studio.When hostspecific is true and you are using Visual Studio, you can cast this.Host to IServiceProvider to access Visual Studio features. También puede utilizar Host.ResolvePath(filename) para obtener la ruta de acceso absoluta de un archivo en el proyecto.You can also use Host.ResolvePath(filename) to obtain the absolute path of a file in the project. Por ejemplo:For example:

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<#@ import namespace="Microsoft.VisualStudio.TextTemplating" #>
<# // Get the Visual Studio API as a service:
 DTE dte = ((IServiceProvider)this.Host).GetCOMService(typeof(DTE)) as DTE;
#>
Number of projects in this solution: <#=  dte.Solution.Projects.Count #>

<#
 // Find a path within the current project:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of myFile is:
<#= myFile #>

Si utiliza los atributos inherits y hostspecific juntos, especifique host="trueFromBase" en la clase derivada y host=" true" en la clase base.If you use the inherits and hostspecific attributes together, specify host="trueFromBase" in the derived class and host="true" in the base class. Esto evita una definición doble de la propiedad Host en el código generado.This avoids a double definition of the Host property in the generated code.

language (atributo)language attribute

Ejemplo: language="VB"Example: language="VB"

Los valores válidos: C# (valor predeterminado)Valid values: C# (default)

VB

El atributo language especifica el idioma (Visual BasicVisual Basic o Visual C#Visual C#) que se utilizará para el código fuente en los bloques de instrucciones y expresiones.The language attribute specifies the language (Visual BasicVisual Basic or Visual C#Visual C#) to use for the source code in statement and expression blocks. El archivo de código intermedio del que se genera el resultado utilizará este lenguaje.The intermediate code file from which the output is generated will use this language. Este lenguaje no se relaciona con el lenguaje que genera la plantilla, que puede ser cualquier tipo de texto.This language is not related to the language that your template generates, which can be any kind of text.

Por ejemplo:For example:

<#@ template language="VB" #>
<#@ output extension=".txt" #>
Squares of numbers:
<#
  Dim number As Integer
  For number = 1 To 4
#>
  Square of <#= number #> is <#= number * number #>
<#
  Next number
#>

inherits (atributo)inherits attribute

Puede especificar que el código de programa de su plantilla puede heredar de otra clase, que también se puede generar a partir de una plantilla de texto.You can specify that the program code of your template can inherit from another class, which can also be generated from a text template.

Herencia en una plantilla de texto (preprocesada) en tiempo de ejecuciónInheritance in a run-time (preprocessed) text template

Puede utilizar la herencia entre plantillas de texto en tiempo de ejecución para crear una plantilla básica con algunas variantes derivadas.You can use inheritance between run-time text templates to create a basic template that has several derived variants. Plantillas en tiempo de ejecución son aquellos que tienen el Custom Tool propiedad establecida en TextTemplatingFilePreprocessor.Run-time templates are those that have the Custom Tool property set to TextTemplatingFilePreprocessor. Una plantilla en tiempo de ejecución genera el código al que puede llamar en la aplicación para crear el texto definido en la plantilla.A run-time template generates code that you can call in your application to create the text defined in the template. Para obtener más información, consulte generación de texto en tiempo de ejecución con plantillas de texto T4.For more information, see Run-Time Text Generation with T4 Text Templates.

Si no especifica un atributo inherits, se generan una clase base y una clase derivada en la plantilla de texto.If you do not specify an inherits attribute, a base class and a derived class are generated from your text template. Al especificar un atributo inherits, únicamente se genera la clase derivada.When you specify an inherits attribute, only the derived class is generated. Puede escribir una clase base a mano, pero debe proporcionar los métodos que utiliza la clase derivada.You can write a base class by hand, but it must provide the methods that are used by the derived class.

Por lo general, se especifica otra plantilla preprocesada como la clase base.More typically, you specify another preprocessed template as the base class. La plantilla base proporciona bloques de texto comunes, que pueden intercalarse con texto en las plantillas derivadas.The base template provides common blocks of text, which can be interleaved with text from the derived templates. Puede utilizar bloques de característica de clase <#+ ... #> para definir métodos que contienen fragmentos de texto.You can use class feature blocks <#+ ... #> to define methods that contain text fragments. Por ejemplo, puede colocar el marco del texto de salida en la plantilla base, proporcionando métodos virtuales que se pueden invalidar en plantillas derivadas:For example, you can place the framework of the output text in the base template, providing virtual methods that can be overridden in derived templates:

Plantilla de texto (preprocesada) en tiempo de ejecución BaseTemplate.tt:Run-time (preprocessed) text template BaseTemplate.tt:

This is the common header.
<#
 SpecificFragment1();
#>
A common central text.
<#
 SpecificFragment2();
#>
This is the common footer.
<#+
 // Declare abstract methods
 protected virtual void SpecificFragment1() { }
 protected virtual void SpecificFragment2() { }
#>

Plantilla de texto (preprocesada) en tiempo de ejecución DerivedTemplate1.tt:Run-time (preprocessed) text template DerivedTemplate1.tt:

<#@ template language="C#" inherits="BaseTemplate" #>
<#
 // Run the base template:
 base.TransformText();
#>
<#+
// Provide fragments specific to this derived template:
protected override void SpecificFragment1()
{
#>
  Fragment 1 for DerivedTemplate1
<#+
}
protected override void SpecificFragment2()
{
#>
  Fragment 2 for DerivedTemplate1
<#+
}
#>

Código de aplicación para invocar a DerivedTemplate1:Application code to invoke DerivedTemplate1:

Console.WriteLine(new DerivedTemplate().TransformText());

Resultado que se obtiene:Resulting output:

This is the common header.
  Fragment 1 for DerivedTemplate1
A common central text.
  Fragment 2 for DerivedTemplate1
This is the common footer.

Puede compilar las clases derivadas y base en proyectos diferentes.You can build the base and derived classes in different projects. No olvide agregar el proyecto base o ensamblado a las referencias del proyecto derivado.Remember to add the base project or assembly to the derived project's references.

También puede utilizar una clase normal escrita a mano como la clase base.You can also use an ordinary hand-written class as the base class. La clase base debe proporcionar los métodos que usa la clase derivada.The base class must provide the methods used by the derived class.

Warning

Si utiliza los atributos inherits y hostspecific juntos, especifique hostspecific="trueFromBase" en la clase derivada y host=" true" en la clase base.If you use the inherits and hostspecific attributes together, specify hostspecific="trueFromBase" in the derived class and host="true" in the base class. Esto evita una definición doble de la propiedad Host en el código generado.This avoids a double definition of the Host property in the generated code.

Herencia en una plantilla de texto en tiempo de diseñoInheritance in a design-time text template

Una plantilla de texto en tiempo de diseño es un archivo para el que Custom Tool está establecido en TextTemplatingFileGenerator.A design-time text template is a file for which Custom Tool is set to TextTemplatingFileGenerator. La plantilla genera un archivo de salida de código o texto, que forma parte del proyecto de Visual Studio.The template generates an output file of code or text, which forms part of your Visual Studio project. Para generar el archivo de salida, la plantilla primero se traduce en un archivo de código de programa intermedio, que normalmente no ve.To generate the output file, the template is first translated into an intermediate program code file, which you do not usually see. El atributo inherits especifica la clase base para este código intermedio.The inherits attribute specifies the base class for this intermediate code.

Para una plantilla de texto en tiempo de diseño, puede especificar cualquier clase base que se derive de Microsoft.VisualStudio.TextTemplating.TextTransformation.For a design-time text template, you can specify any base class that is derived from Microsoft.VisualStudio.TextTemplating.TextTransformation. Utilice la directiva <#@assembly#> para cargar el ensamblado o proyecto que contiene la clase base.Use the <#@assembly#> directive to load the assembly or project that contains the base class.

Para obtener más información, consulte "Herencia en plantillas de texto" en el Blog de Gareth Jones.For more information, see "Inheritance in Text Templates" in Gareth Jones' Blog.

Atributo LinePragmasLinePragmas attribute

Ejemplo: linePragmas="false"Example: linePragmas="false"

Los valores válidos: true (valor predeterminado)Valid values: true (default)

false

Al establecer este atributo en false se quitan las etiquetas que identifican los números de línea en el código generado.Setting this attribute to false removes the tags that identify your line numbers within the generated code. Esto significa que el compilador notificará cualquier error utilizando los números de línea del código generado. Esto proporciona más opciones de depuración, ya que puede elegir entre depurar la plantilla de texto o el código generado.This means that the compiler will report any errors by using line numbers of the generated code.This gives you more debugging options, as you can choose to debug either the text template or the generated code.

Este atributo también puede ayudar si se detecta que los nombres de archivo absolutas en las directivas pragma están produciendo combinaciones confusas bajo control de código fuente.This attribute can also help if you're finding the absolute filenames in pragmas are causing distracting merges under source code control.

Atributo visibilityVisibility attribute

Ejemplo: visibility="internal"Example: visibility="internal"

Los valores válidos: public (valor predeterminado)Valid values: public (default)

internal

En una plantilla de texto en tiempo de ejecución, establece el atributo de visibilidad de la clase generada.In a runtime text template, this sets the visibility attribute of the generated class. De forma predeterminada, la clase forma parte de la API pública del código, pero si se establece visibility="internal", puede asegurarse de que solo el código pueda utilizar la clase de generación de texto.By default, the class is part of the public API of your code, but by setting visibility="internal" you can make sure that only your code can use the text-generating class.