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"] [visibility="internal"] [linePragmas="false"] #>

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 Opzioni del compilatore Visual Basic elencate per categoria.

  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.

Se l'attributo debug è true, il file di codice intermedio conterrà informazioni che consentono al debugger per identificare più precisamente la posizione nel modello in cui di interruzione o si è verificata un'eccezione.

Per i modelli della fase di progettazione il file di codice intermedio verrà scritto nella directory % TEMP%.

Per eseguire un modello in fase di progettazione nel debugger, aprire il menu di scelta rapida del modello di testo in Esplora soluzioni e scegliere Debug modello T4.

attributo Hostspecific

• Esempio:

  hostspecific="true"
  

• Valori validi:
  true, false, trueFromBase.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).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 #>

Se si utilizza con gli attributi hostspecific e inherits, specificare il host= " trueFromBase„ nella classe derivata e il host= " true„ nella classe base.Ciò impedisce una doppia definizione di proprietà Host il codice generato.

attributo Language

• Esempio:
  language="VB"

• Valori validi:
  C# (impostazione predefinita)

  VB

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 con modelli di testo T4.

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.

Attenzione
Se si utilizza con gli attributi hostspecific e inherits, specificare hostspecific = " trueFromBase„ nella classe derivata e in host= " true„ nella classe base.Ciò impedisce una doppia definizione di proprietà Host il codice generato.

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.

Attributo di LinePragmas

• Esempio:
  linePragmas="false"

• Valori validi:
  true (impostazione predefinita)

  false

Impostando l'attributo su false rimuove i tag che identificano i numeri di riga nel codice generato.Ciò significa che il compilatore segnala gli errori utilizzando i numeri di riga del codice generato. Questo consente più opzioni di debug, ad esempio è possibile scegliere di eseguire il debug del modello di testo o il codice generato.

Questo attributo può inoltre consentire quando si cercano i nomi file assoluti nei pragma si sta provocando distraendo le unioni sotto il controllo del codice sorgente.

Attributo di visibilità

• Esempio:
  visibility="internal"

• Valori validi:
  public (impostazione predefinita)

  internal

Nel modello di testo runtime, si imposta l'attributo di visibilità della classe generata.Per impostazione predefinita, la classe fa parte dell'API pubblica del codice, ma impostando visibility="internal" è possibile assicurarsi che solo il codice possa utilizzare la classe generatrice.