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"] [visibility="internal"] [linePragmas="false"] #>

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.False représente la valeur par défaut.

Si l'attribut d' debug est 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ù un arrêt ou une exception s'est produite.

Pour les modèles au moment du design, le fichier de code intermédiaire est écrit dans votre répertoire %TEMP%.

Pour exécuter un modèle au moment de le design dans le débogueur, ouvrez le menu contextuel de l'explorateur de modèles de texte de solutions, puis sélectionnez Déboguez le modèle T4.

attribut hostspecific

• Exemple :

  hostspecific="true"
  

• Valeurs valides :
  true, false, trueFromBase.False représente la valeur par défaut.

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).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 d' inherits et d' hostspecific ensemble, spécifiez le host= " trueFromBase » dans la classe dérivée et le host= " true » dans la classe de base.Cela évite une double définition de la propriété d' Host dans le code généré.

attribut de langage

• Exemple :
  language="VB"

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

  VB

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 des modèles de texte T4.

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.

Attention
Si vous utilisez les attributs d' inherits et d' hostspecific ensemble, spécifiez le hostspecific= " trueFromBase » dans la classe et le host= dérivés " true » dans la classe de base.Cela évite une double définition de la propriété d' Host dans le code généré.

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.

Attribut de LinePragmas

• Exemple :
  linePragmas="false"

• Valeurs valides :
  true (par défaut)

  false

La définition de cet attribut la valeur false supprime les balises qui identifient les numéros de ligne dans le code généré.Cela signifie que le compilateur signale toutes les erreurs à l'aide de les numéros de ligne du code généré. Cela vous donne davantage d'options de débogage, comme vous pouvez choisir de déboguer le modèle de texte ou le code généré.

Cet attribut peut également vous aider si vous recherchez les noms du fichier absolus dans les pragmas génèrent distrayant des fusions sous contrôle de code source.

Attribut de visibilité

• Exemple :
  visibility="internal"

• Valeurs valides :
  public (par défaut)

  internal

Dans un modèle de texte au moment de l'exécution, cela définit l'attribut de visibilité de la classe générée.Par défaut, la classe fait partie de l'API publiques de votre code, mais en définissant visibility="internal" vous pouvez vous assurer que votre code peut utiliser la classe génératrice texte.