Procédure pas à pas : écriture d'un visualiseur en C#

Article
06/10/2015

Cette procédure pas à pas montre comment écrire un visualiseur simple en C#. Le visualiseur que permet de créer cette procédure pas à pas affiche le contenu d'une chaîne à l'aide d'un message Windows Forms. Ce visualiseur de chaîne simple n'est pas très utile, mais il affiche les étapes élémentaires à suivre pour créer des visualiseurs plus utiles à d'autres types de données.

Notes

Les boîtes de dialogue et les commandes de menu qui s'affichent peuvent être différentes de celles qui sont décrites dans l'aide, en fonction de vos paramètres actifs ou de l'édition utilisée.Pour modifier vos paramètres, dans le menu Outils, cliquez sur Importation et exportation de paramètres.Pour plus d'informations, consultez Paramètres Visual Studio.

Le code du visualiseur doit être placé dans une DLL, laquelle sera lue par le débogueur. Par conséquent, la première étape consiste à créer un projet Bibliothèque de classes pour la DLL.

Pour créer un projet Bibliothèque de classes

Dans le menu Fichier, choisissez Nouveau, puis sur Nouveau projet.
Dans la boîte de dialogue Nouveau projet, sous Type de projet, sélectionnez Visual C#.
Dans la zone Modèles, choisissez Bibliothèque de classes.
Dans la zone Nom, tapez un nom approprié pour la bibliothèque de classes, par exemple MyFirstVisualizer.
Cliquez sur OK.

Une fois que vous avez créé la bibliothèque de classes, vous devez ajouter une référence à Microsoft.VisualStudio.DebuggerVisualizers.DLL afin de pouvoir utiliser les classes qui y sont définies. Toutefois, avant d'ajouter la référence, vous devez renommer certaines classes afin qu'elles aient des noms explicites.

Pour renommer Class1.cs et ajouter Microsoft.VisualStudio.DebuggerVisualizers

Dans l'Explorateur de solutions, cliquez avec le bouton droit sur Class1.cs et sélectionnez Renommer dans le menu contextuel.
Remplacez le nom Class1.cs par un nom explicite, par exemple DebuggerSide.cs.

Notes

Visual Studio remplace automatiquement le nom de la déclaration de classe par DebuggerSide.cs, le nouveau nom du fichier.
Dans l'Explorateur de solutions, cliquez avec le bouton droit sur Références, puis sélectionnez Ajouter une référence dans le menu contextuel.
Dans la boîte de dialogue Ajouter une référence, sous l'onglet .NET, cliquez sur Microsoft.VisualStudio.DebuggerVisualizers.DLL.
Cliquez sur OK.
Dans DebuggerSide.cs, ajoutez l'instruction suivante aux instructions using :
```
using Microsoft.VisualStudio.DebuggerVisualizers;
```

Vous êtes désormais prêt à créer du code côté débogueur. Il s'agit du code qui s'exécute dans le débogueur pour afficher les informations que vous souhaitez consulter. En premier lieu, vous devez modifier la déclaration de l'objet DebuggerSide afin qu'il hérite de la classe de base DialogDebuggerVisualizer.

Pour hériter de DialogDebuggerVisualizer

Dans DebuggerSide.cs, allez à la ligne de code suivante :
```
public class DebuggerSide
```

Modifiez le code en :

public class DebuggerSide : DialogDebuggerVisualizer

DialogDebuggerVisualizer a une méthode abstraite (Show) que vous devez substituer.

Pour substituer la méthode DialogDebuggerVisualizer.Show

Dans public class DebuggerSide, ajoutez la méthode suivante :

override protected void Show(IDialogVisualizerService windowService, IVisualizerObjectProvider objectProvider)
{
}

La méthode Show contient le code qui crée en fait la boîte de dialogue du visualiseur (ou une autre interface utilisateur) et qui affiche les informations passées du débogueur au visualiseur. Vous devez ajouter le code qui crée la boîte de dialogue et affiche les informations. Cette procédure pas à pas vous montre comment y parvenir à l'aide d'un message Windows Forms. Vous devez d'abord ajouter une référence et une instruction using pour System.Windows.Forms.

Pour ajouter System.Windows.Forms

Dans l'Explorateur de solutions, cliquez avec le bouton droit sur Références, puis sélectionnez Ajouter une référence dans le menu contextuel.
Dans la boîte de dialogue Ajouter une référence, sous l'onglet .NET, cliquez sur System.Windows.Forms.DLL.
Cliquez sur OK.
Dans DebuggerSide.cs, ajoutez l'instruction suivante aux instructions using :
```
using System.Windows.Forms;
```

Puis, vous ajoutez du code pour créer et afficher l'interface utilisateur du visualiseur. Comme il s'agit de votre premier visualiseur, nous simplifierons l'interface utilisateur simple et utiliserons un message.

Pour afficher la sortie du visualiseur dans une boîte de dialogue

Dans la méthode Show, ajoutez la ligne de code suivante :
```
MessageBox.Show(objectProvider.GetObject().ToString());
```
Cet exemple de code n'inclut pas la gestion des erreurs. Vous devez inclure la gestion des erreurs dans un véritable visualiseur ou tout autre type d'application.
Dans le menu Générer, cliquez sur Générer MyFirstVisualizer. Le projet doit se générer avec succès. Corrigez toutes les erreurs de build avant de continuer.

C'est la fin du code côté débogueur. Il existe toutefois une étape supplémentaire : ajouter l'attribut qui indique côté programme débogué la collection de classes qui compose le visualiseur.

Pour ajouter le code côté débogué

Ajoutez le code d'attribut suivant à DebuggerSide.cs, après les instructions using, mais avant namespace MyFirstVisualizer :

[assembly:System.Diagnostics.DebuggerVisualizer(
typeof(MyFirstVisualizer.DebuggerSide),
typeof(VisualizerObjectSource),
Target  = typeof(System.String),
Description  = "My First Visualizer")]

Dans le menu Générer, cliquez sur Générer MyFirstVisualizer. Le projet doit se générer avec succès. Corrigez toutes les erreurs de build avant de continuer.

À ce stade, votre premier visualiseur est terminé. Si vous avez suivi les étapes correctement, vous devez être en mesure de générer le visualiseur et de l'installer dans Visual Studio. Toutefois, avant d'installer un visualiseur dans Visual Studio, vous devez le tester pour vous assurer qu'il s'exécute correctement. À présent, vous devez créer un atelier de test pour exécuter le visualiseur sans l'installer dans Visual Studio.

Pour ajouter une méthode de test permettant d'afficher le visualiseur

Ajoutez la méthode suivante à la classe public DebuggerSide:

public static void TestShowVisualizer(object objectToVisualize)
{
   VisualizerDevelopmentHost visualizerHost = new VisualizerDevelopmentHost(objectToVisualize, typeof(DebuggerSide));
   visualizerHost.ShowVisualizer();
}

Dans le menu Générer, cliquez sur Générer MyFirstVisualizer. Le projet doit se générer avec succès. Corrigez toutes les erreurs de build avant de continuer.

Ensuite, vous devez créer un projet exécutable pour appeler la DLL du visualiseur. Pour simplifier, nous utiliserons un projet d'application console.

Pour ajouter un projet d'application console à la solution

Dans le menu Fichier, cliquez sur Ajouter, puis sur Nouveau projet.
Dans la boîte de dialogue Ajouter un nouveau projet, dans le volet Modèles, choisissez Application console.
Dans la zone Nom, tapez un nom significatif pour l'application console, par exemple MyTestConsole.
Cliquez sur OK.

Puis, vous devez ajouter les références nécessaires afin que MyTestConsole puisse appeler MyFirstVisualizer.

Pour ajouter les références nécessaires à MyTestConsole

Dans l'Explorateur de solutions, cliquez avec le bouton droit sur MyTestConsole, puis sélectionnez Ajouter une référence dans le menu contextuel.
Dans la boîte de dialogue Ajouter une référence, sous l'onglet .NET, cliquez sur Microsoft.VisualStudio.DebuggerVisualizers.DLL.
Cliquez sur OK.
Cliquez avec le bouton droit sur MyTestConsole et choisissez à nouveau Ajouter une référence.
Dans la boîte de dialogue Ajouter une référence, cliquez sur l'onglet Projets, puis sur MyFirstVisualizer.
Cliquez sur OK.

Puis, vous ajoutez le code pour terminer l'atelier de test.

Pour ajouter le code à MyTestConsole

Dans l'Explorateur de solutions, cliquez avec le bouton droit sur Program.cs et sélectionnez Renommer dans le menu contextuel.
Remplacez le nom Program.cs par un nom plus explicite, par exemple TestConsole.cs.

Remarque Visual Studio modifie automatiquement la déclaration de classe dans TestConsole.cs pour qu'elle corresponde au nouveau nom de fichier.
Dans TestConsole.cs, ajoutez le code suivant aux instructions using :
```
using MyFirstVisualizer;
```

Dans la méthode Main, ajoutez le code suivant :

String myString = "Hello, World";
DebuggerSide.TestShowVisualizer(myString);

Vous êtes désormais prêt à tester votre premier visualiseur.

Pour tester le visualiseur

Dans l'Explorateur de solutions, cliquez avec le bouton droit sur MyTestConsole, puis sélectionnez Définir comme projet de démarrage dans le menu contextuel.
Dans le menu Déboguer, choisissez Démarrer.

L'application console démarre et le visualiseur apparaît et affiche la chaîne "Hello, World".

Félicitations ! Vous venez de générer et de tester votre premier visualiseur.

Pour utiliser votre visualiseur dans Visual Studio au lieu de simplement l'appeler de l'atelier de test, vous devez l'installer. Pour plus d'informations, consultez Comment : installer un visualiseur.

Utilisation du modèle d'élément du visualiseur

Jusqu'à présent, cette procédure pas à pas vous a indiqué comment créer manuellement un visualiseur. Elle a été exécutée comme un exercice d'apprentissage. Maintenant que vous savez comment fonctionne un visualiseur simple, apprenez à en créer plus facilement à l'aide du modèle d'élément du visualiseur.

D'abord, vous devez créer un projet Bibliothèque de classes.

Pour créer un nouveau projet de bibliothèque de classes

Dans le menu Fichier, cliquez sur Ajouter, puis sur Nouveau projet.
Dans la boîte de dialogue Ajouter un nouveau projet, sous Type de projet, sélectionnez Visual C#.
Dans la zone Modèles, choisissez Bibliothèque de classes.
Dans la zone Nom, tapez un nom approprié pour la bibliothèque de classes, par exemple MySecondVisualizer.
Cliquez sur OK.

Maintenant, vous pouvez lui ajouter un élément de visualiseur :

Pour ajouter un élément de visualiseur

Dans l'Explorateur de solutions, cliquez avec le bouton droit sur MySecondVisualizer.
Dans le menu contextuel, sélectionnez Ajouter, puis cliquez sur Nouvel élément.
Dans la boîte de dialogue Ajouter un nouvel élément, sous Modèles, Modèles Visual Studio installés, sélectionnez Visualiseur du débogueur.
Dans la zone Nom, tapez un nom approprié, par exemple SecondVisualizer.cs.
Cliquez sur Ajouter.

Et c'est tout ! Consultez le fichier SecondVisualizer.cs et examinez le code que le modèle a ajouté pour vous. Faites des essais avec le code. Maintenant que vous connaissez les principes de base, vous allez pouvoir créer par vous-même des visualiseurs plus complexes et plus utiles.

Voir aussi