Benutzerdefinierte Datenschnellansichten für den Visual Studio-Debugger (.NET)

  • Artikel

Wichtig

Ab Visual Studio 2022 Version 17.9 können jetzt Visualizer in .NET 6.0+ geschrieben werden, die außerhalb des Prozesses unter Verwendung des neuen VisualStudio.Extensibility-Modells laufen. Wir empfehlen Visualizer-Autoren, die neue Dokumentation unter Visual Studio Debugger Visualizer erstellen zu referenzieren, es sei denn, sie möchten ältere Versionen von Visual Studio unterstützen oder ihre benutzerdefinierten Visualisierungen als Teil einer Bibliotheks-DLL ausliefern.

Eine Schnellansicht ist Teil der Benutzeroberfläche des Visual Studio-Debuggers, in der eine Variable oder ein Objekt auf eine für den jeweiligen Datentyp geeignete Weise angezeigt wird. Eine Bitmap-Schnellansicht interpretiert beispielsweise eine Bitmapstruktur und zeigt die zugehörige Grafik an. In einigen Schnellansichten können Sie die Daten nicht nur anzeigen, sondern auch bearbeiten. Im Debugger wird eine Schnellansicht durch das Lupensymbol VisualizerIcon dargestellt. Das Symbol steht in einem Datentipp, im Überwachungsfenster des Debuggers oder im Dialogfeld Schnellüberwachung zur Verfügung. Wählen Sie dieses Symbol und dann die geeignete Schnellansicht für das entsprechende Objekt aus.

Zusätzlich zu den standardmäßig integrierten Schnellansichten können möglicherweise weitere Schnellansichten von Microsoft, Drittanbietern und der Community heruntergeladen werden. Sie können auch eigene Schnellansichten schreiben und sie im Visual Studio-Debugger installieren.

Dieser Artikel enthält eine allgemeine Übersicht über die Erstellung von Schnellansichten. Ausführliche Anweisungen finden Sie stattdessen in den folgenden Artikeln:

Hinweis

Benutzerdefinierte Schnellansichten werden für Universelle Windows-Plattform- und Windows 8.x-Apps nicht unterstützt.

Übersicht

Sie können für ein Objekt einer beliebigen verwalteten Klasse eine benutzerdefinierte Schnellansicht schreiben. Ausnahmen stellen Object und Array dar.

Die Architektur einer Debuggerschnellansicht besteht aus zwei Teilen:

  • Die Debuggerseite, die im Visual Studio-Debugger ausgeführt wird, erstellt die Benutzeroberfläche der Schnellansicht und zeigt diese an.

    Da Visual Studio in der .NET Framework Runtime ausgeführt wird, muss diese Komponente für .NET Framework geschrieben werden. Aus diesem Grund ist es nicht möglich, sie für .NET Core zu schreiben.

  • Die zu debuggende Seite wird innerhalb des Prozesses ausgeführt, den Visual Studio debuggt (die zu debuggende Komponente). Das darzustellende Datenobjekt (z. B. ein Zeichenfolgenobjekt) ist im zu debuggenden Prozess vorhanden. Die zu debuggende Seite sendet das Objekt an die Debuggerseite, die es auf der von Ihnen erstellten Benutzeroberfläche anzeigt.

    Die Runtime, für die Sie diese Komponente erstellen, sollte mit der Runtime übereinstimmen, in der der Debugprozess ausgeführt wird, also entweder .NET Framework oder .NET Core.

Die Debuggerseite empfängt das Datenobjekt von einem Objektanbieter, der die IVisualizerObjectProvider-Oberfläche implementiert. Die zu debuggende Seite sendet das Objekt über die Objektquelle, die von VisualizerObjectSource abgeleitet wird.

Der Objektanbieter kann auch Daten an die Objektquelle zurücksenden. Dadurch können Sie eine Schnellansicht schreiben, die Daten bearbeiten kann. Sie überschreiben den Objektanbieter, um mit der Ausdrucksauswertung und der Objektquelle zu kommunizieren.

Die zu debuggende Seite und die Debuggerseite kommunizieren miteinander über Stream-Methoden, die ein Datenobjekt in einem Stream serialisieren und anschließend den Stream wieder in ein Datenobjekt konvertieren (deserialisieren).

Sie können für einen generischen Typ nur dann eine Schnellansicht schreiben, wenn es sich um einen offenen Typ handelt. Diese Einschränkung entspricht der Einschränkung bei Verwendung des DebuggerTypeProxy-Attributs. Einzelheiten finden Sie unter Verwenden des DebuggerTypeProxy-Attributs.

In benutzerdefinierten Schnellansichten treten möglicherweise Sicherheitsprobleme auf. Siehe Sicherheitsüberlegungen zu Schnellansichten.

Erstellen der debuggerseitigen Benutzeroberfläche

Zum Erstellen der Benutzeroberfläche der Schnellansicht auf Debuggerseite erstellen Sie eine Klasse, die von DialogDebuggerVisualizer erbt, und überschreiben die Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show-Methode zum Anzeigen der Oberfläche. Mit IDialogVisualizerService können Sie Windows Forms, Dialogfelder und Steuerelemente in der Schnellansicht anzeigen.

  1. Verwenden Sie IVisualizerObjectProvider-Methoden, damit das visuell dargestellte Objekt auf der Debuggerseite ist.

  2. Erstellen Sie eine Klasse, die von DialogDebuggerVisualizer erbt.

Hinweis

Aufgrund der Sicherheitsprobleme, die im folgenden Abschnitt beschrieben werden, können Visualizer ab Visual Studio 2022 Version 17.11 die Legacy Formatierungsrichtlinie nicht mehr im Konstruktor der Basisklasse angeben. Von nun an können Visualisierungen nur noch die JSON-Serialisierung für die Kommunikation zwischen dem Debugger und zu debuggenden Komponenten verwenden.

  1. Überschreiben Sie die Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show-Methode, um die Oberfläche anzuzeigen. Mit den IDialogVisualizerService-Methoden können Sie Windows Forms, Dialogfelder und Steuerelemente auf der Oberfläche anzeigen.

  2. Wenden Sie DebuggerVisualizerAttribute an, und lassen Sie es in der Schnellansicht anzeigen (DialogDebuggerVisualizer).

Besondere Überlegungen zur Debuggerseite für .NET 5.0 und höher

Benutzerdefinierte Schnellansichten übertragen Daten zwischen der zu debuggenden Komponente und dem Debugger durch binäre Serialisierung, indem standardmäßig die Klasse BinaryFormatter verwendet wird. Diese Art der Serialisierung wird in .NET 5 und höher jedoch aufgrund von Sicherheitsbedenken hinsichtlich nicht behebbarer Sicherheitsrisiken eingeschränkt. Darüber hinaus wurde sie in ASP.NET Core 5 als vollständig veraltet markiert, und ihre Verwendung wird wie in der Dokumentation zu ASP.NET Core beschrieben eingestellt. In diesem Abschnitt werden die Schritte beschrieben, die Sie ausführen sollten, um sicherzustellen, dass Ihre Schnellansicht in diesem Szenario weiterhin unterstützt wird.

  • Aus Kompatibilitätsgründen wird von der Methode Show, die im vorherigen Abschnitt überschrieben wurde, weiterhin ein IVisualizerObjectProvider verwendet. Ab Visual Studio 2019, Version 16.10, ist der Typ jedoch tatsächlich IVisualizerObjectProvider3. Aus diesem Grund müssen Sie das Objekt objectProvider in die aktualisierte Schnittstelle umwandeln.

  • Wenn Objekte wie z. B. Befehle oder Daten an die zu debuggende Komponente gesendet werden, verwenden Sie die Methode IVisualizerObjectProvider2.Serialize für die Übergabe an einen Datenstrom. So wird basierend auf der Laufzeit des Prozesses der zu debuggenden Komponente das ideale Serialisierungsformat ermittelt. Übergeben Sie dann den Datenstrom an die Methode IVisualizerObjectProvider2.TransferData.

  • Wenn von der zu debuggenden Komponente der Schnellansicht eine Rückgabe an die Debuggerseite erforderlich ist, befindet sich das betreffende Element im Objekt Stream, das von der Methode TransferData zurückgegeben wird. Verwenden Sie die IVisualizerObjectProvider2.GetDeserializableObjectFrom Methode, um eine IDeserializableObject Instanz daraus abzurufen und sie nach Bedarf zu verarbeiten; oder verwenden DeserializeFromJson Sie, wenn es sich um einen Typ handelt, den Sie kennen, wie Sie deserialisieren.

Lesen Sie den Abschnitt Besondere Überlegungen zur Seite der zu debuggenden Komponente für .NET 5.0 und höher, um zu erfahren, welche weiteren Änderungen auf der Seite der zu debuggenden Komponente erforderlich sind, wenn die binäre Serialisierung nicht unterstützt wird.

Hinweis

Weitere Informationen zu diesem Problem finden Sie im BinaryFormatter-Sicherheitsleitfaden.

Erstellen der debuggerseitigen Schnellansichtobjektquelle

Bearbeiten Sie im debuggerseitigen Code das Element DebuggerVisualizerAttribute, indem Sie ihm den zu visualisierenden Typ angeben (die zu debuggende Objektquelle) (VisualizerObjectSource). Die Target-Eigenschaft legt die Objektquelle fest. Wenn Sie die Objektquelle weglassen, wird eine Standardobjektquelle für die Schnellansicht verwendet.

Der zu debuggende Code enthält die Objektquelle, die visualisiert wird. Das Datenobjekt kann Methoden von VisualizerObjectSource überschreiben. Eine zu debuggende DLL ist erforderlich, wenn Sie eine eigenständige Schnellansicht erstellen möchten.

Im zu debuggenden Code:

  • Damit Sie in der Schnellansicht Datenobjekte bearbeiten können, muss die Objektquelle von VisualizerObjectSource erben und die Methoden TransferData oder CreateReplacementObject überschreiben.

  • Wenn Sie in Ihrer Schnellansicht mehrere Ziele unterstützen müssen, können Sie die folgenden Zielframeworkmoniker (Target Framework Monikers, TFMs) in die zu debuggende Projektdatei einfügen.

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

    Dies sind die einzigen unterstützten TFMs.

Besondere Überlegungen zur Seite der zu debuggenden Komponente für .NET 5.0 und höher

Wichtig

Möglicherweise sind zusätzliche Schritte erforderlich, damit eine Schnellansicht ab NET 5.0 funktioniert. Dies ist auf Sicherheitsbedenken hinsichtlich der zugrunde liegenden Methode zur binären Serialisierung zurückzuführen, die standardmäßig verwendet wird. Lesen Sie diesen Abschnitt, bevor Sie fortfahren.

  • Wenn die Schnellansicht die Methode TransferData implementiert, verwenden Sie die neu hinzugefügte Methode GetDeserializableObject, die in der neuesten Version von VisualizerObjectSource zur Verfügung steht. Anhand des zurückgegebenen IDeserializableObject können Sie das Serialisierungsformat des Objekts (binär oder JSON) ermitteln und das zugrunde liegende Objekt deserialisieren, sodass es verwendet werden kann.

  • Wenn die zu debuggende Komponente im Rahmen des TransferData-Aufrufs Daten an die Debuggerseite zurückgibt, serialisieren Sie die Antwort an den Datenstrom der Debuggerseite über die Methode Serialize.

Zugehöriger Inhalt