Écriture d'un modèle de texte T4Writing a T4 Text Template

Un modèle de texte contient le texte qui sera généré à partir du modèle.A text template contains the text that will be generated from it. Par exemple, un modèle qui crée une page web contiendra «<html > … » et tous les autres composants standard d’une page HTML.For example, a template that creates a web page will contain "<html>..." and all the other standard parts of an HTML page. Inséré dans le modèle sont blocs de contrôle, qui sont des fragments de code de programme.Inserted into the template are control blocks, which are fragments of program code. Les blocs de contrôle fournissent des valeurs variables et permettent à certaines parties du texte d'être conditionnelles et répétées.Control blocks provide varying values and allow parts of the text to be conditional and repeated.

Cette structure simplifie le développement de modèle, car vous pouvez commencer avec un prototype du fichier généré et insérer de manière incrémentielle des blocs de contrôle qui font varier le résultat.This structure makes a template easy to develop, because you can start with a prototype of the generated file, and incrementally insert control blocks that vary the result.

Les modèles de texte sont formés des composants suivants :Text templates are composed of the following parts:

  • Directives -éléments qui contrôlent la façon dont le modèle est traité.Directives - elements that control how the template is processed.

  • Blocs de texte - contenu copié directement dans la sortie.Text blocks - content that is copied directly to the output.

  • Blocs de contrôle -code de programme qui insère les valeurs des variables dans le texte et contrôle les parties conditionnelles ou répétées du texte.Control blocks - program code that inserts variable values into the text, and controls conditional or repeated parts of the text.

    Pour tester les exemples de cette rubrique, copiez-les dans un fichier de modèle comme décrit dans génération du Code à l’aide de modèles de texte T4 au moment du Design.To try the examples in this topic, copy them into a template file as described in Design-Time Code Generation by using T4 Text Templates. Après avoir modifié le fichier de modèle, enregistrez-le, puis examinez la sortie .txt fichier.After editing the template file, save it, and then inspect the output .txt file.

DirectivesDirectives

Les directives de modèle de texte fournissent des instructions générales au moteur de création de modèles de texte concernant la manière de générer le code de transformation et le fichier de sortie.Text template directives provide general instructions to the text templating engine about how to generate the transformation code and the output file.

Par exemple, la directive suivante spécifie que le fichier de sortie doit avoir une extension .txt :For example, the following directive specifies that the output file should have a .txt extension:


<#@ output extension=".txt" #>

Pour plus d’informations sur les directives, consultez Directives de modèle de texte T4.For more information about directives, see T4 Text Template Directives.

Blocs de texteText blocks

Un bloc de texte insère du texte directement dans le fichier de sortie.A text block inserts text directly into the output file. Il n'y a aucune mise en forme spéciale pour les blocs de texte.There is no special formatting for text blocks. Par exemple, le modèle de texte suivant produit un fichier texte qui contient le mot « Hello » :For example, the following text template will produce a text file that contains the word "Hello":

<#@ output extension=".txt" #>
Hello

Blocs de contrôleControl blocks

Les blocs de contrôle sont des sections de code de programme qui servent à transformer les modèles.Control blocks are sections of program code that are used to transform the templates. Le langage par défaut est C#, mais pour utiliser Visual BasicVisual Basic vous pouvez écrire cette directive au début du fichier :The default language is C#, but to use Visual BasicVisual Basic, you can write this directive at the beginning of the file:

<#@ template language="VB" #>

Le langage dans lequel vous écrivez le code dans les blocs de contrôle est sans rapport avec la langue du texte généré.The language in which you write the code in the control blocks is unrelated to the language of the text that is generated.

Blocs de contrôle standardStandard control blocks

Un bloc de contrôle standard est une section de code de programme qui génère une partie du fichier de sortie.A standard control block is a section of program code that generates part of the output file.

Vous pouvez combiner autant de blocs de texte et de blocs de contrôle standard que vous le souhaitez dans un fichier de modèle.You can mix any number of text blocks and standard control blocks in a template file. Toutefois, vous ne pouvez pas placer un bloc de contrôle dans un autre.However, you cannot place one control block inside another. Chaque bloc de contrôle standard est délimité par les symboles <# ... #>.Each standard control block is delimited by the symbols <# ... #>.

Par exemple, le bloc de contrôle et le bloc de texte suivants font en sorte que le fichier de sortie contienne la ligne « 0, 1, 2, 3, 4 Hello! ».For example, the following control block and text block cause the output file to contain the line "0, 1, 2, 3, 4 Hello!":


      <#
    for(int i = 0; i < 4; i++)
    {
        Write(i + ", ");
    }
    Write("4");
#> Hello!

Au lieu d'utiliser des instructions Write() explicites, vous pouvez entrelacer du texte et du code.Instead of using explicit Write() statements, you can interleave text and code. L’exemple suivant imprime « Hello ! »The following example prints "Hello!" quatre fois :four times:

<#
    for(int i = 0; i < 4; i++)
    {
#>
Hello!
<#
    }
#>

Vous pouvez insérer un bloc de texte partout où une instruction Write(); serait autorisée dans le code.You can insert a text block wherever a Write(); statement would be allowed in the code.

Note

Lorsque vous incorporez un bloc de texte dans une instruction composée telle qu’une boucle ou conditionnel, utilisez toujours des accolades {...}When you embed a text block within a compound statement such as a loop or conditional, always use braces {...} pour contenir le bloc de texte.to contain the text block.

Blocs de contrôle d'expressionExpression control blocks

Un bloc de contrôle d'expression évalue une expression et la convertit en chaîne.An expression control block evaluates an expression and converts it to a string. Celle-ci est insérée dans le fichier de sortie.This is inserted into the output file.

Les blocs de contrôle d'expression sont délimités par les symboles <#= ... #>.Expression control blocks are delimited by the symbols <#= ... #>

Par exemple, le bloc de contrôle suivant fait en sorte que le fichier de sortie contienne « 5 » :For example, the following control block causes the output file to contain "5":

<#= 2 + 3 #>

Notez que le symbole d'ouverture comporte trois caractères « <#= ».Notice that the opening symbol has three characters "<#=".

L'expression peut inclure toute variable qui est dans la portée.The expression can include any variable that is in scope. Par exemple, ce bloc imprime des lignes avec des nombres :For example, this block prints lines with numbers:

<#@ output extension=".txt" #>
<#
    for(int i = 0; i < 4; i++)
    {
#>
This is hello number <#= i+1 #>: Hello!
<#
    }
#>

Bloc de contrôle de fonctionnalité de classeClass feature control blocks

Un bloc de contrôle de fonctionnalité de classe définit des propriétés, des méthodes ou tout autre code qui ne doit pas être inclus dans la transformation principale.A class feature control block defines properties, methods, or any other code that should not be included in the main transform. Les blocs de fonctionnalité de classe sont fréquemment utilisés pour les fonctions d’assistance.Class feature blocks are frequently used for helper functions. En règle générale, les blocs de fonctionnalité de classe sont placés dans des fichiers distincts afin qu’ils puissent être inclus par plusieurs modèles de texte.Typically, class feature blocks are placed in separate files so that they can be included by more than one text template.

Les blocs de fonctionnalité de classe sont délimités par les symboles <#+ ... #>.Class feature control blocks are delimited by the symbols <#+ ... #>

Par exemple, le fichier de modèle suivant déclare et utilise une méthode :For example, the following template file declares and uses a method:

<#@ output extension=".txt" #>
Squares:
<#
    for(int i = 0; i < 4; i++)
    {
#>
    The square of <#= i #> is <#= Square(i+1) #>.
<#
    }
#>
That is the end of the list.
<#+   // Start of class feature block
private int Square(int i)
{
    return i*i;
}
#>

Les fonctionnalités de classe doivent être placées à la fin du fichier dans lequel elles sont écrites.Class features must be placed at the end of the file in which they are written. Toutefois, vous pouvez inclure (<#@include#>) un fichier qui contient une fonctionnalité de classe, même si la directive include est suivie de texte et de blocs ordinaires.However, you can <#@include#> a file that contains a class feature, even if the include directive is followed by standard blocks and text.

Pour plus d’informations sur les blocs de contrôle, consultez blocs de contrôle de modèle de texte.For more information about control blocks, see Text Template Control Blocks.

Les blocs de fonctionnalité de classe peuvent contenir des blocs de texteClass feature blocks can contain text blocks

Vous pouvez écrire une méthode qui génère du texte.You can write a method that generates text. Par exemple :For example:

List of Squares:
<#
   for(int i = 0; i < 4; i++)
   {  WriteSquareLine(i); }
#>
End of list.
<#+   // Class feature block
private void WriteSquareLine(int i)
{
#>
   The square of <#= i #> is <#= i*i #>.
<#+
}
#>

Il est particulièrement utile de placer une méthode qui génère du texte dans un fichier distinct pouvant être inclus par plusieurs modèles.It is particularly useful to place a method that generates text in a separate file that can be included by more than one template.

Utilisation de définitions externesUsing external definitions

AssemblysAssemblies

Les blocs de code de votre modèle peuvent utiliser des types définis par les assemblys .NET les plus fréquemment utilisés tels que System.dll.The code blocks of your template can use types that are defined the most frequently used .NET assemblies such as System.dll. De plus, vous pouvez faire référence à d'autres assemblys .NET ou à vos propres assemblys.In addition, you can reference other .NET assemblies or your own assemblies. Vous pouvez fournir un nom de chemin d'accès ou le nom fort d'un assembly :You can provide a pathname, or the strong name of an assembly:

<#@ assembly name="System.Xml" #>

Vous devez utiliser des noms de chemins d'accès absolus ou des noms de macros standard dans le nom du chemin d'accès.You should use absolute path names, or use standard macro names in the path name. Par exemple :For example:

<#@ assembly name="$(SolutionDir)library\MyAssembly.dll" #>

La directive assembly n’a aucun effet un modèle de texte prétraité.The assembly directive has no effect in a preprocessed text template.

Pour plus d’informations, consultez Directive d’Assembly T4.For more information, see T4 Assembly Directive.

Espaces de nomsNamespaces

La directive import est identique à la clause using en C# ou à la clause imports en Visual Basic.The import directive is the same as the using clause in C# or the imports clause in Visual Basic. Elle vous permet de faire référence à des types dans votre code sans utiliser de nom qualifié complet :It allows you to refer to types in your code without using a fully qualified name:

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

Vous pouvez utiliser autant de directives assembly et import que vous le souhaitez.You can use as many assembly and import directives as you want. Vous devez les placer avant les blocs de contrôle et de texte.You must place them before text and control blocks.

Pour plus d’informations, consultez Directive d’importation T4.For more information, see T4 Import Directive.

Y compris le code et le texteIncluding code and text

La directive include insère du texte à partir d'un autre fichier de modèle.The include directive inserts text from another template file. Par exemple, cette directive insère le contenu de test.txt.For example, this directive inserts the content of test.txt.

<#@ include file="c:\test.txt" #>

Le contenu inclus est traité presque comme s'il faisait partie du modèle de texte d'inclusion.The included content is processed almost as if it were part of the including text template. Toutefois, vous pouvez inclure un fichier qui contient un bloc de fonctionnalité de classe <#+...#> même si la directive include est suivie de texte ordinaire et de blocs de contrôle standard.However, you can include a file that contains a class feature block <#+...#> even if the include directive is followed by ordinary text and standard control blocks.

Pour plus d’informations, consultez Directive Include de T4.For more information, see T4 Include Directive.

Méthodes utilitairesUtility methods

Il existe plusieurs méthodes telles que Write() qui sont toujours disponibles dans un bloc de contrôle.There are several methods such as Write() that are always available to you in a control block. Il s'agit notamment de méthodes destinées à vous aider à mettre en retrait la sortie et à signaler les erreurs.They include methods for helping you indent the output, and for reporting errors.

Vous pouvez aussi écrire votre propre jeu de méthodes utilitaires.You can also write your own set of utility methods.

Pour plus d’informations, consultez méthodes utilitaires de modèle de texte.For more information, see Text Template Utility Methods.

Transformation de données et de modèlesTransforming Data and Models

L'application la plus utile pour un modèle de texte consiste à générer une sortie basée sur le contenu d'une source telle qu'un modèle, une base de données ou un fichier de données.The most useful application for a text template is to generate material based on the content of a source such as a model, database, or data file. Votre modèle extrait et modifie la mise en forme des données.Your template extracts and reformats the data. Une collection de modèles peut transformer une telle source en plusieurs fichiers.A collection of templates can transform such a source into multiple files.

Il existe plusieurs approches pour la lecture du fichier source.There are several approaches to reading the source file.

Lire un fichier dans le modèle de texte.Read a file in the text template. C'est le moyen le plus simple d'insérer des données dans le modèle :This is simplest way to get data into the template:

<#@ import namespace="System.IO" #>
<# string fileContent = File.ReadAllText(@"C:\myData.txt"); ...

Charger un fichier en tant que modèle navigable.Load a file as a navigable model. Une méthode plus puissante consiste à lire les données en tant que modèle navigable par votre code de modèle de texte.A more powerful method is to read the data as a model, which your text template code can navigate. Par exemple, vous pouvez charger un fichier XML et le parcourir avec des expressions XPath.For example, you can load an XML file and navigate it with XPath expressions. Vous pouvez également utiliser xsd.exe pour créer un ensemble de classes vous pouvez de lire les données XML.You could also use xsd.exe to create a set of classes with which you can read the XML data.

Modifiez le fichier de modèle dans un diagramme ou d’un formulaire.Edit the model file in a diagram or form. --- --- Outils DSL (langage spécifique à un domaine)Domain-Specific Language Tools Fournit des outils qui vous permettent de modifier un modèle comme un diagramme ou un Windows form. provides tools that let you edit a model as a diagram or Windows form. Il est ainsi plus facile de discuter du modèle avec les utilisateurs de l'application générée.This makes it easier to discuss the model with users of the generated application. --- --- Outils DSL (langage spécifique à un domaine)Domain-Specific Language Tools crée également un ensemble de classes fortement typées qui reflètent la structure du modèle. also creates a set of strongly-typed classes that reflect the structure of the model. Pour plus d’informations, consultez génération du Code à partir d’un langage spécifique à un domaine.For more information, see Generating Code from a Domain-Specific Language.

Chemins d’accès de fichiers relatifs dans les modèles au moment de la conceptionRelative file paths in design-time templates

Dans un modèle de texte au moment du design, si vous souhaitez faire référence à un fichier dans un emplacement relatif au modèle de texte, utilisez this.Host.ResolvePath().In a design-time text template, if you want to reference a file in a location relative to the text template, use this.Host.ResolvePath(). Vous devez aussi définir hostspecific="true" dans la directive template :You must also set hostspecific="true" in the template directive:

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ import namespace="System.IO" #>
<#
 // Find a path within the same project as the text template:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of MyFile.txt is:
<#= myFile #>

Vous pouvez également obtenir d'autres services fournis par l'hôte.You can also obtain other services that are provided by the host. Pour plus d’informations, consultez l’accès à Visual Studio ou autres hôtes à partir d’un modèle.For more information, see Accessing Visual Studio or other Hosts from a Template.

Modèles de texte au moment du design exécutés dans un AppDomain distinctDesign-time Text Templates run in a separate AppDomain

Vous devez être conscient qu’un modèle de texte au moment du design s’exécute dans un AppDomain qui est distinct de l’application principale.You should be aware that a design-time text template runs in an AppDomain that is separate from the main application. Dans la plupart des cas cela n'est pas important, mais dans certains cas complexes certaines restrictions peuvent s'appliquer.In most cases this is not important, but you might discover restrictions in certain complex cases. Par exemple, si vous souhaitez passer des données dans le modèle ou en dehors de celui-ci à partir d'un service distinct, ce service doit fournir une API sérialisable.For example, if you want to pass data in or out of the template from a separate service, then the service must provide a serializable API.

(Cela n’est pas vrai un modèle de texte au moment de l’exécution, qui fournit du code est compilé avec le reste de votre code.)(This isn't true of a run-time text template, which provides code that is compiled along with the rest of your code.)

Modification de modèlesEditing Templates

Vous pouvez télécharger des éditeurs de modèle de texte spécialisés à partir de la galerie en ligne du Gestionnaire d’extensions.Specialized text template editors can be downloaded from the Extension Manager Online Gallery. Sur le outils menu, cliquez sur Gestionnaire d’extensions.On the Tools menu, click Extension Manager. Cliquez sur galerie en ligne, puis utilisez l’outil de recherche.Click Online Gallery, and then use the search tool.

TâcheTask RubriqueTopic
Écrire un modèle.Writing a template. Instructions relatives à l’écriture de modèles de texte T4Guidelines for Writing T4 Text Templates
Générer du texte à l'aide de code de programme.Generate text by using program code. Structure de modèle de texteText Template Structure
Générer des fichiers dans une solution Visual StudioVisual Studio.Generate files in a Visual StudioVisual Studio solution. Génération de code au moment du design à l’aide de modèles de texte T4Design-Time Code Generation by using T4 Text Templates
Exécuter la génération de texte en dehors de Visual StudioVisual Studio.Run text generation outside Visual StudioVisual Studio. Génération de fichiers avec l’utilitaire TextTransformGenerating Files with the TextTransform Utility
Transformer vos données sous la forme d’un langage spécifique à un domaine.Transform your data in the form of a domain-specific language. Génération de code à partir d’un langage spécifique à un domaineGenerating Code from a Domain-Specific Language
Écrire des processeurs de directive pour transformer vos propres sources de données.Write directive processors to transform your own data sources. Personnalisation d’une transformation de texte T4Customizing T4 Text Transformation