Condividi tramite

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

  • Articolo

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

  1. Creare un progetto Visual Studio oppure aprirne uno esistente.

    Ad esempio, nel menu File selezionare Nuovo e fare clic su Progetto.

  2. Aggiungere un file modello di testo al progetto e denominarlo Nuovomodello.tt.

    A tale scopo, in Esplora soluzioni, fare clic con il pulsante destro del mouse sul progetto e selezionare Aggiungi, quindi fare clic su Nuovo elemento. Nella finestra di dialogo Aggiungi nuovo elemento selezionare Modello di testo nel riquadro Modelli. Assegnare al file il nome Nuovomodello.tt.

    Si noti che la proprietà Strumento personalizzato del file è TextTemplatingFileGenerator.

  3. Aprire il file. Nel file saranno già presenti le direttive seguenti:

    <#@ template debug="false" hostspecific="false" language="C#" #>
<#@ output extension=".txt" #>

    Se è stato aggiunto il modello a un progetto Visual Basic, l'attributo di linguaggio sarà VB.

  4. Aggiungere del testo alla fine del file. Ad esempio:

    Hello, world!

  5. 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.

  6. In Esplora soluzioni espandere il nodo Nuovomodello.tt nel quale sarà presente un file denominato Nuovomodello.txt. In questo file è contenuto il testo che è stato immesso.

    Nota

    Se il progetto è un progetto Visual Basic, è necessario fare clic su Mostra tutti i file per vedere il file di output Nuovomodello.txt.

Rigenerazione del codice

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

  • Modificare un modello, quindi spostare lo stato attivo su un'altra finestra Visual Studio.

  • Salvare il modello.

  • Fare clic su Trasforma tutti i modelli sulla barra degli strumenti Esplora soluzioni. Tutti i modelli nella soluzione Visual Studio verranno trasformati.

  • Fare clic con il pulsante destro del mouse su uno o più file in Esplora soluzioni, quindi fare clic su Esegui strumento personalizzato. Utilizzare questo metodo per trasformare un set selezionato di 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

  1. Modificare il contenuto del file .tt:

    <#@ template debug="false" 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 debug="false" 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
#>

  2. 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.

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

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

  2. 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
#>
}

  3. 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. Ad esempio:

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

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

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, fare clic su Trasforma tutti i modelli sulla barra degli strumenti di Esplora soluzioni.

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\TextTemplating\v10.0\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

  1. Nel progetto di Visual Studio, aggiungere un file del tipo che si desidera generare, quale un file .cs, .vb, o .resx.

  2. Testare il nuovo file per assicurarsi che funzioni.

  3. In Esplora soluzioni impostare l'estensione del file su .tt.

  4. Verificare le proprietà seguenti del file .tt:

    Strumento personalizzato =

    TextTemplatingFileGenerator

    Operazione di compilazione =

    None

  5. 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.

  6. 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.

  7. 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 tramite modelli di testo T4 pre-elaborati

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

Altre risorse

Linee guida per la scrittura di modelli di testo T4

Cronologia delle modifiche

Data

Cronologia

Motivo

Ottobre 2010

Aggiunti campioni VB.

Spostate linee guida in un argomento separato.

Miglioramento delle informazioni.