Directive du modèle T4

En général, un modèle de texte T4 Visual Studio commence par une directive template, qui spécifie comment le modèle doit être traité. Il ne doit y avoir qu'une seule directive de modèle dans un modèle de texte et les fichiers qu'il contient.

Pour une vue d'ensemble de l'écriture de modèles de texte, consultez Écriture d'un modèle de texte T4.

Utilisation de la directive du modèle

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

La directive template comporte plusieurs attributs qui vous permettent de spécifier différents aspects de la transformation. Tous les attributs sont facultatifs.

attribut compilerOptions

• Exemple :
  compilerOptions="optimize+"

• Valeurs valides :
  Toutes les options du compilateur valides. Pour plus d'informations, consultez Options du compilateur C# par catégorie et Options du compilateur Visual Basic par catégorie.

  Ignoré pour les modèles au moment de l'exécution (prétraités).

Ces options sont appliquées lorsque le modèle a été converti en Visual C# ou Visual Basic, et que le code résultant est compilé.

attribut de culture

• Exemple :
  culture="de-CH"

• Valeurs valides :
  "", la culture dite indifférente, qui est la valeur par défaut.

  Culture exprimée sous la forme d'une chaîne au format xx-XX. Par exemple, en-US, ja-JP, de-CH, de-DE. Pour plus d'informations, consultez System.Globalization.CultureInfo.

L'attribut de culture spécifie la culture à utiliser lorsqu'un bloc d'expression est converti en texte.

attribut de débogage

• Exemple :

  debug="true"
  

• Valeurs valides :
  true, false. La valeur par défaut est false.

L'attribut de debug spécifie si le débogage est activé. Si la valeur est true, le fichier de code intermédiaire contient des informations qui permettent au débogueur d'identifier la position, dans votre modèle, où un arrêt ou une exception s'est produit. Pour les modèles au moment du design, le fichier de code intermédiaire est écrit dans votre répertoire %TEMP%.

Pour lancer le débogueur à un point spécifique de l'exécution d'un modèle, insérez un appel à Launch. Pour arrêter l'exécution à des points suivants, insérez un appel à Break. Par exemple :

<#@ template debug="true" language="C#" #>
<#@ output extension=".txt" #>
Output something.
<# 
 // Break here:
 System.Diagnostics.Debugger.Launch();  
#>
Output more.
<#
 // Break here also:
 System.Diagnostics.Debugger.Break();  
#>
Output more.

Pour plus d'informations, consultez Procédure pas à pas : débogage d'un modèle de texte.

attribut hostspecific

• Exemple :

  hostspecific="true"
  

• Valeurs valides :
  true, false. La valeur par défaut est false.

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. La propriété est une référence à l'hôte du moteur de transformation, et est déclarée comme Microsoft.VisualStudio.TextTemplating.ITextTemplatingEngineHost. Si vous avez défini un hôte personnalisé, vous pouvez effectuer un cast de celui-ci en type d'hôte personnalisé.

É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.

Lorsque hostspecific a la valeur true et que vous utilisez Visual Studio, vous pouvez effectuer un cast de this.Host en IServiceProvider pour accéder aux fonctionnalités de Visual Studio. Vous pouvez également utiliser Host.ResolvePath(filename) pour obtenir le chemin d'accès absolu d'un fichier dans le projet. Par exemple :

<#@ 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).GetService(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 #>

attribut de langage

• Exemple :
  language="VB"

• Valeurs valides :
  C# (par défaut)

  VB

  (Les valeurs VBv3.5 et C#v3.5 sont obsolètes dans cette version finale, mais seront interprétées comme VB et C#.)

L'attribut de langage spécifie le langage (Visual Basic ou Visual C#) à utiliser pour le code source dans les blocs d'instruction et d'expression. Le fichier de code intermédiaire à partir duquel la sortie est générée utilisera ce langage. Ce langage n'est pas lié au langage que votre modèle génère, qui peut être tout type de texte.

Par exemple :

<#@ 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 Inherits

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.

Héritage dans un modèle de texte au moment de l'exécution (prétraité)

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. Pour les modèles au moment de l'exécution, la propriété Outil personnalisé a la valeur 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. Pour plus d'informations, consultez Génération de texte durant l'exécution à l'aide de modèles de texte T4 prétraités.

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. Lorsque vous spécifiez un attribut inherits, seule la classe dérivée est générée. Vous pouvez écrire une classe de base manuellement, mais elle doit fournir les méthodes utilisées par la classe dérivée.

Plus généralement, vous spécifiez un autre modèle prétraité comme classe de base. 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. Vous pouvez utiliser des blocs de fonctionnalité de classe <#+ ... #> pour définir des méthodes qui contiennent des fragments de texte. 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 :

• Modèle de texte au moment de l'exécution (prétraité) 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 :

  <#@ 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 :

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

• Résultat :

  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. Pensez à ajouter l'assembly ou le projet de base aux références du projet dérivé.

Vous pouvez également utiliser une classe écrite manuellement ordinaire comme classe de base. La classe de base doit fournir les méthodes utilisées par la classe dérivée.

Héritage dans un modèle de texte au moment du design

Un modèle de texte au moment du design est un fichier pour lequel Outil personnalisé a la valeur TextTemplatingFileGenerator. Le modèle génère un fichier de sortie de code ou de texte, qui fait partie de votre projet Visual Studio. 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. L'attribut inherits spécifie la classe de base pour ce code intermédiaire.

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. Utilisez la directive <#@assembly#> pour charger l'assembly ou le projet qui contient la classe de base.

Pour plus d'informations, consultez "Inheritance in Text Templates" sur le blog de Gareth Jones.

Historique des modifications

Date	Historique	Motif
Mars 2011	Fractionnement de rubrique parent. Ajoutez compilerOptions. Ajoutez le lien à l'entrée du blog de l'héritage du modèle de texte.	Améliorations apportées aux informations.