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

Cette procédure pas à pas montre comment écrire un visualiseur simple à l’aide de C#. Le visualiseur que vous créez dans 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.

Le code du visualiseur doit être placé dans un fichier DLL que le débogueur lit. Par conséquent, la première étape consiste à créer un projet 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

1. Pour créer un nouveau projet de bibliothèque de classes, sélectionnez Fichier>Nouveau>Projet.

2. Dans la liste déroulante de langue, sélectionnez C#.

3. Dans la zone de recherche, entrez bibliothèque de classes. Sélectionnez Bibliothèque de classes (.NET Framework), puis sélectionnez Suivant.

4. 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. Bien que 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 Microsoft.VisualStudio.DebuggerVisualizers.DLL fichier pour pouvoir utiliser les classes définies ici. Avant d’ajouter la référence, vous devez renommer certaines classes pour utiliser des noms explicites.

Renommez Class1.cs et ajoutez Microsoft.VisualStudio.DebuggerVisualizers

1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur Class1.cs, puis sélectionnez Renommer dans le menu contextuel.

2. Remplacez le nom de Class1.cs par quelque chose de significatif, par exemple DebuggerSide.cs.

   Note

   Visual Studio modifie automatiquement la déclaration de classe dans DebuggerSide.cs pour qu’elle corresponde au nouveau nom de fichier. Si vous voyez une demande pour terminer l'action, sélectionnez Oui.

3. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur Références et choisissez Ajouter une référence dans le menu contextuel.

4. 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 <Common7\IDE\PublicAssemblies du répertoire d’installation de Visual Studio.

5. Cliquez sur OK.

6. Dans DebuggerSide.cs, ajoutez les éléments suivants aux directives using :

   using Microsoft.VisualStudio.DebuggerVisualizers;
   

Vous êtes maintenant prêt à écrire le code côté débogueur. Ce code s’exécute dans le débogueur pour afficher les informations que vous souhaitez visualiser. Tout d’abord, vous devez modifier la déclaration de l’objet DebuggerSide pour configurer l’héritage à partir de la classe DialogDebuggerVisualizerde base .

Hériter de DialogDebuggerVisualizer

1. Dans DebuggerSide.cs, accédez à la ligne de code suivante :

   public class DebuggerSide
   

2. Modifiez le code en :

   public class DebuggerSide : DialogDebuggerVisualizer
   

3. Ajoutez un constructeur vide pour pouvoir passer 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
   {
   }
   

   Note

   À partir de Visual Studio 2022 version 17.11, en raison des problèmes de sécurité décrits dans les considérations relatives au débogueur spécial pour .NET 5.0+, les visualiseurs ne pourront pas spécifier la stratégie de formatteur Legacy.

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

Remplacer la méthode DialogDebuggerVisualizer.Show

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

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

La Show méthode contient le code qui crée réellement la boîte de dialogue visualiseur ou une autre interface utilisateur et affiche les informations transmises au visualiseur à partir du débogueur. Vous devez ajouter le code qui crée la boîte de dialogue et afficher les informations. Dans cette procédure pas à pas, vous utilisez une boîte de message Windows Forms. Tout d’abord, vous devez ajouter une référence à et une directive using pour System.Windows.Forms.

Ajouter System.Windows.Forms

1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur Références et choisissez Ajouter une référence dans le menu contextuel.

2. Dans la boîte de dialogue Ajouter une référence , sous l’onglet Parcourir , sélectionnez Parcourir et recherchez la System.Windows.Forms.DLL.

   Vous trouverez la DLL dans C :\Windows\Microsoft.NET\Framework\v4.0.30319.

3. Cliquez sur OK.

4. Dans DebuggerSide.cs, ajoutez les éléments suivants aux directives using :

   using System.Windows.Forms;
   

À présent, vous ajoutez du code pour créer et afficher l’interface utilisateur de votre visualiseur. Étant donné que cet exemple est votre premier visualiseur, vous pouvez simplifier l’interface utilisateur et utiliser une boîte de message.

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

1. Dans la Show méthode, 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 visualiseur réel ou tout autre type d’application.

2. Dans le menu Générer , choisissez Build MyFirstVisualizer. Le projet devrait être construit avec succès. Corrigez les erreurs de build avant de continuer.

Le code côté débogueur est maintenant terminé. Il y a une autre étape, cependant ; l’attribut qui indique au côté debuggee quelle collection de classes comprend 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 Target propriété définit le type à visualiser.

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

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

2. Dans le menu Générer , choisissez Build MyFirstVisualizer. Le projet devrait être construit avec succès. Corrigez les erreurs de build avant de continuer.

   À ce stade, votre premier visualiseur est terminé. Si vous avez suivi correctement les étapes, vous pouvez générer le visualiseur et l’installer dans Visual Studio. Avant d’installer un visualiseur dans Visual Studio, vous devez toutefois le tester pour vous assurer qu’il s’exécute correctement. Vous créez maintenant un harnais de test pour exécuter le visualiseur sans l’installer dans Visual Studio.

Ajouter une méthode de test pour afficher le visualiseur

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

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

2. Dans le menu Générer , choisissez Build MyFirstVisualizer. Le projet devrait être construit avec succès. Corrigez les erreurs de build avant de continuer.

   Ensuite, vous devez créer un projet exécutable pour appeler votre DLL de visualiseur. Par souci de simplicité, utilisez un projet d’application console.

Ajouter un projet d’application console à la solution

1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur la solution, choisissez Ajouter, puis sélectionnez Nouveau projet.

2. Choisissez Fichier>Nouveau>Projet. Dans la liste déroulante de langue, choisissez C#. Dans la zone de recherche, tapez l’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.

À présent, vous devez ajouter les références nécessaires pour que MyTestConsole puisse appeler MyFirstVisualizer.

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

1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur MyTestConsole et choisissez Ajouter une référence dans le menu contextuel.

2. Dans la boîte de dialogue Ajouter une référence , ouvrez l’onglet Parcourir et sélectionnez Microsoft.VisualStudio.DebuggerVisualizers.DLL.

3. Cliquez sur OK.

4. Cliquez avec le bouton droit sur MyTestConsole et choisissez à nouveau Ajouter une référence .

5. Dans la boîte de dialogue Ajouter une référence , ouvrez l’onglet Projets et sélectionnez MyFirstVisualizer.

6. Cliquez sur OK.

À présent, vous ajoutez le code pour terminer le harnais de test.

Ajouter du code à MyTestConsole

1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur Program.cs et choisissez Renommer dans le menu contextuel.

2. Modifiez le nom de Program.cs en quelque chose de plus explicite, par exemple TestConsole.cs.

   Note

   Visual Studio modifie automatiquement la déclaration de classe dans TestConsole.cs pour qu’elle corresponde au nouveau nom de fichier.

3. Dans TestConsole.cs, ajoutez le code suivant aux using directives :

   using MyFirstVisualizer;
   

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

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

Vous êtes maintenant prêt à tester votre premier visualiseur.

Tester le visualiseur

1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur MyTestConsole et choisissez Définir comme projet de démarrage dans le menu contextuel.

2. 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 avez créé et testé votre premier visualiseur !

Si vous souhaitez utiliser votre visualiseur dans Visual Studio plutôt que simplement l’appeler à partir du harnais 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é débogage

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

1. 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 de langue, choisissez C#. Dans la zone de recherche, tapez la bibliothèque de classes, puis choisissez Bibliothèque de classes (.NET Framework) ou Bibliothèque de classes pour .NET Standard.

   Note

   Si vous utilisez une application console de test .NET Framework, veillez à créer un projet de bibliothèque de classes .NET Framework.

2. Cliquez sur Suivant. Dans la boîte de dialogue qui s’affiche, tapez le nom MyDataObject, puis sélectionnez Créer.

3. (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>
   

4. Dans l’espace MyDataObject de noms, 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, tel que 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.

5. Dans l’Explorateur de solutions sous le projet MyFirstVisualizer, cliquez avec le bouton droit sur le nœud Références et choisissez Ajouter une référence.

6. Sous Projets, sélectionnez le projet MyDataObject .

7. 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),
   

8. Dans le projet MyFirstVisualizer, remplacez le code de la Show méthode par 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 pour s’afficher dans le titre du formulaire.

   Ensuite, mettez à jour l’application console pour utiliser l’objet de données personnalisé.

9. 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.

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

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

11. (application console .NET) Placez l'appel à TestShowVisualizer dans une instruction try-catch, puisque le cadre de test n'est pas pris en charge.

    try
    {
          DebuggerSide.TestShowVisualizer(customDataObject);
    }
    catch (Exception) {
    }
    

    L’application console a besoin d’une référence runtime au visualiseur. Vous pouvez conserver la référence en conservant le code précédent au lieu de le commenter.

12. Pour une application console .NET Framework, vous pouvez exécuter le harnais de test (appuyez sur F5) ou suivre des instructions dans How to : Install a Visualizer.

    Si vous exécutez l’application à l’aide du harnais de test, l’application affiche windows Form.

13. Pour une application console .NET, copiez les MyFirstVisualizer.dll et MyDataObject.dll dans les dossiers décrits dans Comment : Installer un Visualiseur.

14. 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 configuré correctement, vous devriez voir l’icône en forme 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.

    

Contenu connexe

• Architecture du visualiseur
• Guide pratique pour installer un visualiseur
• Créer des visualiseurs personnalisés