Créer des processeurs de directives de modèles de texte T4 personnalisés

Le processus de transformation de modèle de texte prend un fichier de modèle de texte comme entrée et produit un fichier texte comme sortie. Le moteur de transformation de modèle de texte contrôle le processus, et le moteur interagit avec un hôte de transformation de modèle de texte et un ou plusieurs processeurs de directives de modèle de texte pour terminer le processus. Pour plus d’informations, consultez Processus de transformation de modèle de texte.

Pour créer un processeur de directive personnalisé, vous devez définir une classe qui hérite de DirectiveProcessor ou de RequiresProvidesDirectiveProcessor.

La différence entre ces deux éléments réside dans le fait que DirectiveProcessor implémente l’interface minimale nécessaire pour obtenir des paramètres de l’utilisateur et pour générer le code qui produit le fichier de sortie du modèle. RequiresProvidesDirectiveProcessor implémente le modèle de conception requis/fourni. RequiresProvidesDirectiveProcessor gère deux paramètres spéciaux, requires et provides. Par exemple, un processeur de directive personnalisé peut accepter un nom de fichier de l’utilisateur, ouvrir et lire le fichier, puis stocker le texte du fichier dans une variable nommée fileText. Une sous-classe de la classe RequiresProvidesDirectiveProcessor peut prendre un nom de fichier de l’utilisateur comme valeur du paramètre requires et le nom de la variable dans laquelle stocker le texte comme valeur du paramètre provides. Ce processeur ouvre et lit le fichier, puis stocke le texte du fichier dans la variable spécifiée.

Avant d’appeler un processeur de directive personnalisé à partir d’un modèle de texte dans Visual Studio, vous devez l’inscrire.

Pour plus d’informations sur l’ajout de la clé de Registre, consultez Déploiement d’un processeur de directive personnalisé.

Directives personnalisées

Une directive personnalisée ressemble à ceci :

<#@ MyDirective Processor="MyDirectiveProcessor" parameter1="value1" ... #>

Vous pouvez utiliser un processeur de directive personnalisé lorsque vous souhaitez accéder à des données ou ressources externes à partir d’un modèle de texte.

Différents modèles de texte peuvent partager les fonctionnalités fournies par un processeur de directive unique, de sorte que les processeurs de directives offrent un moyen de factoriser le code en vue d’une réutilisation. La directive intégrée include est similaire, car vous pouvez l’utiliser pour factoriser le code et le partager entre différents modèles de texte. La différence est que toutes les fonctionnalités fournies par la directive include sont fixes et n’acceptent pas de paramètres. Si vous souhaitez fournir des fonctionnalités courantes à un modèle de texte et autoriser le modèle à passer des paramètres, vous devez créer un processeur de directive personnalisé.

Voici quelques exemples de processeurs de directives personnalisées :

• Processeur de directive pour retourner des données d’une base de données qui accepte un nom d’utilisateur et un mot de passe en tant que paramètres.

• Processeur de directive pour ouvrir et lire un fichier qui accepte le nom du fichier en tant que paramètre.

Principales parties d’un processeur de directive personnalisé

Pour développer un processeur de directive, vous devez créer une classe qui hérite de DirectiveProcessor ou de RequiresProvidesDirectiveProcessor.

Les méthodes DirectiveProcessor les plus importantes que vous devez implémenter sont les suivantes.

• bool IsDirectiveSupported(string directiveName) - Retourner true si votre processeur de directive peut traiter la directive nommée.

• void ProcessDirective (string directiveName, IDictionary<string, string> arguments) - Le moteur de modèle appelle cette méthode pour chaque occurrence d’une directive dans le modèle. Votre processeur devrait enregistrer les résultats.

Après tous les appels à ProcessDirective(), le moteur de création de modèles appellera ces méthodes :

• string[] GetReferencesForProcessingRun() - Retourne les noms des assemblys requis par le code du modèle.

• string[] GetImportsForProcessingRun() - Retourne les espaces de noms qui peuvent être utilisés dans le code du modèle.

• string GetClassCodeForProcessingRun() - Retourne le code des méthodes, des propriétés et d’autres déclarations que le code du modèle peut utiliser. La méthode la plus simple consiste à générer une chaîne contenant le code C# ou Visual Basic. Pour que votre processeur de directive puisse être appelé à partir d’un modèle qui utilise n’importe quel langage CLR, vous pouvez construire les instructions en tant qu’arborescence CodeDom, puis retourner le résultat de la sérialisation de l’arborescence dans le langage utilisé par le modèle.

• Pour plus d’informations, consultez Procédure pas à pas : création d'un processeur de directive personnalisé.

Contenu connexe

• L’article Déployer un processeur de directive personnalisé explique comment inscrire un processeur de directive personnalisé.
• L’article Procédure pas à pas : création d'un processeur de directive personnalisé décrit comment créer un processeur de directive personnalisé, comment inscrire et tester le processeur de directive, et comment convertir le fichier de sortie au format HTML.