Generazione di codice in fase di progettazione tramite modelli di testo T4

Articolo
02/19/2013

I modelli di testo T4 della fase di progettazione consentono di generare codice programma e altri file nel progetto di Visual Studio.In genere, i modelli vengono scritti in modo che varino il codice da essi generato in base ai dati di un modello.Un modello è un file o un database contenente informazioni chiave sui requisiti dell'applicazione.

Ad esempio, un modello può definire un flusso di lavoro come tabella o diagramma.Dal modello è possibile generare il software per l'esecuzione del flusso di lavoro.Quando le esigenze degli utenti cambiano, è facile discutere con essi il nuovo flusso di lavoro.La rigenerazione del codice dal flusso di lavoro è più affidabile rispetto all'aggiornamento manuale del codice.

[!NOTA]

Un modello è un'origine dati che descrive un particolare aspetto di un'applicazione.Può avere un formato qualsiasi, in qualsiasi tipo di file o database.Non deve necessariamente avere un formato particolare, come un modello UML o un modello di linguaggio specifico di dominio.I modelli tipici hanno il formato di tabelle o file XML.

Probabilmente si ha già familiarità con la generazione di codice.Quando si definiscono delle risorse in un file .resx nella soluzione Visual Studio, viene automaticamente generato un set di classi e di metodi.Il file di risorse rende molto più semplice e sicuro modificare le risorse di quanto lo sarebbe se si dovessero modificare le classi e i metodi.Con i modelli di testo, è possibile generare codice nello stesso modo da un'origine della propria progettazione.

Un modello di testo contiene una combinazione del testo che si desidera generare e del codice programma che genera parti variabili del testo.Il codice programma consente di ripetere o omettere parti del testo generato in modo condizionale.Il testo generato può essere codice programma che farà parte dell'applicazione.

Creazione di un modello di testo T4 della fase di progettazione

Per creare un modello T4 della fase di progettazione in Visual Studio

Creare un progetto Visual Studio oppure aprirne uno esistente.

Ad esempio, nel menu Il file, scegliere Nuova, Project.
Aggiungere un file modello di testo al progetto e denominarla con estensione tt.

A tale scopo, in Esplora soluzioni, scegliere dal menu di scelta rapida del progetto, scegliere Aggiungi, Nuovo elemento.Nella finestra di dialogo Modello di testo selezionato Aggiungi nuovo elemento nel riquadro centrale.

Si noti che la proprietà Strumento personalizzato del file è TextTemplatingFileGenerator.
Aprire il file.Nel file saranno già presenti le direttive seguenti:
```
<#@ template hostspecific="false" language="C#" #>
<#@ output extension=".txt" #>
```
Se è stato aggiunto il modello a un progetto Visual Basic, l'attributo di linguaggio sarà VB.
Aggiungere del testo alla fine del file.Ad esempio:
```
Hello, world!
```
Salvare il file.

È possibile che venga visualizzata una finestra di messaggio Avviso di sicurezza nella quale viene chiesto di confermare che si desidera eseguire il modello.Fare clic su OK.
In Esplora soluzioni, espandere il nodo del file modello e comprende un file con estensione .txt.Il file contiene il testo generato dal modello.

[!NOTA]

Se il progetto è un progetto di Visual Basic., è necessario fare clic Mostra tutti i file per visualizzare il file di output.

Rigenerazione del codice

Un modello sarà eseguito, generando il file sussidiario, in uno dei casi seguenti:

Modificare lo stato attivo della modifica e quindi del modello a una finestra diversa Visual Studio.
Salvare il modello.
Scegliere Trasforma tutti i modelli nel menu Compilazione.Tutti i modelli nella soluzione Visual Studio verranno trasformati.
In Esplora soluzioni, scegliere dal menu di scelta rapida del file, scegliere Esegui strumento personalizzato.Utilizzare questo metodo per trasformare un sottoinsieme scelto dei modelli.

È inoltre possibile configurare un progetto Visual Studio in modo che i modelli vengano eseguiti dopo che i file di dati letti dai modelli sono stati modificati.Per ulteriori informazioni, vedere Rigenerazione automatica del codice.

Generazione di testo variabile

I modelli di testo consentono di utilizzare codice programma per variare il contenuto del file generato.

Per generare del testo utilizzando codice programma

Modificare il contenuto del file .tt:

<#@ template hostspecific="false" language="C#" #>
<#@ output extension=".txt" #>
<#int top = 10;

for (int i = 0; i<=top; i++) { #>
The square of <#= i #> is <#= i*i #>
<# } #>

<#@ template hostspecific="false" language="VB" #>
<#@ output extension=".txt" #>
<#Dim top As Integer = 10

For i As Integer = 0 To top
#>
    The square of <#= i #> is <#= i*i #>
<#
Next
#>

Salvare il file .tt e controllare nuovamente il file .txt generato.In esso sono elencati i quadrati dei numeri da 0 a 9.

Si noti che le istruzioni sono racchiuse tra <#...#> e le espressioni singole tra <#=...#>.Per ulteriori informazioni, vedere Scrittura di un modello di testo T4.

Se si scrive il codice generatore in Visual Basic, la direttiva template deve contenere language="VB"."C#" è l'impostazione predefinita.

Eseguire il debug di un modello di testo T4 della fase di progettazione

Per eseguire il debug di un modello di testo:

Inserire debug="true" nella direttiva template.Ad esempio:

<#@ template debug="true" hostspecific="false" language="C#" #>
Impostare i punti di interruzione nel modello, allo stesso modo in cui il codice comune.
Scegliere Debug modello T4 dal menu di scelta rapida del file modello di testo in Esplora soluzioni.

Il modello verrà eseguito e verrà interrotta in corrispondenza di punti di interruzione.È possibile esaminare le variabili e il passaggio al codice come sempre.

Suggerimento
debug="true" esegue il mapping di codice generato con maggiore precisione al modello di testo, inserendo più direttive di numerazione delle righe del codice generato.Se viene omesso, i punti di interruzione potrebbero interrompere l'esecuzione in e presenta lo stato. Ma è possibile lasciare la clausola nella direttiva del modello anche quando non si esegue il debug.Ciò comporta solo un calo molto piccolo delle prestazioni.

debug="true" esegue il mapping di codice generato con maggiore precisione al modello di testo, inserendo più direttive di numerazione delle righe del codice generato.Se viene omesso, i punti di interruzione potrebbero interrompere l'esecuzione in e presenta lo stato.

Ma è possibile lasciare la clausola nella direttiva del modello anche quando non si esegue il debug.Ciò comporta solo un calo molto piccolo delle prestazioni.

Generazione di codice o di risorse per la soluzione

È possibile generare file di programma che variano, a seconda di un modello.Un modello è un input quale un database, un file di configurazione, un modello UML o DSL o un'altra origine.In genere si generano diversi file di programma dallo stesso modello.A tal fine, si crea un file modello per ogni file di programma generato e si fa in modo che tutti i modelli leggano lo stesso modello.

Per generare codice programma o risorse

Modificare la direttiva di output per generare un file del tipo adatto, ad esempio .cs, .vb, .resx o .xml.

Inserire codice che genererà il codice richiesto della soluzione.Ad esempio, se si desidera generare tre dichiarazioni di campo Integer in una classe:

                  <#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".cs" #>
<# var properties = new string [] {"P1", "P2", "P3"}; #>
class MyGeneratedClass {
<# 
  foreach (string propertyName in properties)
  { #>
  private int <#= propertyName #> = 0;
<# } #>
}

<#@ template debug="false" hostspecific="false" language="VB" #>
<#@ output extension=".cs" #>
<# Dim properties = {"P1", "P2", "P3"} #>
class MyGeneratedClass {
<# 
   For Each propertyName As String In properties
#>
  private int <#= propertyName #> = 0;
<#
   Next
#>
}

Salvare il file ed esaminare il file generato che contiene ora il codice seguente:

class MyGeneratedClass {
  private int P1 = 0; 
  private int P2 = 0;
  private int P3 = 0;
}

Generazione di codice e testo generato

Quando si genera codice programma, è molto importante evitare di confondere il codice generato che viene eseguito nel modello e il risultante codice generato che diventa parte della soluzione.I due linguaggi non devono necessariamente essere uguali.

Nell'esempio precedente sono indicate due versioni.In una versione, il codice di generazione è in C#.Nell'altra versione, il codice di generazione è Visual Basic.Il testo generato da entrambi è tuttavia identico (una classe C#).

Allo stesso modo è possibile utilizzare un modello Visual C# per generare codice in qualsiasi linguaggio.Il testo generato non deve necessariamente essere in un linguaggio particolare o codice di programmazione.

Struttura di modelli di testo

È consigliabile separare il codice del modello in due parti:

Una parte relativa alla configurazione o alla raccolta dei dati, che imposta i valori nelle variabili ma non contiene blocchi di testo.Nell'esempio precedente questa parte è costituita dall'inizializzazione di properties.

Talvolta questa parte è denominata sezione "modello", in quanto viene costruito un modello nell'archivio e in genere viene letto un file modello.
La parte relativa alla generazione di testo (foreach(...){...} nell'esempio) che utilizza i valori delle variabili.

Non si tratta di una separazione necessaria, ma è un metodo che semplifica la lettura del modello riducendo la complessità della parte che include testo.

Lettura di file o di altre origini

Per accedere a un file modello o di database, nel codice del modello possono essere utilizzati assembly come System.XML.Per accedere a questi assembly, è necessario inserire direttive del seguente tipo:

<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#@ import namespace="System.IO" #>

La direttiva assembly rende disponibile l'assembly specificato al codice del modello, nello stesso modo della sezione Riferimenti di un progetto Visual Studio.Non è necessario includere un riferimento a System.dll, a cui viene fatto riferimento automaticamente.La direttiva import consente di utilizzare dei tipi senza utilizzarne i nomi completi, nello stesso modo della direttiva using in un file programma comune.

Ad esempio, dopo avere importato System.IO, è possibile scrivere:

          <# var properties = File.ReadLines("C:\\propertyList.txt");#>
...
<# foreach (string propertyName in properties) { #>
...

<# For Each propertyName As String In 
             File.ReadLines("C:\\propertyList.txt")
#>

Apertura di un file con un nome del percorso relativo

Per caricare un file da un percorso relativo nel modello di testo, è possibile utilizzare this.Host.ResolvePath().Per utilizzare this.Host, è necessario impostare hostspecific="true" in template:

<#@ template debug="false" hostspecific="true" language="C#" #>

Sarà quindi possibile scrivere, ad esempio:

<# string fileName = this.Host.ResolvePath("filename.txt");
  string [] properties = File.ReadLines(filename);
#>
...
<#  foreach (string propertyName in properties { #>
...

<# Dim fileName = Me.Host.ResolvePath("propertyList.txt")
   Dim properties = File.ReadLines(filename)
#>
...
<#   For Each propertyName As String In properties
...
#>

È inoltre possibile utilizzare this.Host.TemplateFileche identifica il nome del file modello corrente.

Il tipo di this.Host (in VB, Me.Host) è Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost.

Acquisizione di dati da Visual Studio

Per utilizzare i servizi forniti in Visual Studio, impostare l'attributo hostSpecific e caricare l'assembly EnvDTE.È quindi possibile utilizzare IServiceProvider.GetCOMService() per accedere all'oggetto DTE e altri servizi.Ad esempio:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#
  IServiceProvider serviceProvider = (IServiceProvider)this.Host;
  EnvDTE.DTE dte = (EnvDTE.DTE) serviceProvider.GetCOMService(typeof(EnvDTE.DTE));
#>

Number of projects in this VS solution:  <#= dte.Solution.Projects.Count #>

Suggerimento
Un modello di testo viene eseguito nel dominio di applicazione e i servizi si accede desidera effettuare il marshalling.In questa condizione, GetCOMService() è più affidabile di GetService().

Rigenerazione automatica del codice

In genere, molti file in una soluzione Visual Studio vengono generati con un unico modello di input.Ogni file viene generato dal proprio modello, ma tutti i modelli fanno riferimento allo stesso modello.

Se si cambia il modello di origine, è necessario eseguire nuovamente tutti i modelli nella soluzione.Per eseguire questa operazione manualmente, scegliere Trasforma tutti i modelli il menu Compilazione.

Se è stato installato l'SDK di visualizzazione e modellazione di Visual Studio, è possibile fare in modo che tutti i modelli siano trasformati automaticamente ogni volta che si esegue una compilazione.A questo scopo, modificare il file di progetto (.csproj o .vbproj) in un editor di testo e aggiungere le righe seguenti verso la fine del file, dopo qualsiasi altra istruzione <import>:

<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v11.0\TextTemplating\Microsoft.TextTemplating.targets" />
<PropertyGroup>
   <TransformOnBuild>true</TransformOnBuild>
   <!-- Other properties can be inserted here -->
</PropertyGroup>

Per ulteriori informazioni, vedere Generazione di codice in un processo di compilazione.

Segnalazione degli errori

Per inserire messaggi di avviso e di errore nella finestra di errore di Visual Studio, è possibile utilizzare questi metodi:

Error("An error message");
Warning("A warning message");

Conversione di un file esistente in un modello

Una funzionalità utile dei modelli è che assomigliano molto ai file che generano, con del codice programma inserito.Questa caratteristica suggerisce un metodo utile di creazione di un modello.Creare innanzitutto un normale file come prototipo, quale un file Visual C#, quindi inserire gradualmente codice generatore che varia il file risultante.

Per convertire un file esistente in un modello della fase di progettazione

Nel progetto di Visual Studio, aggiungere un file del tipo che si desidera generare, quale un file .cs, .vb, o .resx.
Testare il nuovo file per assicurarsi che funzioni.
In Esplora soluzioni impostare l'estensione del file su .tt.
Verificare le proprietà seguenti del file .tt:

Strumento personalizzato =

TextTemplatingFileGenerator

Operazione di compilazione =

Nessuno
Inserire le seguenti righe all'inizio del file:
```
<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".cs" #>
```
Se si desidera scrivere il codice generatore del modello in Visual Basic, impostare l'attributo language su "VB" anziché su "C#".

Impostare l'attributo extension sull'estensione di file per il tipo di file che si desidera generare, ad esempio .cs, .resx o .xml.
Salvare il file.

Verrà creato un file sussidiario con l'estensione specificata.Le relative proprietà saranno corrette per il tipo di file.Ad esempio, la proprietà Operazione di compilazione di un file .cs sarebbe Compila.

Verificare che il file generato contenga lo stesso contenuto del file originale.
Identificare una parte del file che si desidera variare.Ad esempio, una parte visualizzata solo in determinate condizioni o una parte che viene ripetuta o dove i valori specifici variano.Inserire il codice generatore.Salvare il file e verificare che il file sussidiario venga generato correttamente.Ripetere questo passaggio.

Linee guida per la generazione di codice

Vedere Linee guida per la scrittura di modelli di testo T4.

Passaggi successivi

Passaggio successivo	Argomento
Scrivere ed eseguire il debug di un modello di testo più avanzato, con codice che utilizza funzioni ausiliarie, file inclusi e dati persistenti.	Scrittura di un modello di testo T4
Generare in fase di esecuzione documenti dai modelli.	Generazione di testo in fase di esecuzione con modelli di testo T4
Eseguire generazione di testo fuori da Visual Studio.	Generazione di file con l'utilità TextTransform
Trasformare i dati nel formato di un linguaggio specifico di dominio.	Generazione di codice da un linguaggio specifico di dominio
Scrivere processori di direttive per trasformare le proprie origini dati.	Personalizzazione della trasformazione del testo T4

Vedere anche

Concetti

Linee guida per la scrittura di modelli di testo T4

Condividi tramite