Linee guida per la scrittura di modelli di testo T4

Queste linee guida generali possono essere utili se si genera codice programma o altre risorse dell'applicazione in Visual Studio.Non si tratta di regole fisse.

Linee guida per i modelli T4 della fase di progettazione

I modelli T4 della fase di progettazione sono modelli che in fase di progettazione generano codice nel progetto di Visual Studio.Per ulteriori informazioni, vedere Generazione di codice in fase di progettazione tramite modelli di testo T4.

• Generare aspetti variabili dell'applicazione.
  La generazione di codice è molto utile per quegli aspetti dell'applicazione che potrebbero cambiare durante il progetto o che cambieranno tra le diverse versioni dell'applicazione.Separare questi aspetti variabili da quelli fissi in modo che sia possibile determinare più facilmente che cosa deve essere generato.Ad esempio, se l'applicazione fornisce un sito Web, separare le funzioni che gestiscono la pagina standard dalla logica che definisce i percorsi di navigazione da una pagina all'altra.

• Codificare gli aspetti variabili in uno o più modelli di origine.
  Un modello è un file o un database che ogni modello legge per ottenere valori specifici per le parti variabili del codice che deve essere generato.I modelli possono essere database, file XML di progettazione, diagrammi o linguaggi specifici di dominio.In genere, viene utilizzato un unico modello per generare molti file in un progetto di Visual Studio. Ogni file viene generato da un modello separato.

  È possibile utilizzare più di un modello in un progetto.Ad esempio, è possibile definire un modello per la navigazione tra pagine Web e un modello separato per il layout delle pagine.

• Incentrare il modello sulle necessità e sul vocabolario degli utenti, anziché sull'implementazione.
  Ad esempio, in un'applicazione siti Web, il modello dovrebbe fare riferimento a pagine Web e collegamenti ipertestuali.

  È preferibile scegliere un form di presentazione adatto al genere di informazioni che il modello rappresenta.Ad esempio, un modello di percorsi di navigazione tramite un sito Web potrebbe essere un diagramma di caselle e di frecce.

• Testare il codice generato.
  Utilizzare i test manuali o automatizzati per verificare che il codice risultante funzioni come richiesto dagli utenti.Evitare di generare test dallo stesso modello da cui viene generato il codice.

  In alcuni casi, è possibile eseguire test generici direttamente sul modello.Ad esempio, è possibile scrivere un test per verificare che ogni pagina nel sito Web può essere raggiunta tramite navigazione da qualsiasi altro punto.

• Lasciare spazio a del codice personalizzato: generare classi parziali.
  Lasciare spazio al codice che si scrive a mano in aggiunta al codice generato.È difficile che uno schema di generazione di codice riesca a prendere in considerazione tutte le variazioni possibili che potrebbero sorgere.Pertanto, è necessario prevedere la possibilità di apportare aggiunte al codice generato o di eseguire l'override di alcune parti del codice.Laddove il materiale generato è in linguaggio .NET, ad esempio Visual C# o Visual Basic, due strategie sono particolarmente utili:

  • Le classi generate devono essere parziali.In questo modo è possibile aggiungere contenuto al codice generato.

  • Le classi devono essere generate a coppie, quindi una eredita dall'altra.La classe di base deve contenere tutti i metodi e le proprietà generati e la classe derivata deve contenere solo i costruttori.Questo consente al codice scritto a mano di eseguire l'override di qualsiasi metodo generato.

  Negli altri linguaggi generati, quale il linguaggio XML, utilizzare la direttiva <#@include#> per creare semplici combinazioni di contenuto scritto a mano e contenuto generato.Nei casi più complessi, potrebbe essere necessario scrivere un passaggio della post-elaborazione che combina il file generato con il file scritto a mano.

• Spostare il materiale comune nei file di inclusione o nei modelli della fase di esecuzione
  Per non ripetere blocchi simili di testo e codice in più modelli, utilizzare la direttiva <#@ include #>.Per ulteriori informazioni, vedere Direttiva include T4.

  È inoltre possibile compilare modelli di testo della fase di esecuzione in un progetto separato, quindi chiamarli dal modello della fase di progettazione.A questo scopo, utilizzare la direttiva <#@ assembly #> per accedere al progetto separato.Per i relativi esempi, vedere "Ereditarietà nei modelli di testo" nel blog di Gareth Jones.

• Si consiglia di spostare i blocchi di codice di grandi dimensioni in un assembly separato.
  Se si dispone di blocchi di codice e blocchi della funzionalità di classe di grandi dimensioni, potrebbe essere utile spostare parte di questo codice nei metodi che vengono compilati in un progetto separato.È possibile utilizzare la direttiva <#@ assembly #> per accedere al codice nel modello.Per ulteriori informazioni, vedere Direttiva assembly T4.

  È possibile inserire i metodi in una classe astratta che può essere ereditata dal modello.La classe astratta deve ereditare da Microsoft.VisualStudio.TextTemplating.TextTransformation.Per ulteriori informazioni, vedere Direttiva template T4.

• Generare codice, non file di configurazione
  Un metodo della scrittura di un'applicazione variabile consiste nello scrivere codice programma generico che accetta un file di configurazione.Un'applicazione scritta in questo modo risulta molto flessibile e può essere riconfigurata quando i requisiti aziendali cambiano, senza la necessità di ricompilare l'applicazione.Tuttavia, un inconveniente di questo approccio è che le prestazioni dell'applicazione saranno inferiori rispetto a un'applicazione più specifica.Inoltre, il codice programma sarà più difficile da leggere e da gestire, in parte perché dovrà sempre gestire i tipi più generici.

  Un'applicazione le cui parti variabili vengono generate prima della compilazione può al contrario essere fortemente tipizzata.Diventa così molto più semplice e sicuro scrivere codice a mano e integrarlo con le parti generate del software.

  Per trarre pieno vantaggio dalla generazione di codice, provare a generare codice programma anziché file di configurazione.

• Utilizzare una cartella Codice generato
  Posizionare i modelli e i file generati in una cartella del progetto denominata Codice generato perché sia chiaro che questi non sono file da modificare direttamente.Se si crea codice personalizzato per eseguire l'override di classi generate o da aggiungere a tali classi, posizionare queste classi in una cartella denominata Codice personalizzato.La struttura di un progetto tipico ha il seguente aspetto:

  MyProject
     Custom Code
        Class1.cs
        Class2.cs
     Generated Code
        Class1.tt
            Class1.cs
        Class2.tt
            Class2.cs
     AnotherClass.cs
  
  

Linee guida per i modelli T4 (pre-elaborati) della fase di esecuzione

• Spostare il materiale comune nei modelli ereditati
  È possibile utilizzare l'ereditarietà per condividere metodi e blocchi di testo tra modelli di testo T4.Per ulteriori informazioni, vedere Direttiva template T4.

  È inoltre possibile utilizzare file di inclusione contenenti modelli della fase di esecuzione.

• Spostare grandi quantità di codice in una classe parziale.
  Ogni modello della fase di esecuzione genera una definizione di classe parziale con lo stesso nome del modello.È possibile scrivere un file di codice contenente un'altra definizione parziale della stessa classe.In questo modo è possibile aggiungere alla classe metodi, campi e costruttori.Questi membri possono essere chiamati dai blocchi di codice nel modello.

  Il vantaggio di questa operazione è che il codice è più facile da scrivere perché è disponibile IntelliSense.È inoltre possibile ottenere una separazione migliore tra la presentazione e la logica sottostante.

  Ad esempio in MyReportText.tt:

  The total is: <#= ComputeTotal() #>

  In MyReportText-Methods.cs:

  private string ComputeTotal() { ... }

• Lasciare spazio a del codice personalizzato: fornire punti di estensione
  Si consiglia di generare metodi virtuali in < #+ blocchi della funzionalità di classe #>.In questo modo è possibile utilizzare un singolo modello in molti contesti senza bisogno di modifiche.Anziché modificare il modello, è possibile costruire una classe derivata che fornisca la logica aggiuntiva minima.La classe derivata può essere codice normale o un modello della fase di esecuzione.

  Ad esempio, in MyStandardRunTimeTemplate.tt:

  This page is copyright <#= CompanyName() #>.
  <#+ protected virtual string CompanyName() { return ""; } #>
  

  Nel codice di un'applicazione:

  class FabrikamTemplate : MyStandardRunTimeTemplate
  {
    protected override string CompanyName() { return "Fabrikam"; }
  }
  ...
    string PageToDisplay = new FabrikamTemplate().TextTransform();
  

Linee guida per tutti i modelli T4

• Raccolta di dati separata dalla generazione di testo
  Cercare di evitare l'utilizzo contemporaneo di calcolo e blocchi di testo.In ciascun modello di testo, utilizzare il primo <# blocco di codice #> per impostare le variabili ed eseguire calcoli complessi.Dal primo blocco di testo fino alla fine del modello o il primo <#+ blocco della funzionalità di classe #>, evitare espressioni lunghe, nonché cicli e istruzioni condizionali a meno che non contengano blocchi di testo.Questo rende il modello più facile da leggere e gestire.

• Non utilizzare .tt per i file di inclusione
  Utilizzare un'estensione di file diversa, come .ttinclude per i file di inclusione.Utilizzare .tt solo per i file che si desidera che vengano elaborati come modelli di testo della fase di esecuzione o come modelli di testo della fase di progettazione.In alcuni casi, Visual Studio riconosce i file .tt e imposta automaticamente le relative proprietà per l'elaborazione.

• Avviare ogni modello come prototipo fisso.
  Scrivere un esempio del codice o del testo che si desidera generare e verificare che sia corretto.Impostare quindi l'estensione su .tt e inserire gradualmente il codice che modifica il contenuto mentre legge il modello.

• Si consiglia di utilizzare modelli tipizzati.
  Anche se è possibile creare un XML Schema o uno schema del database per i modelli, potrebbe essere utile creare un linguaggio specifico di dominio (DSL).Il vantaggio del linguaggio DSL è che genera una classe per rappresentare ogni nodo nello schema e le proprietà per rappresentare gli attributi.Questo significa che è possibile programmare facendo riferimento al modello aziendale.Di seguito è riportato un esempio:

  Team Members:
  <# foreach (Person p in team.Members) 
   { #> 
      <#= p.Name #> 
  <# } #>
  

• Si consiglia di utilizzare i diagrammi per i modelli.
  Molti modelli sono presentati e gestiti più efficacemente semplicemente come tabelle di testo, specialmente se sono molto grandi.

  Tuttavia, per alcuni tipi di requisiti aziendali, è importante chiarire i set complessi di relazioni e flussi di lavoro e i diagrammi sono il mezzo meglio indicato.Un vantaggio del diagramma è che è facile da discutere con utenti e altre parti interessate.Generando codice da un modello al livello di requisiti aziendali, si rende il codice più flessibile in caso di variazione dei requisiti.

  È spesso possibile adattare la classe UML e i diagrammi di attività per tali scopi.È inoltre possibile progettare un tipo di diagramma personalizzato come linguaggio specifico di dominio (DSL).Il codice può essere generato sia dai linguaggi ULM che DSL.Per ulteriori informazioni, vedere Modellazione dell'applicazione e Modellazione dell'applicazione.

Vedere anche

Concetti

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

Generazione di testo in fase di esecuzione con modelli di testo T4