Freigeben über

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

Von Bedeutung

Ab Visual Studio 2022-Version 17.9 können Visualisierungen jetzt in .NET 6.0+ geschrieben werden, die mit dem neuen VisualStudio.Extensibility-Modell außerhalb des Prozesses ausgeführt werden. Für Erweiterungen, die mit dem neuen Modell erstellt wurden, sehen Sie die Dokumentation unter Erstellen von Visual Studio-Debugger-Visualisierungen ein. Wenn Sie ältere Versionen von Visual Studio unterstützen oder Ihre benutzerdefinierten Visualisierungen als Teil einer Bibliotheks-DLL versenden möchten, verwenden Sie die Informationen in diesem Artikel, die nur für das ältere Modell der Erweiterungsentwicklung (VSSDK) gelten.

Eine Visualisierung ist Teil der Visual Studio-Debugger-Benutzeroberfläche, die eine Variable oder ein Objekt entsprechend dem Datentyp anzeigt. Beispielsweise interpretiert ein Bitmap-Visualizer eine Bitmap-Struktur und zeigt die Grafik, die sie darstellt. Einige Visualisierungen ermöglichen es Ihnen, die Daten zu ändern und anzuzeigen. Im Debugger wird ein Visualizer durch ein Lupensymbol VisualizerIcon dargestellt. Sie können das Symbol in einem DataTip, Überwachungsfenster oder QuickWatch-Dialogfeld auswählen und dann den entsprechenden Visualizer für das entsprechende Objekt wählen.

Zusätzlich zu den standardmäßigen integrierten Visualisierungen stehen möglicherweise weitere Visualizer zum Download von Microsoft, Drittanbietern und der Community zur Verfügung. Sie können auch eigene Visualisierungen schreiben und im Visual Studio-Debugger installieren.

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

Hinweis

Benutzerdefinierte Visualisierungen werden für UWP-Apps (Universelle Windows-Plattform) und Windows 8.x-Apps nicht unterstützt.

Überblick

Sie können eine benutzerdefinierte Visualisierung für ein Objekt jeder verwalteten Klasse mit Ausnahme von Object und Array.

Die Architektur eines Debugger-Visualisierers besteht aus zwei Teilen:

  • Die Debuggerseite wird im Visual Studio-Debugger ausgeführt und erstellt sowie zeigt die Visualisierer-Benutzeroberfläche 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, es für .NET Core zu schreiben.

  • Die Debug-Seite wird innerhalb des Prozesses, den Visual Studio debuggt (dem Debuggee), ausgeführt. Das zu visualisierende Datenobjekt (z. B. ein String-Objekt) ist im Debugprozess vorhanden. Die Debuggee-Seite sendet das Objekt an die Debugger-Seite, welche es in der von Ihnen erstellten Benutzeroberfläche anzeigt.

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

Die Debuggerseite empfängt das Datenobjekt von einem Objektanbieter , der die IVisualizerObjectProvider Schnittstelle implementiert. Die Debuggee-Seite sendet das Objekt über die Objektquelle, die von VisualizerObjectSource abgeleitet ist.

Der Objektanbieter kann auch Daten zurück an die Objektquelle senden, sodass Sie eine Visualisierung schreiben können, mit der Daten bearbeitet werden können. Sie überschreiben den Objektanbieter, um mit dem Ausdrucksauswerter und der Objektquelle zu kommunizieren.

Die Debugsseite und die Debuggerseite kommunizieren miteinander durch Stream-Methoden, die ein Datenobjekt in ein Stream serialisieren und das Stream wieder in ein Datenobjekt deserialisieren.

Sie können eine Visualisierung nur für einen generischen Typ schreiben, wenn der Typ ein offener Typ ist. Diese Einschränkung entspricht der Einschränkung bei Verwendung des DebuggerTypeProxy Attributs. Ausführliche Informationen finden Sie in "Verwenden des DebuggerTypeProxy-Attributs".

Benutzerdefinierte Visualisierungen können Sicherheitsüberlegungen haben. Siehe Visualr-Sicherheitsüberlegungen.

Erstellen der debuggerseitigen Benutzeroberfläche

Um die Visualisierer-Benutzeroberfläche auf der Debuggerseite zu erstellen, erstellen Sie eine Klasse, die von DialogDebuggerVisualizer erbt, und überschreiben Sie die Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show-Methode, um die Schnittstelle anzuzeigen. Sie können IDialogVisualizerService verwenden, um Windows-Formulare, Dialogfenster und Steuerelemente in Ihrer Visualisierung anzuzeigen.

  1. Verwenden Sie IVisualizerObjectProvider Methoden, um das visualisierte Objekt auf der Debuggerseite abzurufen.

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

Hinweis

Aufgrund der sicherheitsrelevanten Probleme, die im folgenden Abschnitt beschrieben werden, können Visual Studio 2022 Version 17.11 Visualizer nicht die Legacy Formatiererrichtlinie im Konstruktor der Basisklasse angeben. Von nun an können Visualizer nur die JSON-Serialisierung verwenden, um zwischen dem Debugger und debuggeeseitigen Komponenten zu kommunizieren.

  1. Überschreiben Sie die Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show Methode, um Ihre Benutzeroberfläche anzuzeigen. Verwenden Sie IDialogVisualizerService Methoden zum Anzeigen von Windows-Formularen, -Dialogfeldern und -Steuerelementen in Ihrer Benutzeroberfläche.

  2. Wenden Sie DebuggerVisualizerAttribute an und geben Sie ihm den Visualisierer zur Anzeige (DialogDebuggerVisualizer).

Spezielle Überlegungen zur Debuggerseite für .NET 5.0+

Benutzerdefinierte Visualizer übertragen Daten zwischen debuggee und Debuggerseite über binäre Serialisierung standardmäßig mithilfe der BinaryFormatter Klasse. Diese Art von Serialisierung wird jedoch in .NET 5 und höher aufgrund von Sicherheitsbedenken hinsichtlich ihrer nicht behebbaren Sicherheitsanfälligkeiten eingeschränkt. Darüber hinaus ist sie in ASP.NET Core 5 vollständig als veraltet markiert, und ihre Verwendung wird einen Fehler auslösen, wie in der ASP.NET Core-Dokumentation beschrieben. In diesem Abschnitt werden die Schritte beschrieben, die Sie ausführen sollten, um sicherzustellen, dass Ihre Visualisierung in diesem Szenario weiterhin unterstützt wird.

  • Aus Kompatibilitätsgründen nimmt die Show-Methode, die im vorherigen Abschnitt überschrieben wurde, weiterhin ein IVisualizerObjectProvider entgegen. Ab Visual Studio 2019, Version 16.10, ist es jedoch tatsächlich vom Typ IVisualizerObjectProvider3. Aus diesem Grund wandeln Sie das objectProvider Objekt in die aktualisierte Schnittstelle um.

  • Wenn Objekte, wie Befehle oder Daten, an die Debuggee-Seite gesendet werden, verwenden Sie die IVisualizerObjectProvider2.Serialize-Methode, um sie an einen Datenstrom zu übergeben. Diese bestimmt basierend auf der Laufzeit des Debuggee-Prozesses das optimale Serialisierungsformat. Übergeben Sie dann den Datenstrom an die IVisualizerObjectProvider2.TransferData Methode.

  • Wenn die Debuggee-side visualizer-Komponente etwas an die Debuggerseite zurückgeben muss, befindet sie sich im objekt, das Stream von der TransferData Methode zurückgegeben wird. Verwenden Sie die IVisualizerObjectProvider2.GetDeserializableObjectFrom-Methode, um eine IDeserializableObject-Instanz daraus abzurufen und sie nach Bedarf zu verarbeiten, oder verwenden Sie DeserializeFromJson, wenn es sich um einen Typ handelt, von dem Sie wissen, wie man ihn deserialisiert.

Im Abschnitt "Besondere Überlegungen zur Debuggee-Seite für .NET 5.0+" finden Sie Informationen dazu, welche anderen Änderungen auf der Debuggee-Seite erforderlich sind, wenn die binäre Serialisierung nicht unterstützt wird.

Hinweis

Weitere Informationen zum Problem finden Sie im BinaryFormatter-Sicherheitshandbuch.

Erstellen der Visualisiererobjektquelle für die Debugseite

Bearbeiten Sie im Debugger-seitigen Code den Typ DebuggerVisualizerAttribute, indem Sie den zu visualisierenden Typ (die Debuggee-seitige Objektquelle) VisualizerObjectSource angeben. Die Target Eigenschaft legt die Objektquelle fest. Wenn Sie die Objektquelle weglassen, verwendet die Visualisierung eine Standardobjektquelle.

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

In der Debugging-Seite des Codes:

  • Damit der Visualizer Datenobjekte bearbeiten kann, muss die Objektquelle von VisualizerObjectSource erben und die Methoden TransferData oder CreateReplacementObject überschreiben.

  • Wenn Sie multi-targeting in Ihrer Visualisierung unterstützen müssen, können Sie die folgenden Target Framework Monikers (TFMs) in der Debuggee-side-Projektdatei verwenden.

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

    Dies sind die einzigen unterstützten TFMs.

Spezielle Überlegungen zur Debuggee-Seite für .NET 5.0+

Von Bedeutung

Möglicherweise sind zusätzliche Schritte erforderlich, damit eine Visualisierung ab .NET 5.0 aufgrund von Sicherheitsbedenken bezüglich der zugrunde liegenden binären Serialisierungsmethode funktioniert, die standardmäßig verwendet wird. Bitte lesen Sie diesen Abschnitt , bevor Sie fortfahren.

  • Wenn der Visualisierer die TransferData Methode implementiert, verwenden Sie die neu hinzugefügte GetDeserializableObject Methode, die in der neuesten Version von VisualizerObjectSource verfügbar ist. Die IDeserializableObject Rückgabe hilft, das Serialisierungsformat (Binär- oder JSON-Format) des Objekts zu bestimmen und das zugrunde liegende Objekt deserialisieren, damit es verwendet werden kann.

  • Wenn das Debuggee-Side Daten als Teil des Aufrufs an die TransferData zurückgibt, serialisieren Sie die Antwort auf den Datenstrom der Debuggerseite über die Serialize Methode.

Verwandte Inhalte

  • Last updated on