Exemplarische Vorgehensweise: Schreiben eines Visualisierers in C#

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.

In dieser exemplarischen Vorgehensweise wird gezeigt, wie Sie mithilfe von C# eine einfache Visualisierung schreiben. Die Visualisierung, die Sie in dieser Schritt-für-Schritt-Anleitung erstellen, zeigt den Inhalt eines Strings mithilfe eines Windows Forms an. Diese einfache Zeichenfolgenschnellansicht ist nicht besonders nützlich, zeigt aber die grundlegenden Schritte an, die Sie ausführen müssen, um nützlichere Visualisierungen für andere Datentypen zu erstellen.

Hinweis

Die angezeigten Dialogfelder und Menübefehle unterscheiden sich je nach aktiven Einstellungen oder Edition möglicherweise von den in der Hilfe beschriebenen Befehlen. Um Ihre Einstellungen zu ändern, wechseln Sie zum Menü "Extras ", und wählen Sie " Import- und Exporteinstellungen" aus. Weitere Informationen finden Sie unter "Einstellungen zurücksetzen".

Visualr-Code muss in einer DLL-Datei platziert werden, die der Debugger liest. Daher besteht der erste Schritt darin, ein Klassenbibliotheksprojekt für die DLL zu erstellen.

Manuelles Erstellen einer Visualisierung

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

Erstellen eines Klassenbibliotheksprojekts

1. Um ein neues Klassenbibliotheksprojekt zu erstellen, wählen Sie Datei>Neu>Projekt aus.

2. Wählen Sie in der Dropdownliste "Sprache" C# aus.

3. Geben Sie im Suchfeld die Klassenbibliothek ein. Wählen Sie "Klassenbibliothek(.NET Framework)" und dann "Weiter" aus.

4. Geben Sie im Dialogfeld den Namen MyFirstVisualizerein, und wählen Sie dann "Erstellen" aus.

Stellen Sie für das Visualisierungsprojekt sicher, dass Sie eine .NET Framework-Klassenbibliothek und nicht .NET auswählen. Obwohl die Visualisierung .NET Framework sein muss, kann die aufrufende App .NET sein.

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.

Umbenennen Class1.cs und Hinzufügen von Microsoft.VisualStudio.DebuggerVisualizers

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Class1.cs, und wählen Sie im Kontextmenü "Umbenennen" aus.

2. Ändern Sie den Namen von Class1.cs in einen aussagekräftigen Namen, z. B. DebuggerSide.cs.

   Hinweis

   Visual Studio ändert die Klassendeklaration in DebuggerSide.cs automatisch so, dass sie mit dem neuen Dateinamen übereinstimmt. Wenn eine Aufforderung zum Abschließen der Aktion angezeigt wird, wählen Sie "Ja" aus.

3. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Verweise , und wählen Sie im Kontextmenü " Verweis hinzufügen " aus.

4. Wählen Sie im Dialogfeld " Verweis hinzufügen " auf der Registerkarte " Durchsuchen " die Option "Durchsuchen" aus, und suchen Sie die Microsoft.VisualStudio.DebuggerVisualizers.DLL.

   Sie finden die DLL in <Visual Studio Install Directory>\Common7\IDE\PublicAssemblies-Unterverzeichnis des Installationsverzeichnisses von Visual Studio.

5. Wählen Sie OK aus.

6. Fügen Sie in DebuggerSide.cs Folgendes zu den using-Direktiven 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 DialogDebuggerVisualizerzu konfigurieren.

Von DialogDebuggerVisualizer erben

1. Wechseln Sie in DebuggerSide.cs zur folgenden Codezeile:

   public class DebuggerSide
   

2. Ändert den Code auf:

   public class DebuggerSide : DialogDebuggerVisualizer
   

3. Fügen Sie einen leeren Konstruktor hinzu, damit Sie den Konstruktor der Basisklasse an die Serialisierungsrichtlinie übergeben können, die für die Kommunikation zwischen den Visualisierungskomponenten verwendet wird.

   public DebuggerSide() : base(FormatterPolicy.NewtonsoftJson) // or FormatterPolicy.Json
   {
   }
   

   Hinweis

   Aufgrund der sicherheitsrelevanten Probleme, die in speziellen Debugger-Seitenüberlegungen für .NET 5.0+ beschrieben werden, können Visual Studio 2022 Version 17.11 Visualisierer nicht mehr die Legacy Formatierrichtlinie festlegen.

4. DialogDebuggerVisualizer verfügt über eine abstrakte Methode (Show), die Sie überschreiben müssen.

Überschreiben der DialogDebuggerVisualizer.Show-Methode

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

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

Die Show Methode enthält den Code, der tatsächlich das Dialogfeld "Visualizer" oder eine andere Benutzeroberfläche erstellt und die Informationen anzeigt, die vom Debugger an die Visualisierung übergeben wurden. Sie müssen den Code hinzufügen, der das Dialogfeld erstellt und die Informationen anzeigt. In dieser exemplarischen Vorgehensweise verwenden Sie ein Windows Forms-Meldungsfeld. Zunächst müssen Sie einen Verweis und eine using-Direktive für System.Windows.Forms hinzufügen.

Hinzufügen von System.Windows.Forms

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Verweise , und wählen Sie im Kontextmenü " Verweis hinzufügen " aus.

2. Wählen Sie im Dialogfeld " Verweis hinzufügen " auf der Registerkarte " Durchsuchen " die Option "Durchsuchen" aus, und suchen Sie die System.Windows.Forms.DLL.

   Sie finden die DLL in C:\Windows\Microsoft.NET\Framework\v4.0.30319.

3. Wählen Sie OK aus.

4. Fügen Sie in DebuggerSide.cs Folgendes zu den using-Direktiven hinzu:

   using System.Windows.Forms;
   

Jetzt fügen Sie Code zum Erstellen und Anzeigen der Benutzeroberfläche für Ihre Visualisierung hinzu. Da es sich bei diesem Beispiel um Ihre erste Visualisierung handelt, können Sie die Benutzeroberfläche einfach halten und ein Meldungsfeld verwenden.

Anzeigen der Visualizer-Ausgabe in einem Dialogfeld

1. Fügen Sie in der Show Methode die folgende Codezeile hinzu:

   MessageBox.Show(objectProvider.GetObject().ToString());
   

   Dieser Beispielcode enthält keine Fehlerbehandlung. Sie sollten die Fehlerbehandlung in eine echte Visualisierung oder einen anderen Anwendungstyp einschließen.

2. 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. Es gibt jedoch einen weiteren Schritt: das Attribut, das der Debuggee-Seite mitteilt, aus welcher Sammlung von Klassen der Visualizer besteht.

Fügen Sie den Typ hinzu, der für den debuggeeseitigen Code visualisiert werden soll.

Im Code auf der Debugger-Seite geben Sie den Typ an, der für die Visualisierung des Debuggees, also die Objektquelle, mithilfe des DebuggerVisualizerAttribute Attributs verwendet werden soll. Die Target Eigenschaft legt den Typ fest, der visualisiert werden soll.

1. Fügen Sie den folgenden Attributcode zu DebuggerSide.cs, nach den using Direktiven, aber vor namespace MyFirstVisualizer:

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

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

   An diesem Punkt ist Ihre erste Visualisierung abgeschlossen. Wenn Sie die Schritte richtig ausgeführt haben, können Sie die Visualisierung erstellen und in Visual Studio installieren. Bevor Sie eine Visualisierung in Visual Studio installieren, sollten Sie sie jedoch testen, um sicherzustellen, dass sie ordnungsgemäß ausgeführt wird. Sie erstellen jetzt eine Testumgebung, um die Visualisierung auszuführen, ohne sie in Visual Studio zu installieren.

Hinzufügen einer Testmethode zum Anzeigen der Visualisierung

1. Fügen Sie der Klasse public DebuggerSidedie folgende Methode hinzu:

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

2. 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 Visualizer-DLL aufzurufen. Verwenden Sie aus Gründen der Einfachheit ein Konsolenanwendungsprojekt.

Hinzufügen eines Konsolenanwendungsprojekts zur Lösung

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Projektmappe, wählen Sie "Hinzufügen" und dann "Neues Projekt" aus.

2. Wählen Sie "Datei>Neu>Projekt" aus. Wählen Sie in der Dropdownliste "Sprache" die Option "C#" aus. Geben Sie im Suchfeld Konsolen-App ein, und wählen Sie dann entweder Konsolen-App (.NET Framework) oder Konsolenanwendung für .NET aus. Wählen Sie Weiteraus. Geben Sie im daraufhin angezeigten Dialogfeld den Namen MyTestConsoleein, und wählen Sie dann "Erstellen" aus.

Hinweis

Wenn Sie die Visualisierung einfach mithilfe einer Testumgebung testen möchten, erstellen Sie eine .NET Framework-Konsolen-App. Sie können stattdessen eine .NET-Konsolen-App erstellen, aber die weiter unten beschriebene Testumgebung wird für .NET noch nicht unterstützt. Daher müssen Sie die Visualisierung installieren, um sie zu testen. Erstellen Sie für eine .NET-Konsolen-App zuerst die Konsolen-App hier, fügen Sie die erforderlichen DLL- und Projektverweise hinzu, und führen Sie dann die schritte aus, die unter Hinzufügen eines debuggeeseitigen Datenobjekts beschrieben sind. Informationen zu ASP.NET Core-Szenarien finden Sie in speziellen Debugger-Seitenüberlegungen für .NET 5.0+.

Jetzt müssen Sie die erforderlichen Verweise hinzufügen, damit MyTestConsole MyFirstVisualizer aufrufen kann.

Hinzufügen erforderlicher Verweise auf MyTestConsole

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf "MyTestConsole ", und wählen Sie im Kontextmenü " Verweis hinzufügen " aus.

2. Öffnen Sie im Dialogfeld " Verweis hinzufügen " die Registerkarte " Durchsuchen ", und wählen Sie Microsoft.VisualStudio.DebuggerVisualizers.DLL aus.

3. Wählen Sie OK aus.

4. Klicken Sie mit der rechten Maustaste auf "MyTestConsole ", und wählen Sie erneut "Verweis hinzufügen" aus.

5. Öffnen Sie im Dialogfeld " Verweis hinzufügen " die Registerkarte "Projekte ", und wählen Sie "MyFirstVisualizer" aus.

6. Wählen Sie OK aus.

Jetzt fügen Sie den Code hinzu, um das Testgerüst abzuschließen.

Hinzufügen von Code zu MyTestConsole

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Program.cs, und wählen Sie im Kontextmenü "Umbenennen" aus.

2. Ändern Sie den Namen von Program.cs in einen aussagekräftigeren Namen, z. B. TestConsole.cs.

   Hinweis

   Visual Studio ändert die Klassendeklaration in TestConsole.cs automatisch so, dass sie mit dem neuen Dateinamen übereinstimmt.

3. Fügen Sie in TestConsole.cs den Direktiven den folgenden Code hinzu using :

   using MyFirstVisualizer;
   

4. Fügen Sie in der Methode Mainden folgenden Code hinzu:

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

Jetzt können Sie Ihre erste Visualisierung testen.

Testen des Visualizers

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf "MyTestConsole ", und wählen Sie im Kontextmenü " Als Startprojekt festlegen " aus.

2. Wählen Sie im Menü " Debuggen " die Option "Start" aus.

   Die Konsolenanwendung wird gestartet, und der Visualizer wird angezeigt und zeigt die Zeichenkette "Hello, World" an.

Glückwunsch. Sie haben Ihren ersten Visualizer erstellt und getestet!

Wenn Sie Ihren Visualizer in Visual Studio verwenden möchten, statt es einfach nur aus der Testumgebung aufzurufen, müssen Sie ihn installieren. Weitere Informationen finden Sie unter How to: Install a Visualizer.

Hinzufügen eines debuggeeseitigen Datenobjekts

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

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Projektmappe, wählen Sie "Hinzufügen" und dann "Neues Projekt" aus. Wählen Sie in der Dropdownliste "Sprache" die Option "C#" aus. Geben Sie im Suchfeld 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.

2. Wählen Sie Weiteraus. Geben Sie im daraufhin angezeigten Dialogfeld den Namen MyDataObjectein, und wählen Sie dann "Erstellen" aus.

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

4. MyDataObject Ersetzen Sie im 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 Visualisierung, z. B. in diesem Beispiel, ist es nicht erforderlich, Methoden von VisualizerObjectSource zu implementieren.

   Aktualisieren Sie als Nächstes das MyFirstVisualizer-Projekt, um das neue Datenobjekt zu verwenden.

5. Klicken Sie im Projektmappen-Explorer unter dem Projekt MyFirstVisualizer mit der rechten Maustaste auf den Knoten "Verweise", und wählen Sie "Verweis hinzufügen" aus.

6. Wählen Sie unter "Projekte" das Projekt "MyDataObject" aus.

7. Aktualisieren Sie im Attributcode von DebuggerSide.cs den Zielwert, und ändern Sie den Wert System.String in MyDataObject.CustomDataObject.

   Target = typeof(MyDataObject.CustomDataObject),
   

8. 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 vorangehende Code verwendet eine Eigenschaft des Datenobjekts, um im Titel des Formulars anzuzeigen.

   Aktualisieren Sie als Nächstes die Konsolen-App, um das benutzerdefinierte Datenobjekt zu verwenden.

9. Klicken Sie im Projektmappen-Explorer unter dem Projekt MyTestConsole mit der rechten Maustaste auf den Knoten "Verweise " oder "Abhängigkeiten" , und fügen Sie einen Projektverweis hinzu MyDataObject.

10. 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);
    

11. (.NET-Konsolen-App) Schließen Sie den Aufruf TestShowVisualizer in eine Try-Catch-Anweisung ein, da das Test-Harness nicht unterstützt wird.

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

    Die Konsolen-App benötigt einen Laufzeitverweis auf den Visualizer. Sie können den Verweis beibehalten, indem Sie den vorhergehenden Code behalten, anstatt ihn auszukommentieren.

12. Für eine .NET Framework-Konsolen-App können Sie die Testumgebung ausführen (drücken Sie F5), oder Sie können die Anweisungen unter "How to: Install a Visualizer" befolgen.

    Wenn Sie die App mit dem Test-Harness ausführen, zeigt die App das Windows Form an.

13. Kopieren Sie für eine .NET-Konsolen-App die MyFirstVisualizer.dll und MyDataObject.dll in die Verzeichnisse, die in How to: Install a Visualizer beschrieben sind.

14. Legen Sie nach der Installation des Visualizers einen Haltepunkt fest, führen Sie die Konsolen-App aus, und fahren Sie mit der Maus über customDataObject. Wenn alles richtig eingerichtet ist, sollten Sie das Lupensymbol sehen.

    

    Wenn Sie "MyFirstVisualizer" aus der Lupe auswählen, wird das Formular mit dem Datenobjekttext im Titel angezeigt.

    

Verwandte Inhalte

• Visualizer-Architektur
• How to: Install a Visualizer
• Erstellen von benutzerdefinierten Visualisierungen