Procédure pas à pas : débogage d'un modèle de texte

Article
08/10/2011

Pour pouvoir déboguer un modèle de texte, vous devez connaître les deux étapes du processus de transformation de modèle. Différentes classes d'erreurs peuvent se produire au cours de chaque étape. Les étapes sont les suivantes :

Le moteur de transformation de modèle de texte crée une classe nommée classe de transformation générée. Pour créer la classe de transformation générée, le moteur de transformation de modèle de texte doit pouvoir analyser le modèle de texte.

Lors de cette étape, les erreurs présentes dans le modèle de texte, telles que des balises incorrectes, peuvent empêcher son analyse. Les erreurs sont signalées avec le numéro de la ligne de modèle de texte correspondante.
Le moteur compile la classe de transformation générée.

Lors de cette étape, les erreurs de code peuvent empêcher la compilation de la classe de transformation générée. La plupart des erreurs sont signalées avec le numéro de la ligne de modèle de texte correspondante. Les crochets non appariés dans le code du modèle peuvent provoquer des erreurs faisant référence à la classe transformée, qui a un nom de fichier temporaire.
La classe de transformation compilée est exécutée pour produire la sortie.

À ce stade, les erreurs ne sont pas signalées avec le numéro de ligne correspondant. Vous pouvez exécuter pas à pas le code du modèle ; toutefois, vous devez lancer le débogueur explicitement comme indiqué dans une section ultérieure.

Pour déboguer un modèle de texte, vous devez d'abord corriger les erreurs contenues dans ce dernier. Vous devez ensuite corriger les erreurs figurant dans la classe de transformation générée.

Notes

Lorsque vous transformez un modèle de texte, des erreurs provenant de l'une des trois sources suivantes peuvent survenir : le modèle de texte, la classe de transformation générée et les directives que vous appelez à partir du modèle de texte. Dans cette procédure pas à pas, vous allez déboguer des erreurs dans le modèle de texte et la classe de transformation générée. Toutefois, vous pouvez également utiliser ces procédures pour déboguer des directives personnalisées.

Cette procédure pas à pas décrit les tâches suivantes :

Débogage d'une balise de modèle de texte incorrecte
Exécution pas à pas du code du modèle

Création d'un modèle de texte

Créez un projet d'application console C# et ajoutez un modèle de texte à votre solution. Vous déboguerez ce modèle de texte lors des étapes ultérieures.

Pour créer un modèle de texte

Dans Visual Studio, créez une application console C# et nommez-la DebugTemplate.
Ajoutez un fichier modèle de texte nommé DebugTest.tt au projet DebugTemplate.
Assurez-vous que la propriété Outil personnalisé de DebugTest.tt a la valeur TextTemplatingFileGenerator.
Modifiez le fichier de façon à ce qu'il contienne uniquement la ligne suivante :
```
<#@ output extension=".txt" #> 
```
Enregistrez le fichier.

Le système transforme le modèle de texte et génère le fichier de sortie correspondant. Le nouveau fichier s'affiche dans l'Explorateur de solutions sous le fichier modèle de texte.

Débogage d'une balise de modèle de texte incorrecte

Lorsque vous écrivez des modèles de texte, une erreur de syntaxe courante consiste à utiliser une balise de début ou de fin incorrecte. Dans cette procédure, vous déboguerez une balise incorrecte.

Pour déboguer une balise de modèle de texte incorrecte

Ajoutez le code suivant au fichier DebugTest.tt :

Notes

Le code contient une erreur. Vous introduisez délibérément l'erreur pour la déboguer.
```
<# for (int i = 0; i < 3; i++) { >
Hello, World!
<# } #>
```
Enregistrez le fichier.

La fenêtre Liste d'erreurs apparaît et affiche l'erreur suivante :

Une balise de début ou de fin inattendue a été trouvée dans un bloc. Assurez-vous que vous n'avez pas mal tapé une balise de fin ou de début, et que vous n'avez pas de blocs imbriqués dans le modèle.

Dans ce cas, l'erreur présente dans le code est une balise de fin incorrecte. Le signe # est manquant dans la balise de fin.
Double-cliquez sur l'erreur dans la fenêtre Liste d'erreurs pour accéder au code.
Pour corriger le code, ajoutez le signe # à la balise de fin.
```
<# for (int i = 0; i < 3; i++) { #>
```
Enregistrez le fichier.

Le système transforme à présent le modèle de texte et génère le fichier de sortie correspondant. Aucune erreur ne s'affiche dans la fenêtre Liste d'erreurs.

Exécution pas à pas du code du modèle

Pour exécuter pas à pas le code du modèle, vous devez ajouter deux éléments au modèle :

<@#template debug="true" #>
System.Diagnostics.Debugger.Launch();

Dans la procédure suivante, vous allez déboguer un index d'élément qui n'existe pas. Cette erreur est semblable à celles des procédures précédentes. Toutefois, vous la déboguerez cette fois à l'aide du débogueur Visual Studio.

Pour effectuer le débogage à l'aide du débogueur

Créer un dossier C:\nonsense, puis enregistrez un fichier texte vide, nommé nonsense.xml, dans ce dossier.

Remplacez le code présent dans DebugTest.tt par le code suivant :

Notes

Le code contient une erreur. Vous introduisez délibérément l'erreur pour la déboguer.

<#@ output extension=".txt" #>
<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#
XmlDocument xDoc = new XmlDocument();
   xDoc.Load(@"C:\nonsense\nonsense.xml");
   XmlAttributeCollection attributes = xDoc.Attributes;
   if (attributes != null)
   {
      foreach (XmlAttribute attr in attributes)
      { #>
       <#=  attr.Name #>
   <# }
   }
   #>

Enregistrez le fichier.

La fenêtre Liste d'erreurs apparaît et affiche l'erreur suivante :

Exécution de la transformation : System.Xml.XmlException : l'élément racine manque.
Ajoutez une directive template avec le paramètre debug défini à true :
```
<#@ template debug="true" #>
```

Ajoutez une instruction System.Diagnostics.Debugger.Launch() au code du modèle de texte.

Le code se présentera comme suit :

<#@ template debug="true" #>
<#@ output extension=".txt" #>
<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#
   XmlDocument xDoc = new XmlDocument();
   System.Diagnostics.Debugger.Launch();
   xDoc.Load(@"C:\nonsense\nonsense.xml");
   XmlAttributeCollection attributes = xDoc.Attributes;
   if (attributes != null)
   { 
      foreach (XmlAttribute attr in attributes)
      { #>
       <#=  attr.Name #>
   <# }
   }
 #>

Réexécutez la transformation.

La boîte de dialogue Débogueur juste-à-temps Visual Studio s'affiche
Dans la liste Débogueurs possibles, cliquez sur Nouvelle instance de Visual Studio 2010, puis sur Oui.

Le fichier DebugTest.tt s'ouvre dans une nouvelle instance de Visual Studio.
Exécutez le code pas à pas jusqu'à la ligne suivante :
```
xDoc.Load(@"C:\nonsense\nonsense.xml");
```
L'erreur se produira au niveau de cette ligne.
Fermez la deuxième instance de Visual Studio.
1. Dans le menu Déboguer, cliquez sur Arrêter le débogage.
2. Dans le menu Fichier, cliquez sur Quitter.
3. Lorsque vous êtes invité à enregistrer les modifications apportées à la solution, cliquez sur Non.
  
  La deuxième instance de Visual Studio se ferme.
Corrigez le modèle de texte et supprimez les fonctionnalités de débogage.
1. Dans l'Explorateur de solutions, double-cliquez sur le fichier DebugTest.tt pour l'ouvrir dans l'éditeur.
2. Corrigez le nom de fichier erroné. Par exemple, remplacez-le par ce qui suit :
  
  @"C:\\Program Files\\Microsoft Visual Studio 10.0\\Xml\\SnippetsIndex.xml"
3. Supprimez la directive templat et le saut de ligne.
  
  Le modèle de texte doit se présenter comme suit :
```
<#@ output extension=".txt" #>
<#@ assembly name="System.Xml.dll" #>
<#@ import namespace="System.Xml" #>
<#
    XmlDocument xDoc = new XmlDocument();
    xDoc.Load(@"C:\Program Files\Microsoft Visual Studio 10.0\Xml\SnippetsIndex.xml");
    foreach (XmlNode node in xDoc.SelectNodes("//*"))
    {  #>
       <#= node.Name #>
   <#  }
#>
```

Enregistrez DebugTest.tt. Vérifiez qu'il n'y a pas d'erreurs et que le fichier .txt obtenu répertorie les noms de nœuds du fichier XML.

Voir aussi

Référence

Erreurs et avertissements courants lors de l'utilisation de modèles de texte

Partager via