Directiva de plantilla T4

Normalmente, una plantilla de texto T4 de Visual Studio se inicia con una directiva template, que especifica cómo se debería procesar la plantilla.No debería haber más de una directiva de plantilla en una plantilla de texto y cualquier archivo que incluye.

Para obtener información general sobre cómo escribir plantillas de texto, vea Escribir una plantilla de texto T4.

Usar la directiva de plantilla

<#@ 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.Todos los atributos son opcionales.

compilerOptions (atributo)

• Ejemplo:
  compilerOptions="optimize+"

• Valores válidos:
  Cualquier opción del compilador válida.Para obtener más información, vea Opciones del compilador de C#, por categoría y Opciones del compilador de Visual Basic, por categoría.

  Se omite para plantillas (preprocesadas) en tiempo de ejecución.

Estas opciones se aplican cuando la plantilla se ha convertido en Visual C# o Visual Basic, y el código resultante está compilado.

culture (atributo)

• Ejemplo:
  culture="de-CH"

• Valores válidos:
  "", la referencia cultural, que es la predeterminada.

  Una referencia cultural expresada como una cadena con el formato xx-XX.Por ejemplo, es-ES, ja-JP, de-CH, de-DE.Para obtener más información, vea System.Globalization.CultureInfo.

El atributo culture especifica la referencia cultural para utilizar cuando un bloque de expresión se convierte en texto.

debug (atributo)

• Ejemplo:

  debug="true"
  

• Valores válidos:
  true, false.False es la opción predeterminada.

Si el atributo debug es true, el archivo de código intermedio contendrá información que permite al depurador identificar más exactamente la posición en la plantilla donde una interrupción o se ha producido una excepción.

Para plantillas en tiempo de diseño el archivo de código intermedio se escribirá en el directorio % TEMP%.

Para ejecutar una plantilla en tiempo de diseño en el depurador, abra el menú contextual de la plantilla de texto en el explorador de soluciones, y elija Depurar plantilla T4.

hostspecific (atributo)

• Ejemplo:

  hostspecific="true"
  

• Valores válidos:
  true, false, trueFromBase.False es la opción predeterminada.

Si establece el valor de este atributo en true, una propiedad denominada Host se agrega a la clase generada por la plantilla de texto.La propiedad es una referencia al host del motor de transformación y se declara como Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost.Si ha definido un host personalizado, puede convertirlo al tipo de host personalizado.

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.

Si hostspecific es true y está utilizando Visual Studio, puede convertir this.Host a IServiceProvider para tener acceso a las características de Visual Studio.También puede utilizar Host.ResolvePath(filename) para obtener la ruta de acceso absoluta de un archivo en el proyecto.Por ejemplo:

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<# // 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 el host= " trueFromBase” en la clase derivada y el host= " true” en la clase base.Esto evita una definición doble de la propiedad Host en el código generado.

language (atributo)

• Ejemplo:
  language="VB"

• Valores válidos:
  C# (valor predeterminado)

  VB

El atributo language especifica el lenguaje (Visual Basic o Visual C#) que se va a usar para el código fuente en los bloques de instrucciones y expresiones.El archivo de código intermedio del que se genera el resultado utilizará este lenguaje.Este lenguaje no se relaciona con el lenguaje que genera la plantilla, que puede ser cualquier tipo de texto.

Por ejemplo:

<#@ 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)

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.

Herencia en una plantilla de texto (preprocesada) en tiempo de ejecución

Puede utilizar la herencia entre plantillas de texto en tiempo de ejecución para crear una plantilla básica con algunas variantes derivadas.Las plantillas en tiempo de ejecución son las que tienen la propiedad Herramienta personalizada establecida en 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.Para obtener más información, vea Generación de texto en tiempo de ejecución con plantillas de texto T4.

Si no especifica un atributo inherits, se generan una clase base y una clase derivada en la plantilla de texto.Al especificar un atributo inherits, únicamente se genera la clase derivada.Puede escribir una clase base a mano, pero debe proporcionar los métodos que utiliza la clase derivada.

Por lo general, se especifica otra plantilla preprocesada como la clase base.La plantilla base proporciona bloques de texto comunes, que pueden intercalarse con texto en las plantillas derivadas.Puede utilizar bloques de característica de clase <#+ ... #> para definir métodos que contienen fragmentos de texto.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:

• Plantilla de texto (preprocesada) en tiempo de ejecución 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:

  <#@ 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:

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

• Resultado que se obtiene:

  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.No olvide agregar el proyecto base o ensamblado a las referencias del proyecto derivado.

También puede utilizar una clase normal escrita a mano como la clase base.La clase base debe proporcionar los métodos que usa la clase derivada.

Precaución
Si utiliza los atributos inherits y hostspecific juntos, especifique hostspecific= " trueFromBase” en la clase derivada y el host= " true” en la clase base.Esto evita una definición doble de la propiedad Host en el código generado.

Herencia en una plantilla de texto en tiempo de diseño

Una plantilla de texto en tiempo de diseño es un archivo para el que la propiedad Herramienta personalizada está establecida en TextTemplatingFileGenerator.La plantilla genera un archivo de salida de código o texto, que forma parte de su proyecto de Visual Studio.Para generar el archivo de salida, la plantilla primero se traduce en un archivo de código de programa intermedio, que normalmente no ve.El atributo inherits especifica la clase base para este código intermedio.

Para una plantilla de texto en tiempo de diseño, puede especificar cualquier clase base que se derive de Microsoft.VisualStudio.TextTemplating.TextTransformation.Utilice la directiva <#@assembly#> para cargar el ensamblado o proyecto que contiene la clase base.

Para obtener más información, vea "Inheritance in Text Templates" en el blog de Gareth Jones.

Atributo de LinePragmas

• Ejemplo:
  linePragmas="false"

• Valores válidos:
  true (valor predeterminado)

  false

Al establecer este atributo en false quita las etiquetas que identifican los números de línea en el código generado.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, como puede elegir para depurar la plantilla de texto o el código generado.

Este atributo puede contribuir si se detecta los nombres de archivo absolutos en pragmas está produciendo distrayendo combinaciones bajo control de código fuente.

Atributo de visibilidad

• Ejemplo:
  visibility="internal"

• Valores válidos:
  public (valor predeterminado)

  internal

En una plantilla de texto en tiempo de ejecución, se establece el atributo de la visibilidad de la clase generada.De forma predeterminada, la clase forma parte de la API pública de código, pero estableciendo visibility="internal" puede asegurarse de que sólo el código puede utilizar la clase texto- que genera.