Exemplarische Vorgehensweise: Schreiben einer Schnellansicht in C#

Artikel
05/16/2024

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.

In dieser exemplarischen Vorgehensweise wird gezeigt, wie Sie in C# eine einfache Schnellansicht schreiben können. Der Visualizer, den Sie in dieser Anleitung erstellen, zeigt den Inhalt einer Zeichenfolge mithilfe eines Windows-Formulars an. Diese einfache Zeichenfolgen-Schnellansicht ist an sich nicht sehr nützlich, doch es wird die grundlegende Vorgehensweise für das Erstellen besser geeigneter Schnellansichten für andere Datentypen gezeigt.

Hinweis

Die angezeigten Dialogfelder und Menübefehle können sich je nach den aktiven Einstellungen oder der verwendeten Version von den in der Hilfe beschriebenen unterscheiden. Wählen Sie im Menü Extras die Option Einstellungen importieren und exportieren aus, um die Einstellungen zu ändern. Weitere Informationen finden Sie unter Reset settings (Zurücksetzen der Einstellungen).

Schnellansicht-Code muss in einer DLL-Datei platziert werden, die der Debugger liest. Deshalb müssen Sie als Erstes ein Klassenbibliotheksprojekt für die DLL erstellen.

Manuelles Erstellen einer Schnellansicht

Führen Sie die folgenden Aufgaben aus, um eine Visualisierung zu erstellen.

Erstellen eines Klassenbibliotheksprojekts

Um ein neues Klassenbibliotheksprojekt zu erstellen, wählen Sie Datei>Neues>Projekt.
Wählen Sie C# in der Sprache-Dropdownliste aus.
Geben Sie im Suchfeld Klassenbibliothek ein. Wählen Sie erst Klassenbibliothek (.NET Framework) und dann Weiter aus.
Geben Sie im Dialogfeld den Namen MyFirstVisualizer ein und wählen Sie dann Erstellen aus.

Stellen Sie für das Schnellansichtsprojekt sicher, dass Sie eine .NET Framework-Klassenbibliothek und nicht .NET auswählen. Obwohl die Schnellansicht in .NET Framework vorliegen muss, kann es sich bei der aufrufenden App um eine .NET-App handeln.

Nachdem Sie die Klassenbibliothek erstellt haben, müssen Sie einen Verweis auf die Microsoft.VisualStudio.DebuggerVisualizers.DLL-Datei hinzufügen, damit Sie die dort definierten Klassen verwenden können. Bevor Sie den Verweis hinzufügen, müssen Sie einige Klassen umbenennen, um aussagekräftige Namen zu verwenden.

Benennen Sie Class1.cs um und fügen Sie Microsoft.VisualStudio.DebuggerVisualizers hinzu

Klicken Sie im Projektmappen-Explorermit der rechten Maustaste auf „Class1.cs“ und wählen Sie im Kontextmenü die Option Umbenennen aus.
Ändern Sie den Namen von Class1.cs in einen aussagekräftigeren Namen, zum Beispiel DebuggerSide.cs.

Hinweis

Visual Studio passt die Klassendeklaration in DebuggerSide.cs automatisch an den neuen Dateinamen an. Wenn eine Aufforderung zum Abschließen der Aktion angezeigt wird, wählen Sie Ja aus.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Verweise, und wählen Sie im Kontextmenü Verweis hinzufügen aus.
Wählen Sie im Dialogfeld Verweis hinzufügen auf der Registerkarte Durchsuchen den Eintrag Durchsuchen aus, und suchen Sie nach Microsoft.VisualStudio.DebuggerVisualizers.DLL.

Sie finden die DLL im Unterverzeichnis <Visual Studio-Installationsverzeichnis>\Common7\IDE\PublicAssemblies des Installationsverzeichnisses von Visual Studio.
Wählen Sie OK aus.
Fügen Sie in DebuggerSide.cs Folgendes zu den using-Anweisungen hinzu:
```
using Microsoft.VisualStudio.DebuggerVisualizers;
```

Jetzt können Sie den debuggerseitigen Code erstellen. Dieser Code wird im Debugger ausgeführt, um die Informationen anzuzeigen, die Sie visualisieren möchten. Zunächst müssen Sie die Deklaration des DebuggerSide Objekts ändern, um die Vererbung von der Basisklasse DialogDebuggerVisualizer zu konfigurieren.

Erbe von DialogDebuggerVisualizer

Gehen Sie in DebuggerSide.cs zu folgender Codezeile:
```
public class DebuggerSide
```

Ändern Sie den Code in:

public class DebuggerSide : DialogDebuggerVisualizer

Fügen Sie einen leeren Konstruktor hinzu, damit Sie dem Konstruktor der Basisklasse die Serialisierungsrichtlinie übergeben können, die für die Kommunikation zwischen den Visualizer-Komponenten verwendet werden soll.
```
public DebuggerSide() : base(FormatterPolicy.NewtonsoftJson) // or FormatterPolicy.Json
{
}
```
Hinweis

Aufgrund der Sicherheitsprobleme, die in Besondere Überlegungen zur Debuggerseite für .NET 5.0 und höher beschrieben sind, können Visualizer ab Visual Studio 2022 Version 17.11 die Legacy-Formatierungsrichtlinie nicht mehr angeben.
DialogDebuggerVisualizer verfügt über eine abstrakte Methode (Show), die Sie überschreiben müssen.

Überschreiben Sie die Methode DialogDebuggerVisualizer.Show

Fügen Sie die folgende Methode in public class DebuggerSide hinzu:

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

Die Show-Methode enthält den Code, der für das Erstellen des Dialogfelds der Schnellansicht oder eines anderen Benutzeroberflächenelements verantwortlich ist. Sie zeigt die Informationen an, die der Debugger an die Schnellansicht übergibt. Den Code, der das Dialogfeld erstellt und die Informationen anzeigt, müssen Sie hinzufügen. In dieser exemplarischen Vorgehensweise verwenden Sie ein Windows Forms-Meldungsfeld. Zunächst müssen Sie einen Verweis und eine using-Anweisung für System.Windows.Forms hinzufügen.

Fügen Sie System.Windows.Forms hinzu

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Verweise, und wählen Sie im Kontextmenü Verweis hinzufügen aus.
Wählen Sie im Dialogfeld Verweis hinzufügen auf der Registerkarte Durchsuchen die Option Durchsuchen aus, und suchen Sie nach System.Windows.Forms.DLL.

Sie finden die DLL unter C:\Windows\Microsoft.NET\Framework\v4.0.30319.
Wählen Sie OK aus.
Fügen Sie in DebuggerSide.cs Folgendes zu den using-Anweisungen hinzu:
```
using System.Windows.Forms;
```

Jetzt fügen Sie etwas Code hinzu, um die Benutzeroberfläche für Ihren Visualizer zu erstellen und anzuzeigen. Da es sich bei diesem Beispiel um Ihren ersten Visualizer handelt, können Sie die Benutzeroberfläche einfach halten und ein Nachrichtenfeld verwenden.

Die Visualizer-Ausgabe in einem Dialogfeld anzeigen

Fügen Sie der Show-Methode folgende Codezeile hinzu:
```
MessageBox.Show(objectProvider.GetObject().ToString());
```
Dieser Beispielcode enthält keine Fehlerbehandlung. Sie sollten eine Fehlerbehandlung in einen echten Visualizer oder jede andere Art von Anwendung integrieren.
Wählen Sie im Menü Erstellen die Option MyFirstVisualizer erstellen aus. Das Projekt sollte erfolgreich erstellt werden. Korrigieren Sie alle Buildfehler, bevor Sie fortfahren.

Der debuggerseitige Code ist jetzt abgeschlossen. Ein Schritt fehlt allerdings noch. Das Attribut, das der zu debuggenden Seite mitteilt, welche Auflistung von Klassen die Schnellansicht enthält.

Fügen Sie den Typ hinzu, der für den zu debuggenden Code visualisiert werden soll

Geben Sie den zu visualisierenden Typ (die Objektquelle) für die zu debuggende Komponente mit dem DebuggerVisualizerAttribute-Attribut im debuggerseitigen Code an. Die Target-Eigenschaft legt den zu visualisierenden Typ fest.

Fügen Sie DebuggerSide.cs den folgenden Attributcode hinzu, und zwar nach den using-Anweisungen und vor namespace MyFirstVisualizer:

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

Wählen Sie im Menü Erstellen die Option MyFirstVisualizer erstellen aus. Das Projekt sollte erfolgreich erstellt werden. Korrigieren Sie alle Buildfehler, bevor Sie fortfahren.

Damit ist das Erstellen Ihrer ersten Schnellansicht abgeschlossen. Wenn Sie alle Schritte richtig befolgt haben, können Sie die Schnellansicht problemlos erstellen und in Visual Studio installieren. Bevor Sie eine Schnellansicht in Visual Studio installieren, sollten Sie jedoch durch Tests sicherstellen, dass sie ordnungsgemäß funktioniert. Als Nächstes erstellen Sie eine Testumgebung, in der Sie die Schnellansicht ohne Installation in Visual Studio ausführen können.

Fügen Sie eine Testmethode zur Anzeige der Schnellansicht hinzu

Fügen Sie der public DebuggerSide-Klasse folgende Methode hinzu:

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

Wählen Sie im Menü Erstellen die Option MyFirstVisualizer erstellen aus. Das Projekt sollte erfolgreich erstellt werden. Korrigieren Sie alle Buildfehler, bevor Sie fortfahren.

Als Nächstes müssen Sie ein ausführbares Projekt erstellen, um die Schnellansichts-DLL aufzurufen. Verwenden Sie der Einfachheit halber ein Konsolenanwendungsprojekt.

Fügen Sie der Projektmappe ein Konsolenanwendungsprojekt hinzu

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Hinzufügen und wählen Sie dann Neues Projekt aus.
Klicken Sie auf Datei>Neu>Projekt. Wählen Sie C# in der Dropdownliste für die Sprache aus. Geben Sie im Suchfeld den Begriff Konsolen-App ein, und wählen Sie dann entweder Konsolen-App (.NET Framework) oder Konsolenanwendung für .NET aus. Wählen Sie Weiter aus. Geben Sie in dem daraufhin angezeigten Dialogfeld den Namen MyTestConsole ein und wählen Sie dann Erstellen aus.

Hinweis

Zum einfachen Testen der Schnellansicht mithilfe einer Testumgebung erstellen Sie eine .NET Framework-Konsolen-App. Sie können stattdessen auch eine .NET-Konsolen-App erstellen, aber die weiter unten beschriebene Testumgebung wird für .NET noch nicht unterstützt, und Sie müssen deshalb zum Testen die Schnellansicht installieren. Erstellen Sie für eine .NET-Konsolen-App zunächst die Konsolen-App hier, fügen Sie die erforderliche DLL sowie Projektverweise hinzu, und befolgen Sie dann die unter Hinzufügen eines debugseitigen Datenobjekts beschriebenen Schritte. Informationen zu ASP.NET Core-Szenarien finden Sie unter Besondere Überlegungen zur Debuggerseite für .NET 5.0 und höher.

Jetzt müssen Sie die notwendigen Verweise hinzufügen, damit MyFirstVisualizer von MyTestConsole aufgerufen werden kann.

Fügen Sie MyTestConsole die erforderlichen Verweise hinzu

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf MyTestConsole, und wählen Sie im Kontextmenü Verweis hinzufügen aus.
Im Dialogfeld Verweis hinzufügen öffnen Sie die Registerkarte Durchsuchen und wählen Sie dann „Microsoft.VisualStudio.DebuggerVisualizers.DLL“ aus.
Wählen Sie OK aus.
Klicken Sie mit der rechten Maustaste auf MyTestConsole, und klicken Sie erneut auf Verweis hinzufügen.
Im Dialogfeld Verweis hinzufügen öffnen Sie die Registerkarte Projekte und wählen Sie dann „MyFirstVisualizer“ aus.
Wählen Sie OK aus.

Fügen Sie nun den Code hinzu, um die Testumgebung fertigzustellen.

Fügen Sie MyTestConsole Code hinzu

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Program.cs, und wählen Sie im Kontextmenü Umbenennen aus.
Vergeben Sie für den Namen Program.cs eine aussagekräftigere Bezeichnung, zum Beispiel TestConsole.cs.

Hinweis

Visual Studio passt die Klassendeklaration in TestConsole.cs automatisch an den neuen Dateinamen an.
Fügen Sie in TestConsole.cs den using-Anweisungen den folgenden Code hinzu:
```
using MyFirstVisualizer;
```

Fügen Sie der Main-Methode den folgenden Code hinzu:

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

Jetzt können Sie Ihre erste Schnellansicht testen.

Testen Sie die Schnellansicht

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf MyTestConsole, und wählen Sie im Kontextmenü Als Startprojekt festlegen aus.
Wählen Sie im Menü Debuggen den Befehl Starten aus.

Die Konsolenanwendung wird gestartet und die Schnellansicht mit der Zeichenfolge "Hello, World" angezeigt.

Herzlichen Glückwunsch! Sie haben Ihre erste Schnellansicht erstellt und getestet!

Wenn Sie die Schnellansicht in Visual Studio und nicht nur innerhalb der Testumgebung verwenden möchten, dann müssen Sie sie installieren. Weitere Informationen finden Sie unter Vorgehensweise: Install a Visualizer (Vorgehensweise: Installieren einer Schnellansicht).

Hinzufügen eines debugseitigen Datenobjekts

In diesem Abschnitt wechseln Sie vom Datenobjekt System.String zu einem benutzerdefinierten Datenobjekt.

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Hinzufügen und wählen Sie dann Neues Projekt aus. Wählen Sie C# in der Dropdownliste für die Sprache aus. Geben Sie im Suchfeld den Begriff Klassenbibliothek ein, und wählen Sie dann entweder Klassenbibliothek (.NET Framework) oder Klassenbibliothek für .NET Standard aus.

Hinweis

Wenn Sie eine .NET Framework-Testkonsolen-App verwenden, stellen Sie sicher, dass Sie ein .NET Framework-Klassenbibliotheksprojekt erstellen.
Wählen Sie Weiter aus. Geben Sie in dem daraufhin angezeigten Dialogfeld den Namen MyDataObject ein und wählen Sie dann Erstellen aus.
(Nur für .NET Standard-Klassenbibliothek) Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Projektdatei bearbeiten aus. Ändern Sie den <TargetFramework>-Wert in netstandard2.0.
```
<TargetFramework>netstandard2.0</TargetFramework>
```
Ersetzen Sie im MyDataObject-Namespace den Standardcode durch den folgenden Code.
```
[Serializable] 
public class CustomDataObject
{
   public CustomDataObject()
   {
      this.MyData = "MyTestData";
   }
   public string MyData { get; set; }
}
```
Für eine schreibgeschützte Schnellansicht wie in diesem Beispiel ist es nicht erforderlich, Methoden von VisualizerObjectSource zu implementieren.

Als Nächstes aktualisieren Sie das MyFirstVisualizer-Projekt, um das neue Datenobjekt zu verwenden.
Klicken Sie im Projektmappen-Explorer unter dem MyFirstVisualizer-Projekt mit der rechten Maustaste auf den Knoten Verweise, und wählen Sie Verweis hinzufügen aus.
Wählen Sie unter Projekte das Projekt MyDataObject aus.
Aktualisieren Sie im Attributcode von DebuggerSide.cs den Wert für „Target“, und ändern Sie System.String in MyDataObject.CustomDataObject.
```
Target = typeof(MyDataObject.CustomDataObject),
```
Ersetzen Sie im MyFirstVisualizer-Projekt den Code für die Show-Methode durch den folgenden Code.
```
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);
```
Der Code oben verwendet eine Eigenschaft des Datenobjekts zur Anzeige im Titel des Windows Forms-Elements.

Als Nächstes aktualisieren Sie die Konsolen-App, um das benutzerdefinierte Datenobjekt zu verwenden.
Klicken Sie im Projektmappen-Explorer unter dem MyTestConsole-Projekt mit der rechten Maustaste auf den Knoten Verweise oder Abhängigkeiten, und fügen Sie einen Projektverweis auf MyDataObject hinzu.

Ersetzen Sie in Program.cs den Code in der Main-Methode durch den folgenden Code.

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

DebuggerSide.TestShowVisualizer(customDataObject);

(.NET-Konsolen-App) Schließen Sie den Aufruf von TestShowVisualizer in eine try-catch-Anweisung ein, da die Testumgebung nicht unterstützt wird.
```
try
{
      DebuggerSide.TestShowVisualizer(customDataObject);
}
catch (Exception) {
}
```
Die Konsolen-App benötigt einen Runtimeverweis auf die Schnellansicht. Sie können den Verweis verwalten, indem Sie den vorangehenden Code behalten, anstatt ihn auszukommentieren.
Für eine .NET Framework-Konsolen-App können Sie die Testumgebung ausführen (F5 drücken) oder den Anweisungen unter Installieren einer Schnellansicht folgen.

Wenn Sie die App mithilfe der Testumgebung ausführen, zeigt die App das Windows Forms-Element an.
Für eine .NET-Konsolen-App kopieren Sie MyFirstVisualizer.dll und MyDataObject.dll in die unter Installieren einer Schnellansicht beschriebenen Ordner.
Legen Sie nach der Installation der Schnellansicht einen Haltepunkt fest, führen Sie die Konsolen-App aus, und zeigen Sie auf customDataObject. Wenn alles ordnungsgemäß eingerichtet ist, sollte das Lupensymbol angezeigt werden.

Wenn Sie MyFirstVisualizer über das Lupensymbol auswählen, sehen Sie das Formular mit dem Text des Datenobjekts im Titel.

Freigeben über

Exemplarische Vorgehensweise: Schreiben einer Schnellansicht in C#

Manuelles Erstellen einer Schnellansicht

Erstellen eines Klassenbibliotheksprojekts

Benennen Sie Class1.cs um und fügen Sie Microsoft.VisualStudio.DebuggerVisualizers hinzu

Erbe von DialogDebuggerVisualizer

Überschreiben Sie die Methode DialogDebuggerVisualizer.Show

Fügen Sie System.Windows.Forms hinzu

Die Visualizer-Ausgabe in einem Dialogfeld anzeigen

Fügen Sie den Typ hinzu, der für den zu debuggenden Code visualisiert werden soll

Fügen Sie eine Testmethode zur Anzeige der Schnellansicht hinzu

Fügen Sie der Projektmappe ein Konsolenanwendungsprojekt hinzu

Fügen Sie MyTestConsole die erforderlichen Verweise hinzu

Fügen Sie MyTestConsole Code hinzu

Testen Sie die Schnellansicht

Hinzufügen eines debugseitigen Datenobjekts

Feedback

Zusätzliche Ressourcen

Freigeben über

Exemplarische Vorgehensweise: Schreiben einer Schnellansicht in C#

Manuelles Erstellen einer Schnellansicht

Erstellen eines Klassenbibliotheksprojekts

Benennen Sie Class1.cs um und fügen Sie Microsoft.VisualStudio.DebuggerVisualizers hinzu

Erbe von DialogDebuggerVisualizer

Überschreiben Sie die Methode DialogDebuggerVisualizer.Show

Fügen Sie System.Windows.Forms hinzu

Die Visualizer-Ausgabe in einem Dialogfeld anzeigen

Fügen Sie den Typ hinzu, der für den zu debuggenden Code visualisiert werden soll

Fügen Sie eine Testmethode zur Anzeige der Schnellansicht hinzu

Fügen Sie der Projektmappe ein Konsolenanwendungsprojekt hinzu

Fügen Sie MyTestConsole die erforderlichen Verweise hinzu

Fügen Sie MyTestConsole Code hinzu

Testen Sie die Schnellansicht

Hinzufügen eines debugseitigen Datenobjekts

Zugehöriger Inhalt

Feedback

Zusätzliche Ressourcen