Direttiva template T4

Un modello di testo T4 di Visual Studio di solito inizia con la direttiva template che specifica come deve essere elaborato il modello. Un modello di testo e qualsiasi file in esso incluso non devono contenere più di una direttiva template.

Per cenni preliminari sulla scrittura dei modelli di testo, vedere Scrittura di un modello di testo T4.

Utilizzo della direttiva template

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

La direttiva template dispone di diversi attributi che consentono di specificare vari aspetti della trasformazione. Tutti gli attributi sono facoltativi.

attributo compilerOptions

• Esempio:
  compilerOptions="optimize+"

• Valori validi:
  Qualsiasi opzione del compilatore valida. Per ulteriori informazioni, vedere Opzioni del compilatore C# elencate per categoria e Visual Basic Compiler Options Listed by Category.

  Ignorato per i modelli (pre-elaborati) della fase di esecuzione.

Queste opzioni vengono applicate una volta che il modello è stato convertito in Visual C# o Visual Basic e che è stato compilato il codice risultante.

attributo Culture

• Esempio:
  culture="de-CH"

• Valori validi:
  "", la lingua inglese, ovvero l'impostazione predefinita.

  Impostazioni cultura espresse come una stringa nel formato xx-XX. Ad esempio, it-IT, en-US, ja-JP, de-CH e de-DE. Per ulteriori informazioni, vedere System.Globalization.CultureInfo.

L'attributo Culture specifica le impostazioni cultura da utilizzare quando un blocco di espressione viene convertito in testo.

attributo debug

• Esempio:

  debug="true"
  

• Valori validi:
  true, false. False è l'impostazione predefinita.

L'attributo debug specifica se il debug è abilitato. Se è true, il file di codice intermedio conterrà le informazioni che consentono al debugger di identificare la posizione nel modello in cui si è verificata un'interruzione o un'eccezione. Per i modelli della fase di progettazione il file di codice intermedio verrà scritto nella directory % TEMP%.

Per avviare il debugger in un punto particolare dell'esecuzione di un modello, inserire una chiamata a Launch. Per interrompere l'esecuzione nei punti successivi, inserire una chiamata a Break. Ad esempio:

<#@ template debug="true" language="C#" #>
<#@ output extension=".txt" #>
Output something.
<# 
 // Break here:
 System.Diagnostics.Debugger.Launch();  
#>
Output more.
<#
 // Break here also:
 System.Diagnostics.Debugger.Break();  
#>
Output more.

Per ulteriori informazioni, vedere Procedura dettagliata: debug di un modello di testo.

attributo Hostspecific

• Esempio:

  hostspecific="true"
  

• Valori validi:
  true, false. False è l'impostazione predefinita.

Se si imposta il valore di questo attributo su true, viene aggiunta una proprietà denominata Host alla classe generata dal modello di testo. La proprietà è un riferimento all'host del motore di trasformazione e viene dichiarata come Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost. Se è stato definito un host personalizzato, è possibile eseguirne il cast sul tipo di host personalizzato.

Poiché il tipo di questa proprietà dipende dal tipo di host, è utile solo se si scrive un modello di testo che funziona solo con un host specifico.

Quando hostspecific è true e si utilizza Visual Studio, è possibile eseguire il cast di this.Host a IServiceProvider per accedere alle funzionalità di Visual Studio. È inoltre possibile utilizzare Host.ResolvePath(filename) per ottenere il percorso assoluto di un file nel progetto. Ad esempio:

<#@ 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).GetService(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 #>

attributo Language

• Esempio:
  language="VB"

• Valori validi:
  C# (impostazione predefinita)

  VB

  I valori VBv3.5 e C#v3.5 sono obsoleti in questa versione, ma verranno interpretati come VB e C#.

L'attributo di linguaggio specifica il linguaggio (Visual Basic o Visual C#) da utilizzare per il codice sorgente nei blocchi di istruzioni e di espressioni. Il file di codice intermedio dal quale viene generato l'output utilizzerà questo linguaggio. Questo linguaggio non è correlato al linguaggio generato dal modello, che può essere qualsiasi tipo di testo.

Ad esempio:

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

attributo Inherits

È possibile specificare che il codice del programma del modello può ereditare da un'altra classe che può essere generata anche da un modello di testo.

Ereditarietà in un modello di testo (pre-elaborato) della fase di esecuzione

È possibile utilizzare l'ereditarietà tra i modelli di testo della fase di esecuzione per creare un modello di base che disponga di molte varianti derivate. I modelli della fase di esecuzione sono quelli che dispongono della proprietà Strumento personalizzato impostata su TextTemplatingFilePreprocessor. Un modello della fase di esecuzione genera codice che è possibile chiamare nell'applicazione per creare il testo definito nel modello. Per ulteriori informazioni, vedere Generazione di testo in fase di esecuzione tramite modelli di testo T4 pre-elaborati.

Se non si specifica un attributo inherits, una classe di base e una classe derivata vengono generate dal modello di testo. Quando si specifica l'attributo inherits, viene generata solo la classe derivata. È possibile scrivere manualmente una classe di base, ma deve fornire i metodi utilizzati dalla classe derivata.

Più in generale è possibile specificare un altro modello pre-elaborato come classe di base. Il modello di base fornisce blocchi di testo comuni che possono essere interfogliati con il testo dei modelli derivati. È possibile utilizzare i blocchi della funzionalità di classe <#+ ... #> per definire i metodi che contengono frammenti di testo. Ad esempio, è possibile inserire il framework del testo di output nel modello di base, fornendo i metodi virtuali che possono essere sottoposti a override nei modelli derivati:

• Modello di testo (pre-elaborato) della fase di esecuzione 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() { }
  #>
  

• Modello di testo (pre-elaborato) della fase di esecuzione 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
  <#+
  }
  #>
  

• Codice dell'applicazione per richiamare DerivedTemplate1:

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

• Output risultante:

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

È possibile compilare le classi di base e derivate in progetti diversi. Ricordare di aggiungere il progetto o l'assembly di base ai riferimenti del progetto derivato.

È inoltre possibile utilizzare una classe comune scritta manualmente come classe di base. La classe di base deve fornire i metodi utilizzati dalla classe derivata.

Ereditarietà in un modello di testo della fase di progettazione

Un modello di testo della fase di progettazione è un file per cui Strumento personalizzato viene impostato su TextTemplatingFileGenerator. Il modello genera un file di output di codice o testo che fa parte del progetto Visual Studio. Per generare il file di output, il modello viene prima tradotto in un file del codice del programma intermedio che non viene in genere visualizzato. L'attributo inherits specifica la classe di base per questo codice intermedio.

Per un modello di testo della fase di progettazione, è possibile specificare qualsiasi classe di base derivata da Microsoft.VisualStudio.TextTemplating.TextTransformation. Utilizzare la direttiva <#@assembly#> per caricare l'assembly o il progetto contenente la classe di base.

Per ulteriori informazioni, vedere "Ereditarietà nei modelli di testo" nel blog di Gareth Jones.

Cronologia delle modifiche