Partager via

Visualiseurs de données personnalisés pour le débogueur Visual Studio (.NET)

Important

À compter de Visual Studio 2022 version 17.9, les visualiseurs peuvent désormais être écrits dans .NET 6.0+ qui s’exécutent hors processus à l’aide du nouveau modèle VisualStudio.Extensibility. Pour les extensions créées à l’aide du nouveau modèle, consultez la documentation de Créer des visualiseurs de débogueur Visual Studio à la place. Si vous devez prendre en charge les versions antérieures de Visual Studio ou si vous souhaitez expédier vos visualiseurs personnalisés dans le cadre d’une DLL de bibliothèque, utilisez les informations de cet article, qui s’appliquent uniquement au modèle plus ancien de développement d’extension (VSSDK).

Un visualiseur fait partie de l’interface utilisateur du débogueur Visual Studio qui affiche une variable ou un objet d’une manière appropriée à son type de données. Par exemple, un visualiseur bitmap interprète une structure bitmap et affiche le graphique qu’il représente. Certains visualiseurs vous permettent de modifier et d’afficher les données. Dans le débogueur, un visualiseur est représenté par une icône de loupe Visualiseur. Vous pouvez sélectionner l'icône dans une DataTip, la fenêtre Watch du débogueur ou la boîte de dialogue QuickWatch, puis sélectionner le visualiseur approprié pour l'objet correspondant.

En plus des visualiseurs intégrés standard, d’autres visualiseurs peuvent être disponibles pour le téléchargement à partir de Microsoft, de tiers et de la communauté. Vous pouvez également écrire vos propres visualiseurs et les installer dans le débogueur Visual Studio.

Cet article fournit une vue d’ensemble générale de la création du visualiseur. Pour obtenir des instructions détaillées, consultez les articles suivants à la place :

Note

Les visualiseurs personnalisés ne sont pas pris en charge pour les applications de plateforme Windows universelle (UWP) et Windows 8.x.

Aperçu

Vous pouvez écrire un visualiseur personnalisé pour un objet de n’importe quelle classe managée à l’exception Object et Array.

L’architecture d’un visualiseur de débogueur comporte deux parties :

  • Le côté du débogueur s’exécute dans le débogueur Visual Studio et crée et affiche l’interface utilisateur du visualiseur.

    Étant donné que Visual Studio s’exécute sur le runtime .NET Framework, ce composant doit être écrit pour .NET Framework. Pour cette raison, il n’est pas possible de l’écrire pour .NET Core.

  • Le côté débogage s’exécute dans le processus que Visual Studio débogue (le débogueur). L’objet de données à visualiser (par exemple, un objet String) existe dans le processus de débogage. Le côté débogage envoie l’objet au côté débogueur, qui l’affiche dans l’interface utilisateur que vous créez.

    Le runtime pour lequel vous générez ce composant doit correspondre à celui dans lequel le processus de débogage s’exécutera, c’est-à-dire .NET Framework ou .NET Core.

Le débogueur reçoit l’objet de données d’un fournisseur d’objets qui implémente l’interface IVisualizerObjectProvider . Le côté du programme débogué envoie l'objet via la source de l’objet, qui est dérivée de VisualizerObjectSource.

Le fournisseur d’objets peut également renvoyer des données à la source de l’objet, ce qui vous permet d’écrire un visualiseur capable de modifier des données. Vous remplacez le fournisseur d'objets pour dialoguer avec l’évaluateur d’expression et la source d'objet.

Le côté à déboguer et le côté débogueur communiquent entre eux par le biais de méthodes Stream qui sérialisent un objet de données en un Stream et désérialisent le Stream pour retourner à un objet de données.

Vous pouvez écrire un visualiseur pour un type générique uniquement si le type est un type ouvert. Cette restriction est identique à la restriction lors de l’utilisation de l’attribut DebuggerTypeProxy . Pour plus d’informations, consultez l’attribut DebuggerTypeProxy.

Les visualiseurs personnalisés peuvent avoir des considérations de sécurité. Consultez les considérations relatives à la sécurité du visualiseur.

Créer l’interface utilisateur côté débogueur

Pour créer l'interface utilisateur du visualiseur côté débogueur, vous créez une classe qui hérite de DialogDebuggerVisualizer et qui remplace la méthode Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show pour afficher l'interface. Vous pouvez utiliser IDialogVisualizerService pour afficher les formulaires Windows, les dialogues et les contrôles dans votre visualiseur.

  1. Utilisez des IVisualizerObjectProvider méthodes pour obtenir l’objet visualisé côté débogueur.

  2. Créez une classe qui hérite de DialogDebuggerVisualizer.

Note

En raison des problèmes de sécurité décrits dans la section ci-dessous, à partir de la version 17.11 de Visual Studio 2022, les visualiseurs ne pourront plus spécifier la politique de formatage Legacy dans le constructeur de la classe de base. À partir de maintenant, les visualiseurs peuvent uniquement utiliser la sérialisation JSON pour communiquer entre le débogueur et les composants côté débogage .

  1. Remplacez la Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show méthode pour afficher votre interface. Utilisez des IDialogVisualizerService méthodes pour afficher des formulaires Windows, des dialogues et des contrôles dans votre interface.

  2. Appliquez DebuggerVisualizerAttribute, en lui donnant le visualiseur à afficher (DialogDebuggerVisualizer).

Considérations côté débogueur spéciales pour .NET 5.0+

Les visualiseurs personnalisés transfèrent des données entre le côté débogué et le côté débogueur via la sérialisation binaire à l'aide de la classe BinaryFormatter par défaut. Toutefois, ce type de sérialisation est limité dans .NET 5 et versions ultérieures en raison de problèmes de sécurité concernant ses vulnérabilités non fixes . De plus, il a été marqué comme totalement obsolète dans ASP.NET Core 5, et son utilisation générera une exception comme décrit dans la documentation ASP.NET Core. Cette section décrit les étapes à suivre pour vous assurer que votre visualiseur est toujours pris en charge dans ce scénario.

  • Pour des raisons de compatibilité, la Show méthode remplacée dans la section précédente prend toujours un IVisualizerObjectProvider. Toutefois, à partir de Visual Studio 2019 version 16.10, il est en fait de type IVisualizerObjectProvider3. Pour cette raison, convertissez l’objet objectProvider en l’interface mise à jour.

  • Lors de l’envoi d’objets, tels que des commandes ou des données, du côté debuggee, utilisez la méthode IVisualizerObjectProvider2.Serialize pour le transmettre à un flux; cela déterminera le meilleur format de sérialisation à utiliser en fonction de l'environnement d'exécution du processus debuggee. Ensuite, passez le flux à la IVisualizerObjectProvider2.TransferData méthode.

  • Si le composant visualiseur côté débogué doit retourner quoi que ce soit au côté débogueur, cela se trouvera dans l’objet Stream que la méthode TransferData retourne. Utilisez la méthode IVisualizerObjectProvider2.GetDeserializableObjectFrom pour obtenir une instance IDeserializableObject à partir de celle-ci et la traiter en fonction des besoins ; ou utilisez DeserializeFromJson s’il s’agit d’un type que vous savez comment désérialiser.

Reportez-vous à la section Considérations spéciales côté debuggee pour .NET 5.0+ pour savoir quelles autres modifications sont requises du côté debuggee lorsque la sérialisation binaire n'est pas prise en charge.

Note

Si vous souhaitez plus d’informations sur le problème, consultez le guide de sécurité BinaryFormatter.

Créer la source de l'objet visualiseur pour le côté débogué

Dans le code côté débogueur, modifiez le DebuggerVisualizerAttribute, en lui attribuant le type à visualiser (source de l'objet côté programme à déboguer) (VisualizerObjectSource). La Target propriété définit la source de l’objet. Si vous omettez la source de l’objet, le visualiseur utilise une source d’objet par défaut.

Le code côté du débogage contient la source des objets qui sont visualisées. L’objet de données peut remplacer les méthodes de VisualizerObjectSource. Une DLL côté débogage est nécessaire si vous souhaitez créer un visualiseur autonome.

Dans le code côté débogage :

  • Pour permettre au visualiseur de modifier les objets de données, la source d'objet doit hériter de VisualizerObjectSource et remplacer les méthodes TransferData ou CreateReplacementObject.

  • Si vous devez prendre en charge le ciblage multiple dans votre visualiseur, vous pouvez utiliser les monikers de framework cible (TFMs) suivants dans le fichier projet côté débogage.

    <TargetFrameworks>net20;netstandard2.0;netcoreapp2.0</TargetFrameworks>

    Il s’agit des seules TFMs prises en charge.

Considérations spéciales du côté du débogueur pour .NET 5.0+

Important

Des étapes supplémentaires peuvent être nécessaires pour qu’un visualiseur fonctionne à partir de .NET 5.0 en raison de problèmes de sécurité concernant la méthode de sérialisation binaire sous-jacente utilisée par défaut. Lisez cette section avant de continuer.

  • Si le visualiseur implémente la TransferData méthode, utilisez la méthode nouvellement ajoutée GetDeserializableObject disponible dans la dernière version de VisualizerObjectSource. Elle IDeserializableObject permet de déterminer le format de sérialisation de l’objet (binaire ou JSON) et de désérialiser l’objet sous-jacent afin qu’il puisse être utilisé.

  • Si le côté débogué retourne des données au côté débogueur dans le cadre de l'appel TransferData, sérialisez la réponse vers le flux du côté débogueur via la méthode Serialize.

Contenu connexe

  • Last updated on