Blocs de contrôle des modèles de texteText Template Control Blocks

Les blocs de contrôle vous permettent d'écrire du code dans votre modèle de texte pour faire varier la sortie.Control blocks let you write code in your text template in order to vary the output. Il existe trois types de blocs de contrôle, distingués par leurs crochets d'ouverture :There are three kinds of control blocks, which are distinguished by their opening brackets:

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

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

  • <#+ Class feature control blocks #> peut contenir des méthodes, des propriétés et des champs.<#+ Class feature control blocks #> can contain methods, fields and properties.

Bloc de contrôle standardStandard control block

Les blocs de contrôle standard contiennent des instructions.Standard control blocks contain statements. Par exemple, le bloc standard suivant obtient les noms de tous les attributs du document XML :For example, the following standard block gets the names of all the attributes in the XML document:

<#@ 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 dans une instruction composée comme if ou for.You can embed plain text inside a compound statement such as if or for. Par exemple, ce fragment génère une ligne de sortie dans chaque itération de boucle :For example, this fragment generates an output line in each loop iteration:

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

Avertissement

Utilisez toujours {...}Always use {...} pour délimiter les instructions imbriquées qui contiennent le texte brut incorporé.to delimit nested statements that contain embedded plain text. L'exemple suivant peut ne pas fonctionner correctement :The following example might not work properly:

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

À la place, vous devez inclure des {accolades}, comme suit :Instead, you should include {braces}, as follows:


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

Bloc de contrôle d'expressionExpression control block

Les blocs de contrôle d'expression sont utilisés pour le code qui fournit des chaînes à écrire dans le fichier de sortie.Expression control blocks are used for code that provides strings to be written to the output file. 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 :For example, with the example above, you can print the names of the attributes to the output file by modifying the code block as follows:

<#  
    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 classeClass feature control block

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.You can use class feature control blocks to add methods, properties, fields, or even nested classes to your text template. Les blocs de fonctionnalité de classe sont le plus souvent utilisés pour fournir des fonctions d’assistance pour le code dans d’autres parties du modèle de texte.The most common use of class feature blocks is to provide helper functions for code in other parts of the text template. Par exemple, le bloc de fonctionnalité de classe suivant met en majuscule la première lettre du nom de l'attribut (ou la première lettre de chaque mot si le nom contient un espace blanc) :For example, the following class feature block capitalizes the first letter of the attribute name (or, if the name contains whitespace, it capitalizes the first letter of every word):

<#@ import namespace="System.Globalization" #>  
<#+  
    private string FixAttributeName(string name)  
    {  
        return CultureInfo.CurrentCulture.TextInfo.ToTitleCase(name);  
    }  
#>  

Note

Un bloc de contrôle de fonctionnalité de classe ne doit pas être suivi de blocs de contrôle standard dans le même fichier modèle.A class feature control block must not be followed by standard control blocks in the same template file. Toutefois, cette restriction ne s'applique pas au résultat de l'utilisation de directives <#@include#>.However, this restriction does not apply to the result of using <#@include#> directives. Chaque fichier inclus peut avoir des blocs standard suivis de blocs de fonctionnalité de classe.Each included file can have standard blocks followed by class feature blocks.

Vous pouvez créer une fonction qui génère une sortie en incorporant des blocs de texte et d'expression dans un bloc de contrôle de fonctionnalité de classe.You can create a function that generates output by embedding text and expression blocks inside a class feature control block. Par exemple :For example:

<#+  
    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é de classe :You could call this function from a standard block or from another class feature block:

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

Comment utiliser les blocs de contrôleHow to use control blocks

Tout le code contenu dans chacun des blocs de contrôle d'expression et standard d'un modèle unique (y compris celui figurant dans les modèles inclus) est combiné pour former la méthode TransformText() du code généré.All the code in all the standard and expression control blocks in a single template (including all the code in included templates) is combined to form the TransformText() method of the generated code. (Pour plus d’informations sur l’inclusion d’autres modèles de texte avec le include directive, voir Directives de modèle de texte T4.)(For more information about including other text templates with the include directive, see T4 Text Template Directives.)

Vous devez tenir compte des considérations suivantes quand vous utilisez des blocs de contrôle :You should keep in mind the following considerations when you use control blocks:

  • Langage.Language. Vous pouvez utiliser du code C# ou Visual Basic dans un modèle de texte.You can use either C# or Visual Basic code in a text template. Le langage par défaut est C#, mais vous pouvez spécifier Visual Basic avec le paramètre language de la directive template.The default language is C#, but you can specify Visual Basic with the language parameter of the template directive. (Pour plus d’informations sur la template directive, voir Directives de modèle de texte T4.)(For more information about the template directive, see T4 Text Template Directives.)

    Le langage que vous utilisez dans les blocs de contrôle n'a aucun rapport avec le langage ou le format du texte que vous générez dans un modèle de texte.The language you use in control blocks has nothing to do with the language or format of the text you generate in a text template. Vous pouvez générer du code C# en utilisant du code Visual Basic ou vice versa.You can generate C# by using Visual Basic code or vice versa.

    Vous ne pouvez utiliser qu'un seul langage dans un modèle de texte donné, y compris tous les modèles de texte que vous incluez avec la directive include.You can use only one language in a given text template, including all the text templates you include with the include directive.

  • Variables locales.Local variables. Étant donné que tout le code des blocs de contrôle d'expression et standard d'un modèle de texte est généré sous la forme d'une méthode unique, vous devez vérifier qu'il n'existe aucun conflit avec les noms des variables locales.Since all the code in the standard and expression control blocks in a text template is generated as a single method, you should make certain that there are no conflicts with the names of local variables. Si vous incluez d'autres modèles de texte, vous devez vous assurer que les noms de variables sont uniques pour tous les modèles inclus.If you are including other text templates, you must make sure that variable names are unique across all included templates. Pour ce faire, une méthode consiste à ajouter à chaque nom de variable locale une chaîne identifiant le modèle de texte dans lequel il a été déclaré.One way to ensure this is to add a string to each local variable name identifying the text template in which it was declared.

    Nous vous recommandons également d'initialiser vos variables locales à des valeurs sensibles quand vous les déclarez, en particulier quand vous incluez plusieurs modèles de texte.It is also a good idea to initialize your local variables to sensible values when you declare them, particularly when you are including multiple text templates.

  • Imbrication de blocs de contrôle.Nesting of control blocks. Les blocs de contrôle ne peuvent pas être imbriqués les uns dans les autres.Control blocks may not be nested inside each other. Vous devez toujours terminer un bloc de contrôle donné avant d'en ouvrir un autre.You must always terminate a given control block before you open another one. Par exemple, le code suivant montre comment imprimer du texte d'un bloc d'expression dans le cadre d'un bloc de contrôle standard.For example, the following shows how to print some text in an expression block as part of a standard control block.

    <#   
    int x = 10;  
    while (x-- > 0)  
    {  
    #>  
    <#= x #>  
    <# } #>  
    
  • La refactorisation.Refactoring. Pour que vos modèles de texte restent courts et faciles à comprendre, nous vous recommandons fortement d’éviter d’employer du code répétitif en factorisant le code réutilisable au sein de fonctions d’assistance dans des blocs de fonctionnalité de classe ou en créant votre propre classe de modèle de texte qui hérite de la classe Microsoft.VisualStudio.TextTemplating.TextTransformation.In order to keep your text templates short and easy to understand, it is strongly recommended that you avoid repetitive code either by factoring the reusable code into helper functions in class feature blocks or by creating your own text template class that inherits from the Microsoft.VisualStudio.TextTemplating.TextTransformation class.