Blocchi di controllo del modello di testo

I blocchi di controllo consentono di scrivere codice nel modello di testo per variare l'output. Esistono tre tipi di blocchi di controllo, che sono distinti in base alle parentesi di apertura:

• <# Standard control blocks #> può contenere istruzioni.

• <#= Expression control blocks #> può contenere espressioni.

• <#+ Class feature control blocks #> può contenere metodi, campi e proprietà.

Blocco di controllo standard

I blocchi di controllo standard contengono istruzioni. Ad esempio, il blocco standard seguente ottiene i nomi di tutti gli attributi nel documento XML:

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

<#
    List<string> allAttributes = new List<string>();
    XmlDocument xDoc = new XmlDocument();
    xDoc.Load(@"E:\CSharp\Overview.xml");
    XmlAttributeCollection attributes = xDoc.Attributes;
    if (attributes.Count > 0)
    {
       foreach (XmlAttribute attr in attributes)
       {
           allAtributes.Add(attr.Name);
       }
     }
#>

È possibile incorporare testo normale all'interno di un'istruzione composta, if ad esempio o for. Ad esempio, questo frammento genera una riga di output in ogni iterazione del ciclo:

<#
       foreach (XmlAttribute attr in attributes)
       {
#>
Found another one!
<#
           allAtributes.Add(attr.Name);
       }
#>

Avvertimento

Usare sempre {...} per delimitare le istruzioni annidate che contengono testo normale incorporato. L'esempio seguente potrebbe non funzionare correttamente:

<# if (ShouldPrint) #> Some text. -- WRONG

Dovresti invece includere {graffe}, come segue:

<#
 if (ShouldPrint)
 {   //  "{" REQUIRED
#>
Some text.
<#
 }
#>

Blocco di controllo delle espressioni

I blocchi di controllo delle espressioni vengono usati per il codice che fornisce stringhe da scrivere nel file di output. Ad esempio, con l'esempio precedente, è possibile stampare i nomi degli attributi nel file di output modificando il blocco di codice come segue:

<#
    XmlDocument xDoc = new XmlDocument();
    xDoc.Load(@"E:\CSharp\Overview.xml");
    XmlAttributeCollection attributes = xDoc.Attributes;
    if (attributes != null)
    {
       foreach (XmlAttribute attr in attributes)
       {
#><#= attr.Name #><#
       }
    }
#>

Blocco di controllo delle caratteristiche della classe

È possibile usare blocchi di controllo delle funzionalità della classe per aggiungere metodi, proprietà, campi o anche classi annidate al modello di testo. L'uso più comune dei blocchi di funzionalità di classe consiste nel fornire funzioni helper per il codice in altre parti del modello di testo. Ad esempio, il blocco di funzionalità della classe seguente mette in maiuscolo la prima lettera del nome dell'attributo (o, se il nome contiene spazi vuoti, mette in maiuscolo la prima lettera di ogni parola):

<#@ import namespace="System.Globalization" #>

<#+
    private string FixAttributeName(string name)
    {
        return CultureInfo.CurrentCulture.TextInfo.ToTitleCase(name);
    }
#>

Annotazioni

Un blocco di controllo delle funzionalità di classe non deve essere seguito da blocchi di controllo standard nello stesso file modello. Tuttavia, questa restrizione non si applica al risultato delle direttive using <#@include#> . Ogni file incluso può avere blocchi standard seguiti da blocchi di funzionalità di classe.

È possibile creare una funzione che genera l'output incorporando blocchi di testo ed espressione all'interno di un blocco di controllo funzionalità della classe. Per esempio:

<#+
    private void OutputFixedAttributeName(string name)
    {
#>
 Attribute:  <#= CultureInfo.CurrentCulture.TextInfo.ToTitleCase(name) #>
<#+  // <<< Notice that this is also a class feature block.
    }
#>

È possibile chiamare questa funzione da un blocco standard o da un altro blocco di funzionalità di classe:

<# foreach (Attribute attribute in item.Attributes)
{
  OutputFixedAttributeName(attribute.Name);
}
#>

Come usare i blocchi di controllo

Tutto il codice in tutti i blocchi di controllo standard ed espressione in un singolo modello (incluso tutto il codice nei modelli inclusi) viene combinato per formare il TransformText() metodo del codice generato. Per altre informazioni sull'inclusione di altri modelli di testo con la direttiva include, vedere le Direttive dei Modelli di Testo T4.

Quando si usano blocchi di controllo, tenere presenti le considerazioni seguenti:

• Lingua. È possibile usare codice C# o Visual Basic in un modello di testo. Il linguaggio predefinito è C#, ma è possibile specificare Visual Basic con il language parametro della template direttiva . Per altre informazioni sulla template direttiva, vedere Direttive del modello di testo T4.

  La lingua usata nei blocchi di controllo non ha nulla a che fare con la lingua o il formato del testo generato in un modello di testo. È possibile generare C# usando codice Visual Basic o viceversa.

  È possibile usare una sola lingua in un determinato modello di testo, inclusi tutti i modelli di testo inclusi nella include direttiva .

• Variabili locali. Poiché tutto il codice nei blocchi di controllo standard ed espressione in un modello di testo viene generato come singolo metodo, è necessario assicurarsi che non ci siano conflitti con i nomi delle variabili locali. Se si includono altri modelli di testo, è necessario assicurarsi che i nomi delle variabili siano univoci in tutti i modelli inclusi. Un modo per assicurarsi di aggiungere una stringa a ogni nome di variabile locale che identifica il modello di testo in cui è dichiarato.

  È anche consigliabile inizializzare le variabili locali in valori sensibili quando vengono dichiarati, in particolare quando si includono più modelli di testo.

• Annidamento dei blocchi di controllo. I blocchi di controllo non possono essere annidati tra loro. È necessario terminare sempre un determinato blocco di controllo prima di aprirlo un altro. Nell'esempio seguente viene illustrato come stampare testo in un blocco di espressioni come parte di un blocco di controllo standard.

  <#
  int x = 10;
  while (x-- > 0)
  {
  #>
  <#= x #>
  <# } #>
  

• Refactoring. Per mantenere i modelli di testo brevi e facili da comprendere, è consigliabile evitare codice ripetitivo inserendo il codice riutilizzabile in funzioni helper nei blocchi di funzionalità di classe o creando una classe modello di testo personalizzata che eredita dalla classe Microsoft.VisualStudio.TextTemplating.TextTransformation.