Comment : écrire avec des modèles de texte

2025-06-12

Les modèles de texte dans Visual Studio offrent un moyen utile de générer du texte de n’importe quel type. Vous pouvez utiliser des modèles de texte pour générer du texte au moment de l’exécution dans le cadre de votre application et au moment du design pour générer du code pour votre projet. Cette rubrique récapitule les questions pratiques les plus fréquemment posées.

Dans cette rubrique, plusieurs réponses précédées de puces sont des suggestions alternatives.

Pour une présentation générale des modèles de texte, consultez Génération de code et Modèles de texte T4.

Comment...

Générer une partie de mon code d’application

J’ai une configuration ou un modèle dans un fichier ou une base de données. Une ou plusieurs parties de mon code dépendent de ce modèle.

Générez certains de vos fichiers de code à partir de modèles de texte. Pour plus d’informations, consultez Génération de code au moment de la conception à l’aide de modèles de texte T4 et Quelle est la meilleure façon de commencer à écrire un modèle ?.

Générer des fichiers au moment de l’exécution, en passant des données dans le modèle

Au moment de l’exécution, mon application génère des fichiers texte, tels que des rapports, qui contiennent un mélange de texte et de données standard. Je veux éviter d’écrire des centaines d’instructions write.

Ajoutez un modèle de texte d’exécution à votre projet. Ce modèle crée une classe dans votre code, que vous pouvez instancier et utiliser pour générer du texte. Vous pouvez lui transmettre des données dans les paramètres du constructeur. Pour plus d’informations, consultez Génération de texte à l’exécution à l’aide des modèles de texte T4.
Si vous souhaitez générer à partir de modèles disponibles uniquement au moment de l’exécution, vous pouvez utiliser des modèles de texte standard. Si vous écrivez une extension Visual Studio, vous pouvez appeler le service de création de modèles de texte. Pour plus d’informations, consultez Appel d’une transformation de texte dans une extension VS. Dans d’autres contextes, vous pouvez utiliser le moteur de création de modèles de texte. Pour plus d’informations, consultez Microsoft.VisualStudio.TextTemplating.Engine.

Utilisez la directive <#@parameter#> pour transmettre des paramètres à ces modèles. Pour plus d’informations, consultez Directive de paramètre T4.

Lire un autre fichier projet à partir d’un modèle

Pour lire un fichier à partir du même projet Visual Studio que le modèle :

Insérez hostSpecific="true" dans la directive <#@template#>.

Dans votre code, utilisez this.Host.ResolvePath(filename) pour obtenir le chemin d’accès complet du fichier.

Appeler des méthodes à partir d’un modèle

Si les méthodes existent déjà, par exemple, dans les classes .NET :

Utilisez la directive <#@assembly#> pour charger l’assembly et utilisez <#@import#> pour définir le contexte d’espace de noms. Pour plus d’informations, consultez Directive d’importation T4.

Si vous utilisez fréquemment le même ensemble de directives d’assembly et d’importation, envisagez d’écrire un processeur de directive. Dans chaque modèle, vous pouvez appeler le processeur de directive, qui peut charger les assemblys et les fichiers de modèle et définir le contexte d’espace de noms. Pour plus d’informations, consultez Création de processeurs de directive de modèle de texte T4 personnalisés.

Si vous écrivez vous-même les méthodes :

Si vous écrivez un modèle de texte d’exécution, écrivez une définition de classe partielle portant le même nom que votre modèle de texte d’exécution. Ajoutez les méthodes supplémentaires dans cette classe.
Écrivez un bloc de contrôle de fonctionnalité de classe <#+ ... #> dans lequel vous pouvez déclarer des méthodes, des propriétés et des classes privées. Lorsque le modèle de texte est compilé, il est transformé en classe. Les blocs de contrôle standard <#...#> et le texte sont transformés en une seule méthode, et les blocs de fonctionnalité de classe sont insérés en tant que membres distincts. Pour plus d’informations, consultez Blocs de contrôle de modèle de texte.

Les méthodes définies en tant que fonctionnalités de classe peuvent également inclure des blocs de texte incorporés.

Envisagez de placer des fonctionnalités de classe dans un fichier distinct que vous pouvez <#@include#> dans un ou plusieurs fichiers de modèle.
Écrivez les méthodes dans un assembly distinct (bibliothèque de classes) et appelez-les à partir de votre modèle. Utilisez la directive <#@assembly#> pour charger l’assembly et <#@import#> pour définir le contexte d’espace de noms. Notez que pour reconstruire l’assembly pendant le débogage, vous devrez peut-être arrêter et redémarrer Visual Studio. Pour plus d’informations, consultez Directives de modèle de texte T4.

Générer de nombreux fichiers à partir d’un schéma de modèle

Si vous générez souvent des fichiers à partir de modèles qui ont le même schéma XML ou de base de données :

Envisagez d’écrire un processeur de directive. Cela vous permet de remplacer plusieurs instructions d’assembly et d’importer des instructions dans chaque modèle avec une directive personnalisée unique. Le processeur de directive peut également charger et analyser le fichier de modèle. Pour plus d’informations, consultez Création de processeurs de directive de modèle de texte T4 personnalisés.

Générer des fichiers à partir d’un modèle complexe

Envisagez de créer un langage spécifique à un domaine (DSL) pour représenter le modèle. Cela facilite considérablement l’écriture des modèles, car vous utilisez des types et des propriétés qui reflètent les noms des éléments de votre modèle. Vous n’avez pas besoin d’analyser le fichier ou de parcourir les nœuds XML. Par exemple :

foreach (Book book in this.Library) { ... }

Pour plus d’informations, consultez Prise en main du langage spécifique à un domaine et Génération de code à partir d’un langage spécifique à un domaine.

Obtenir des données à partir de Visual Studio

Pour utiliser des services fournis dans Visual Studio, définissez l'attribut hostSpecific et chargez l'assembly EnvDTE. Par exemple :

<#@ template hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ assembly name="EnvDTE" #>
<#
  IServiceProvider serviceProvider = (IServiceProvider)this.Host;
  EnvDTE.DTE dte = (EnvDTE.DTE) serviceProvider.GetService(typeof(EnvDTE.DTE));
#>

Number of projects in this VS solution:  <#= dte.Solution.Projects.Count #>

Exécuter des modèles de texte dans le processus de génération

Pour plus d'informations, consultez Génération de code dans un processus de génération.

Questions plus générales

Quelle est la meilleure façon de commencer à écrire un modèle de texte ?

Écrivez un exemple spécifique du fichier généré.
Transformez-le en modèle de texte en insérant la directive <#@template #>, ainsi que les directives et le code requis pour charger le fichier d’entrée ou le modèle.
Remplacez progressivement les parties du fichier par des blocs d’expression et de code.

Qu’est un « modèle » ?

C’est l’entrée lue par votre modèle. Il peut s’agir d’un fichier ou d’une base de données. Il peut s’agir d’un XML, d’un dessin Visio, d’un langage spécifique à un domaine (DSL), d’un modèle UML, ou d’un texte brut. Il peut être réparti sur plusieurs fichiers. En règle générale, plusieurs modèle lisent un modèle.

L’implication du terme « modèle » est qu’il représente un aspect de votre entreprise plus directement que le code du programme généré ou d’autres fichiers. Par exemple, il peut représenter le plan d’un réseau de communications supervisé par votre logiciel généré.

Quel est l’avantage d’utiliser des modèles de texte ?

En règle générale, vous générez plusieurs fichiers de code ou d’autres fichiers à partir d’un modèle. Le modèle représente les exigences plus directement que le code généré. Il omet les détails de l’implémentation et est écrit selon les exigences, plutôt que le code. Lorsque les exigences changent, ce qui est généralement le cas, vous pouvez mettre à jour le modèle plus facilement et plus fiablement que les différentes parties du code du programme.

La génération de code est donc un outil précieux du point de vue des méthodes de développement agiles.

Quelles sont les « meilleures pratiques » pour les modèles de texte ?

Pour plus d’informations, consultez Recommandations pour l’écriture de modèles de texte T4.

Qu’est-ce que « T4 » ?

Un autre nom pour les fonctionnalités de modèle de texte Visual Studio décrites ici. La version précédente, qui n’a pas été publiée, était une abréviation de « Transformation de modèle de texte ».