Blocs de contrôle de modèle de texte

Les blocs de contrôle vous permettent d’écrire du code dans votre modèle de texte afin de varier la sortie. Il existe trois types de blocs de contrôle, qui se distinguent par leurs crochets ouvrants :

• <# Standard control blocks #> peut contenir des instructions.

• <#= Expression control blocks #> peut contenir des expressions.

• <#+ Class feature control blocks #> peut contenir des méthodes, des champs et des propriétés.

Bloc de contrôle standard

Les blocs de contrôle standard contiennent des instructions. Par exemple, le bloc standard suivant obtient les noms de tous les attributs du document 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);
       }
     }
#>

Vous pouvez incorporer du texte brut à l’intérieur d’une instruction composée telle que if ou for. Par exemple, ce fragment génère une ligne de sortie dans chaque itération de boucle :

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

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

Bloc de contrôle d’expression

Les blocs de contrôle d’expression sont utilisés pour le code qui fournit des chaînes à écrire dans le fichier de sortie. Par exemple, avec l’exemple ci-dessus, vous pouvez imprimer les noms des attributs dans le fichier de sortie en modifiant le bloc de code comme suit :

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

Bloc de contrôle de fonctionnalité de classe

Vous pouvez utiliser des blocs de contrôle de fonctionnalité de classe pour ajouter des méthodes, des propriétés, des champs ou même des classes imbriquées à votre modèle de texte. L’utilisation la plus courante des blocs de fonctionnalités de classe consiste à fournir des fonctions d’assistance pour le code dans d’autres parties du modèle de texte. Par exemple, le bloc de caractéristiques de classe suivant met en majuscule la première lettre du nom d’attribut (ou, si le nom contient un espace blanc, il met en majuscule la première lettre de chaque mot) :

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

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

Vous pouvez créer une fonction qui génère la sortie en incorporant des blocs de texte et d’expression à l’intérieur d’un bloc de contrôle de fonctionnalité de classe. Par exemple:

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

Vous pouvez appeler cette fonction à partir d’un bloc standard ou d’un autre bloc de fonctionnalités de classe :

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

Comment utiliser des blocs de contrôle

Tout le code de tous les blocs de contrôle standard et d’expression dans un seul modèle (y compris tout le code dans les modèles inclus) est combiné pour former la TransformText() méthode du code généré. (Pour plus d’informations sur l’inclusion d’autres modèles de texte avec la include directive, consultez directives de modèle de texte T4.)

Gardez à l’esprit les considérations suivantes lorsque vous utilisez des blocs de contrôle :

• Langue. Vous pouvez utiliser du code C# ou Visual Basic dans un modèle de texte. Le langage par défaut est C#, mais vous pouvez spécifier Visual Basic avec le language paramètre de la template directive. (Pour plus d’informations sur la template directive, consultez directives de modèle de texte T4.)

  La langue que vous utilisez dans les blocs de contrôle n’a rien à voir avec la langue ou le format du texte que vous générez dans un modèle de texte. Vous pouvez générer C# à l’aide du code Visual Basic ou inversement.

  Vous ne pouvez utiliser qu’une seule langue dans un modèle de texte donné, y compris tous les modèles de texte que vous incluez avec la include directive.

• Variables locales. Étant donné que tout le code dans les blocs de contrôle standard et d’expression d’un modèle de texte est généré en tant que méthode unique, vous devez vous assurer qu’il n’existe aucun conflit avec les noms des variables locales. Si vous incluez d’autres modèles de texte, vous devez vous assurer que les noms de variables sont uniques dans tous les modèles inclus. Une façon d'assurer cela est d'ajouter une chaîne de caractères à chaque nom de variable locale identifiant le modèle de texte dans lequel elle a été déclarée.

  Il est également judicieux d’initialiser vos variables locales en valeurs sensibles lorsque vous les déclarez, en particulier lorsque vous incluez plusieurs modèles de texte.

• Imbrication des blocs de contrôle. Les blocs de contrôle peuvent ne pas être imbriqués entre eux. Vous devez toujours arrêter un bloc de contrôle donné avant d’en ouvrir un autre. Par exemple, l’exemple suivant montre comment imprimer du texte dans un bloc d’expression dans le cadre d’un bloc de contrôle standard.

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

• Refactorisation. Pour que vos modèles de texte restent courts et faciles à comprendre, il est vivement recommandé d’éviter le code répétitif en factorisant le code réutilisable en fonctions d’assistance dans les blocs de fonctionnalités de classe ou en créant votre propre classe de modèle de texte qui hérite de la classe Microsoft.VisualStudio.TextTemplating.TextTransformation.