Directive du modèle T4T4 Template Directive

Un modèle de texte Visual Studio T4 commence généralement par un template directive, qui spécifie comment le modèle doit être traité.A Visual Studio T4 text template usually starts with a template directive, which specifies how the template should be processed. Il ne doit y avoir qu'une seule directive de modèle dans un modèle de texte et les fichiers qu'il contient.There should be no more than one template directive in a text template and any files that it includes.

Pour obtenir une vue d’ensemble de l’écriture de modèles de texte, consultez écriture d’un modèle de texte T4.For a general overview of writing text templates, see Writing a T4 Text Template.

Utilisation de la directive du modèleUsing the Template Directive

<#@ template [language="VB"] [compilerOptions="options"] [culture="code"] [debug="true"] [hostspecific="true"] [inherits="templateBaseClass"] [visibility="internal"] [linePragmas="false"] #>

La directive template comporte plusieurs attributs qui vous permettent de spécifier différents aspects de la transformation.The template directive has several attributes that allow you to specify different aspects of the transformation. Tous les attributs sont facultatifs.All the attributes are optional.

attribut compilerOptionscompilerOptions attribute

Exemple : compilerOptions="optimize+"Example: compilerOptions="optimize+"

Valeurs valides : toutes les options du compilateur valide.Valid values: Any valid compiler options.

Ignoré pour les modèles au moment de l'exécution (prétraités).Ignored for run-time (preprocessed) templates.

Ces options sont appliquées lorsque le modèle a été converti en Visual C#Visual C# ou Visual BasicVisual Basic, et que le code résultant est compilé.These options are applied when the template has been converted into Visual C#Visual C# or Visual BasicVisual Basic, and the resulting code is compiled.

attribut de cultureculture attribute

Exemple : culture="de-CH"Example: culture="de-CH"

Valeurs valides : « », la culture dite indifférente, qui est la valeur par défaut.Valid values: "", the invariant culture, which is the default.

Culture exprimée sous la forme d'une chaîne au format xx-XX.A culture expressed as a string in the form xx-XX. Par exemple, en-US, ja-JP, de-CH, de-DE.For example, en-US, ja-JP, de-CH, de-DE. Pour plus d'informations, consultez System.Globalization.CultureInfo.For more information, see System.Globalization.CultureInfo.

L'attribut de culture spécifie la culture à utiliser lorsqu'un bloc d'expression est converti en texte.The culture attribute specifies the culture to use when an expression block is converted to text.

attribut de débogagedebug attribute

Exemple :Example:

debug="true"

Valeurs valides : true, false.Valid values: true, false. False représente la valeur par défaut.False is the default.

Si l'attribut debug a la valeur true, le fichier de code intermédiaire contient des informations qui permettent au débogueur d'identifier plus précisément la position, dans votre modèle, où s'est produit un arrêt ou une exception.If the debug attribute is true, the intermediate code file will contain information that enables the debugger to identify more accurately the position in your template where a break or exception occurred.

Pour les modèles au moment du design le fichier de code intermédiaire sera écrit pour votre %temp% directory.For design-time templates the intermediate code file will be written to your %TEMP% directory.

Pour exécuter un modèle au moment du design dans le débogueur, enregistrez le modèle de texte, puis ouvrez le menu contextuel du modèle de texte dans l’Explorateur de solutions et choisissez déboguer le modèle T4.To run a design-time template in the debugger, save the text template, then open the shortcut menu of the text template in Solution Explorer, and choose Debug T4 Template.

attribut hostspecifichostspecific attribute

Exemple :Example:

hostspecific="true"

Valeurs valides : true, false, trueFromBase.Valid values: true, false, trueFromBase. False représente la valeur par défaut.False is the default.

Si vous affectez à cet attribut la valeur true, une propriété nommée Host est ajoutée à la classe générée par votre modèle de texte.If you set the value of this attribute to true, a property named Host is added to the class generated by your text template. La propriété est une référence à l'hôte du moteur de transformation, et est déclarée comme ITextTemplatingEngineHost.The property is a reference to the host of the transformation engine, and is declared as ITextTemplatingEngineHost. Si vous avez défini un hôte personnalisé, vous pouvez effectuer un cast de celui-ci en type d'hôte personnalisé.If you have defined a custom host, you can cast it to the custom host type.

Étant donné que le type de cette propriété dépend du type d'hôte, elle n'est utile que si vous écrivez un modèle de texte qui fonctionne uniquement avec un hôte spécifique.Because the type of this property depends on the type of host, it is only useful if you are writing a text template that works only with a specific host. Il s’applique aux les modèles au moment du design, mais pas modèles au moment de l’exécution.It's applicable to design-time templates, but not run-time templates.

Lorsque hostspecific est true et que vous utilisez Visual Studio, vous pouvez effectuer un cast this.Host en IServiceProvider pour accéder aux fonctionnalités de Visual Studio.When hostspecific is true and you are using Visual Studio, you can cast this.Host to IServiceProvider to access Visual Studio features. Vous pouvez également utiliser Host.ResolvePath(filename) pour obtenir le chemin d'accès absolu d'un fichier dans le projet.You can also use Host.ResolvePath(filename) to obtain the absolute path of a file in the project. Exemple :For example:

<#@ template debug="false" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#@ import namespace="EnvDTE" #>
<#@ import namespace="System.IO" #>
<# // Get the Visual Studio API as a service:
 DTE dte = ((IServiceProvider)this.Host).GetCOMService(typeof(DTE)) as DTE;
#>
Number of projects in this solution: <#=  dte.Solution.Projects.Count #>

<#
 // Find a path within the current project:
 string myFile = File.ReadAllText(this.Host.ResolvePath("MyFile.txt"));
#>
Content of myFile is:
<#= myFile #>

Si vous utilisez les attributs inherits et hostspecific ensemble, spécifiez host="trueFromBase" dans la classe dérivée et host="true" dans la classe de base.If you use the inherits and hostspecific attributes together, specify host="trueFromBase" in the derived class and host="true" in the base class. Cela évite une double définition de la propriété Host dans le code généré.This avoids a double definition of the Host property in the generated code.

attribut de langagelanguage attribute

Exemple : language="VB"Example: language="VB"

Valeurs valides : C# (valeur par défaut)Valid values: C# (default)

VB

L’attribut de langage spécifie le langage (Visual BasicVisual Basic ou Visual C#Visual C#) à utiliser pour le code source dans les blocs d’instruction et une expression.The language attribute specifies the language (Visual BasicVisual Basic or Visual C#Visual C#) to use for the source code in statement and expression blocks. Le fichier de code intermédiaire à partir duquel la sortie est générée utilisera ce langage.The intermediate code file from which the output is generated will use this language. Ce langage n'est pas lié au langage que votre modèle génère, qui peut être tout type de texte.This language is not related to the language that your template generates, which can be any kind of text.

Exemple :For example:

<#@ template language="VB" #>
<#@ output extension=".txt" #>
Squares of numbers:
<#
  Dim number As Integer
  For number = 1 To 4
#>
  Square of <#= number #> is <#= number * number #>
<#
  Next number
#>

attribut Inheritsinherits attribute

Vous pouvez spécifier que le code du programme de votre modèle peut hériter d'une autre classe, qui peut également être générée à partir d'un modèle de texte.You can specify that the program code of your template can inherit from another class, which can also be generated from a text template.

Héritage dans un modèle de texte au moment de l'exécution (prétraité)Inheritance in a run-time (preprocessed) text template

Vous pouvez utiliser l'héritage entre les modèles de texte au moment de l'exécution pour créer un modèle de base avec plusieurs variantes dérivées.You can use inheritance between run-time text templates to create a basic template that has several derived variants. Modèles d’exécution sont celles qui ont le un outil personnalisé propriété définie sur TextTemplatingFilePreprocessor.Run-time templates are those that have the Custom Tool property set to TextTemplatingFilePreprocessor. Un modèle au moment de l'exécution génère du code que vous pouvez appeler dans votre application pour créer le texte défini dans le modèle.A run-time template generates code that you can call in your application to create the text defined in the template. Pour plus d’informations, consultez génération de texte d’exécution avec les modèles de texte T4.For more information, see Run-Time Text Generation with T4 Text Templates.

Si vous ne spécifiez pas d'attribut inherits, une classe de base et une classe dérivée sont générées à partir de votre modèle de texte.If you do not specify an inherits attribute, a base class and a derived class are generated from your text template. Lorsque vous spécifiez un attribut inherits, seule la classe dérivée est générée.When you specify an inherits attribute, only the derived class is generated. Vous pouvez écrire une classe de base manuellement, mais elle doit fournir les méthodes utilisées par la classe dérivée.You can write a base class by hand, but it must provide the methods that are used by the derived class.

Plus généralement, vous spécifiez un autre modèle prétraité comme classe de base.More typically, you specify another preprocessed template as the base class. Le modèle de base fournit des blocs de texte communs, qui peuvent être entrelacés avec du texte des modèles dérivés.The base template provides common blocks of text, which can be interleaved with text from the derived templates. Vous pouvez utiliser des blocs de fonctionnalité de classe <#+ ... #> pour définir des méthodes qui contiennent des fragments de texte.You can use class feature blocks <#+ ... #> to define methods that contain text fragments. Par exemple, vous pouvez placer l'infrastructure du texte de sortie dans le modèle de base, en fournissant des méthodes virtuelles qui peuvent être substituées dans les modèles dérivés :For example, you can place the framework of the output text in the base template, providing virtual methods that can be overridden in derived templates:

Modèle de texte au moment de l'exécution (prétraité) BaseTemplate.tt :Run-time (preprocessed) text template BaseTemplate.tt:

This is the common header.
<#
 SpecificFragment1();
#>
A common central text.
<#
 SpecificFragment2();
#>
This is the common footer.
<#+
 // Declare abstract methods
 protected virtual void SpecificFragment1() { }
 protected virtual void SpecificFragment2() { }
#>

Modèle de texte au moment de l'exécution (prétraité) DerivedTemplate1.tt :Run-time (preprocessed) text template DerivedTemplate1.tt:

<#@ template language="C#" inherits="BaseTemplate" #>
<#
 // Run the base template:
 base.TransformText();
#>
<#+
// Provide fragments specific to this derived template:
protected override void SpecificFragment1()
{
#>
  Fragment 1 for DerivedTemplate1
<#+
}
protected override void SpecificFragment2()
{
#>
  Fragment 2 for DerivedTemplate1
<#+
}
#>

Code d'application pour appeler DerivedTemplate1 :Application code to invoke DerivedTemplate1:

Console.WriteLine(new DerivedTemplate().TransformText());

Résultat :Resulting output:

This is the common header.
  Fragment 1 for DerivedTemplate1
A common central text.
  Fragment 2 for DerivedTemplate1
This is the common footer.

Vous pouvez générer les classes de base et les classes dérivées dans des projets différents.You can build the base and derived classes in different projects. Pensez à ajouter l’assembly ou le projet de base pour les références du projet dérivé.Remember to add the base project or assembly to the derived project's references.

Vous pouvez également utiliser une classe écrite manuellement ordinaire comme classe de base.You can also use an ordinary hand-written class as the base class. La classe de base doit fournir les méthodes utilisées par la classe dérivée.The base class must provide the methods used by the derived class.

Warning

Si vous utilisez les attributs inherits et hostspecific ensemble, spécifiez hostspecific="trueFromBase" dans la classe dérivée et host="true" dans la classe de base.If you use the inherits and hostspecific attributes together, specify hostspecific="trueFromBase" in the derived class and host="true" in the base class. Cela évite une double définition de la propriété Host dans le code généré.This avoids a double definition of the Host property in the generated code.

Héritage dans un modèle de texte au moment du designInheritance in a design-time text template

Un modèle de texte au moment du design est un fichier pour lequel un outil personnalisé a la valeur TextTemplatingFileGenerator.A design-time text template is a file for which Custom Tool is set to TextTemplatingFileGenerator. Le modèle génère un fichier de sortie de code ou de texte, ce qui constitue une partie de votre projet Visual Studio.The template generates an output file of code or text, which forms part of your Visual Studio project. Pour générer le fichier de sortie, le modèle est d'abord traduit en fichier de code du programme intermédiaire, que vous ne voyez normalement pas.To generate the output file, the template is first translated into an intermediate program code file, which you do not usually see. L'attribut inherits spécifie la classe de base pour ce code intermédiaire.The inherits attribute specifies the base class for this intermediate code.

Pour un modèle de texte au moment du design, vous pouvez spécifier toute classe de base dérivée de Microsoft.VisualStudio.TextTemplating.TextTransformation.For a design-time text template, you can specify any base class that is derived from Microsoft.VisualStudio.TextTemplating.TextTransformation. Utilisez la directive <#@assembly#> pour charger l'assembly ou le projet qui contient la classe de base.Use the <#@assembly#> directive to load the assembly or project that contains the base class.

Pour plus d’informations, consultez « L’héritage dans modèles de texte » dans le Blog de Gareth Jones.For more information, see "Inheritance in Text Templates" in Gareth Jones' Blog.

Attribut LinePragmasLinePragmas attribute

Exemple : linePragmas="false"Example: linePragmas="false"

Valeurs valides : true (valeur par défaut)Valid values: true (default)

false

L’assignation de la valeur false à cet attribut permet de supprimer les étiquettes qui identifient les numéros de ligne dans le code généré.Setting this attribute to false removes the tags that identify your line numbers within the generated code. Cela signifie que le compilateur signale toutes les erreurs en utilisant les numéros de ligne du code généré. Cela vous donne davantage d'options de débogage, car vous pouvez choisir de déboguer le modèle de texte ou le code généré.This means that the compiler will report any errors by using line numbers of the generated code.This gives you more debugging options, as you can choose to debug either the text template or the generated code.

Cet attribut peut également utile si vous ne trouvez que les noms de fichiers absolus dans les pragmas sont à l’origine des fusions perturbante sous contrôle de code source.This attribute can also help if you're finding the absolute filenames in pragmas are causing distracting merges under source code control.

Attribut VisibilityVisibility attribute

Exemple : visibility="internal"Example: visibility="internal"

Valeurs valides : public (valeur par défaut)Valid values: public (default)

internal

Dans un modèle de texte au moment de l'exécution, vous définissez l'attribut de visibilité de la classe générée.In a runtime text template, this sets the visibility attribute of the generated class. Par défaut, la classe fait partie de l'API publique de votre code, mais en définissant visibility="internal", vous pouvez vous assurer que votre code est en mesure d'utiliser la classe de génération de texte.By default, the class is part of the public API of your code, but by setting visibility="internal" you can make sure that only your code can use the text-generating class.