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

Article
05/16/2024

Important

À compter de Visual Studio 2022 version 17.9, les visualiseurs peuvent désormais être écrits en .NET 6.0+ et s’exécuter hors processus à l’aide du nouveau modèle VisualStudio.Extensibility. Nous encourageons les auteurs du visualiseur à référencer la nouvelle documentation sur Créer des visualiseurs de débogueur Visual Studio, sauf s’ils souhaitent prendre en charge les versions antérieures de Visual Studio ou envoyer leurs visualiseurs personnalisés dans le cadre d’une DLL de bibliothèque.

Cette procédure pas à pas explique comment écrire un visualiseur simple à l’aide de C#. Le visualiseur que permet de créer cette procédure pas à pas affiche le contenu d'une chaîne à l'aide d'un Windows Form. Ce visualiseur de chaîne simple n’est pas particulièrement utile en soi, mais il montre les étapes de base que vous devez suivre pour créer des visualiseurs plus utiles pour d’autres types de données.

Remarque

Selon vos paramètres actifs ou votre édition, les boîtes de dialogue et les commandes de menu affichées peuvent différer de celles qui sont décrites dans l'aide. Pour modifier vos paramètres, dans le menu Outils, cliquez sur Importer et exporter des paramètres. Pour plus d’informations, consultez Réinitialiser les paramètres.

Le code du visualiseur doit être placé dans un fichier DLL qui sera lu par le débogueur. La première étape consiste à créer un projet de bibliothèque de classes pour la DLL.

Créer un visualiseur manuellement

Effectuez les tâches suivantes pour créer un visualiseur.

Créer un projet de bibliothèque de classes

Pour créer un projet de bibliothèque de classes, sélectionnez Fichier>Nouveau>Projet.
Dans la liste déroulante langue, sélectionnez C#.
Dans la zone de recherche, saisissez bibliothèque de classes. Sélectionnez Bibliothèque de classes (.NET Framework), puis cliquez sur Suivant.
Dans la boîte de dialogue, entrez le nom MyFirstVisualizer, puis sélectionnez Créer.

Pour le projet visualiseur, veillez à sélectionner une bibliothèque de classes .NET Framework et non .NET. Même si le visualiseur doit être .NET Framework, l’application appelante peut être .NET.

Après avoir créé la bibliothèque de classes, vous devez ajouter une référence au fichier Microsoft.VisualStudio.DebuggerVisualizers.DLL pour pouvoir utiliser les classes définies. Avant d’ajouter la référence, vous devez renommer certaines classes avec des noms explicites.

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 correspondant au nouveau nom du fichier. Si vous voyez une invite pour terminer l’action, sélectionnez Oui.
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 Parcourir, sélectionnez Parcourir et recherchez la Microsoft.VisualStudio.DebuggerVisualizers.DLL.

Vous trouverez la DLL dans le sous-répertoire <Répertoire d’installation de Visual Studio>\Common7\IDE\PublicAssemblies du répertoire d’installation de Visual Studio.
Cliquez sur OK.
Dans DebuggerSide.cs, ajoutez les éléments suivants aux directives 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. Tout d'abord, vous devez modifier la déclaration de l'objet DebuggerSide pour configurer l’héritage de la classe de base DialogDebuggerVisualizer.

Hériter de DialogDebuggerVisualizer

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

Remplacez le code par :

public class DebuggerSide : DialogDebuggerVisualizer

Ajoutez un constructeur vide pour pouvoir transférer au constructeur de la classe de base la stratégie de sérialisation qui sera utilisée pour communiquer entre les composants du visualiseur.
```
public DebuggerSide() : base(FormatterPolicy.NewtonsoftJson) // or FormatterPolicy.Json
{
}
```
Remarque

En raison des problèmes de sécurité décrits dans Considérations spéciales sur le débogueur pour .NET 5.0+, à compter de Visual Studio 2022 version 17.11, les visualiseurs ne pourront pas spécifier la stratégie de formateur Legacy.
DialogDebuggerVisualizer a une méthode abstraite, Show, que vous devez substituer.

Substituer la méthode DialogDebuggerVisualizer.Show

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

protected override 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. Durant cette procédure pas à pas, vous utilisez un message Windows Forms. Tout d’abord, vous devez ajouter une référence et using une directive pour System.Windows.Forms.

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 Parcourir, sélectionnez Parcourir, puis recherchez la System.Windows.Forms.DLL.

Vous trouverez la DLL dans C:\Windows\Microsoft .NET\Framework\v4.0.30319.
Cliquez sur OK.
Dans DebuggerSide.cs, ajoutez les éléments suivants aux directives using :
```
using System.Windows.Forms;
```

Puis, vous ajoutez du code pour créer et afficher l'interface utilisateur du visualiseur. Comme cet échantillon est votre premier visualiseur, vous pouvez simplifier l'interface utilisateur simple et utiliser un message.

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, sélectionnez Générer MyFirstVisualizer. Le projet doit se générer avec succès. Corrigez toutes les erreurs de build avant de continuer.

Le code côté débogueur est maintenant terminé. 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.

Ajouter le type à visualiser pour le code côté débogage

Dans le code côté débogueur, vous spécifiez le type à visualiser (la source de l’objet) pour le débogueur à l’aide de l’attribut DebuggerVisualizerAttribute. La propriété Target définit le type à visualiser.

Ajoutez le code d'attribut suivant à DebuggerSide.cs, après les directives 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, sélectionnez 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.

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, sélectionnez 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. Par souci de simplicité, utilisez un projet d'application console.

Ajouter un projet d'application console à la solution

Dans l’Explorateur de solutions, cliquez avec le bouton droit sur la solution, choisissez Ajouter puis sélectionnez Nouveau projet.
Choisissez Fichier>Nouveau>Projet. Dans la liste déroulante langue, choisissez C#. Dans la zone de recherche, tapez application console, puis choisissez Application console (.NET Framework) ou Application console pour .NET. Cliquez sur Suivant. Dans la boîte de dialogue qui s’affiche, tapez le nom MyTestConsole, puis sélectionnez Créer.

Remarque

Si vous souhaitez tester facilement le visualiseur à l’aide d’un atelier de test, créez une application console .NET Framework. Vous pouvez créer une application console .NET à la place, mais l’atelier de test décrit plus loin n’est pas encore pris en charge pour .NET. Vous devez donc installer le visualiseur pour le tester. Pour une application console .NET, commencez par créer l’application console ici, ajoutez la DLL et les références de projet requises, puis suivez les étapes décrites dans Ajouter un objet de données côté débogage. Pour les scénarios ASP.NET Core, consultez Considérations spéciales côté débogueur pour .NET 5.0+.

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

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, ouvrez l’onglet Parcourir, et sélectionnez Microsoft.VisualStudio.DebuggerVisualizers.DLL.
Cliquez sur OK.
Cliquez avec le bouton droit sur MyTestConsole, puis sélectionnez à nouveau Ajouter une référence.
Dans la boîte de dialogue Ajouter une référence, ouvrez l’onglet Projets et sélectionnez MyFirstVisualizer.
Cliquez sur OK.

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

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.
Modifiez le nom de Program.cs sur quelque chose de plus explicite, tel que TestConsole.cs.

Notes

Visual Studio remplace automatiquement le nom de la déclaration de classe par TestConsole.cs correspondant au nouveau nom du fichier.
Dans TestConsole.cs, ajoutez le code suivant aux directives 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.

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 s’affiche et affiche la chaîne « Hello, World ».

Félicitations ! Vous avez généré et testé 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 Guide pratique pour installer un visualiseur.

Ajouter un objet de données côté élément débogué

Dans cette section, vous passez de l’objet System.String de données à un objet de données personnalisé.

Dans l’Explorateur de solutions, cliquez avec le bouton droit sur la solution, choisissez Ajouter puis sélectionnez Nouveau projet. Dans la liste déroulante langue, choisissez C#. Dans la zone de recherche, tapez bibliothèque de classes, puis choisissez Bibliothèque de classes (.NET Framework) ou Bibliothèque de classes pour .NET Standard.

Notes

Si vous utilisez une application console de test .NET Framework, veillez à créer un projet de bibliothèque de classes .NET Framework.
Cliquez sur Suivant. Dans la boîte de dialogue qui s’affiche, tapez le nom MyDataObject, puis sélectionnez Créer.
(Bibliothèque de classes .NET Standard uniquement) Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet et choisissez Modifier le fichier projet. Remplacez la valeur <TargetFramework> par netstandard2.0.
```
<TargetFramework>netstandard2.0</TargetFramework>
```
Dans l’espace de noms MyDataObject, remplacez le code par défaut par le code suivant.
```
[Serializable] 
public class CustomDataObject
{
   public CustomDataObject()
   {
      this.MyData = "MyTestData";
   }
   public string MyData { get; set; }
}
```
Pour un visualiseur en lecture seule, comme dans cet exemple, il n’est pas nécessaire d’implémenter des méthodes de VisualizerObjectSource.

Ensuite, mettez à jour le projet MyFirstVisualizer pour utiliser le nouvel objet de données.
Dans l’Explorateur de solutions, sous le projet MyFirstVisualizer, cliquez avec le bouton droit sur le nœud Références, puis choisissez Ajouter une référence.
Sous Projets, sélectionnez le projet MyDataObject.
Dans le code d’attribut de DebuggerSide.cs, mettez à jour la valeur Cible en remplaçant System.String par MyDataObject.CustomDataObject.
```
Target = typeof(MyDataObject.CustomDataObject),
```
Dans le projet MyFirstVisualizer, remplacez le code de la méthode Showpar le code suivant.
```
var data = objectProvider.GetObject() as MyDataObject.CustomDataObject;

// You can replace displayForm with your own custom Form or Control.  
Form displayForm = new Form();
displayForm.Text = data.MyData;
windowService.ShowDialog(displayForm);
```
Le code précédent utilise une propriété de l’objet de données à afficher dans le titre du formulaire.

Ensuite, mettez à jour l’application console pour utiliser l’objet de données personnalisé.
Dans l’Explorateur de solutions, sous le projet MyTestConsole, cliquez avec le bouton droit sur le nœud Références ou Dépendances, puis ajoutez une référence de projet à MyDataObject.

Dans Program.cs, remplacez le code dans la méthode Main par le code suivant.

// String myString = "Hello, World";
CustomDataObject customDataObject = new CustomDataObject();

DebuggerSide.TestShowVisualizer(customDataObject);

(Application console .NET) Placez l’appel à TestShowVisualizer dans une instruction try-catch, car l’atelier de test n’est pas pris en charge.
```
try
{
      DebuggerSide.TestShowVisualizer(customDataObject);
}
catch (Exception) {
}
```
L’application console a besoin d’une référence au runtime du visualiseur. Vous pouvez conserver la référence en conservant le code précédent au lieu de la commenter.
Pour une application console .NET Framework, vous pouvez exécuter l’atelier de test (appuyez sur F5), ou vous pouvez suivre les instructions fournies dans Guide pratique pour installer un visualiseur.

Si vous exécutez l’application à l’aide de l’atelier de test, l’application affiche le Windows Form.
Pour une application console .NET, copiez le MyFirstVisualizer.dll et le MyDataObject.dll dans les dossiers décrits dans Guide pratique pour installer un visualiseur.
Après avoir installé le visualiseur, définissez un point d’arrêt, exécutez l’application console et pointez sur customDataObject. Si tout est correctement configuré, vous devez voir l’icône de loupe .

Lorsque vous choisissez MyFirstVisualizer à partir de la loupe, vous voyez le formulaire avec le texte de l’objet de données dans le titre.

Partage via

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

Créer un visualiseur manuellement

Créer un projet de bibliothèque de classes

Renommer Class1.cs et ajouter Microsoft.VisualStudio.DebuggerVisualizers

Hériter de DialogDebuggerVisualizer

Substituer la méthode DialogDebuggerVisualizer.Show

Ajouter System.Windows.Forms

Afficher la sortie du visualiseur dans une boîte de dialogue

Ajouter le type à visualiser pour le code côté débogage

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

Ajouter un projet d'application console à la solution

Ajouter les références nécessaires à MyTestConsole

Ajouter le code à MyTestConsole

Tester le visualiseur

Ajouter un objet de données côté élément débogué

Commentaires

Ressources supplémentaires

Partage via

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

Créer un visualiseur manuellement

Créer un projet de bibliothèque de classes

Renommer Class1.cs et ajouter Microsoft.VisualStudio.DebuggerVisualizers

Hériter de DialogDebuggerVisualizer

Substituer la méthode DialogDebuggerVisualizer.Show

Ajouter System.Windows.Forms

Afficher la sortie du visualiseur dans une boîte de dialogue

Ajouter le type à visualiser pour le code côté débogage

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

Ajouter un projet d'application console à la solution

Ajouter les références nécessaires à MyTestConsole

Ajouter le code à MyTestConsole

Tester le visualiseur

Ajouter un objet de données côté élément débogué

Contenu connexe

Commentaires

Ressources supplémentaires