Przewodnik: pisanie wizualizatora w języku C#

2025-06-27

Ważne

Począwszy od Visual Studio 2022 w wersji 17.9, wizualizatory można teraz pisać na platformie .NET 6.0+, które działają poza procesem przy użyciu nowego modelu VisualStudio.Extensibility. Aby uzyskać rozszerzenia utworzone przy użyciu nowego modelu, zobacz dokumentację w temacie Tworzenie wizualizatorów debugera programu Visual Studio . Jeśli potrzebujesz obsługiwać starsze wersje programu Visual Studio lub chcesz dostarczyć niestandardowe wizualizatory w ramach biblioteki DLL, skorzystaj z informacji w tym artykule, które dotyczą tylko starszego modelu programowania rozszerzeń (VSSDK).

W tym przewodniku pokazano, jak napisać prosty wizualizator przy użyciu języka C#. Wizualizator utworzony w tym przewodniku wyświetla zawartość ciągu przy użyciu formularza systemu Windows. Ten prosty wizualizator ciągów nie jest szczególnie przydatny w sobie, ale pokazuje podstawowe kroki, które należy wykonać, aby utworzyć bardziej przydatne wizualizatory dla innych typów danych.

Uwaga / Notatka

Wyświetlane okna dialogowe i polecenia menu mogą różnić się od poleceń opisanych w pomocy, w zależności od aktywnych ustawień lub edycji. Aby zmienić ustawienia, przejdź do menu Narzędzia i wybierz pozycję Importuj i Eksportuj ustawienia. Aby uzyskać więcej informacji, zobacz Resetowanie ustawień.

Kod wizualizatora musi zostać umieszczony w pliku DLL odczytanym przez debuger. W związku z tym pierwszym krokiem jest utworzenie projektu biblioteki klas dla biblioteki DLL.

Ręczne tworzenie wizualizatora

Wykonaj następujące zadania, aby utworzyć wizualizator.

Tworzenie projektu biblioteki klas

Aby utworzyć nowy projekt biblioteki klas, wybierz pozycję Plik>nowy>projekt.
Z listy rozwijanej języka wybierz pozycję C#.
W polu wyszukiwania wprowadź bibliotekę klas. Wybierz pozycję Biblioteka klas (.NET Framework), a następnie wybierz pozycję Dalej.
W oknie dialogowym wprowadź nazwę MyFirstVisualizer, a następnie wybierz pozycję Utwórz.

W przypadku projektu wizualizatora upewnij się, że wybrano bibliotekę klas programu .NET Framework, a nie .NET. Mimo że wizualizator musi być platformą .NET Framework, aplikacja wywołująca może być platformą .NET.

Po utworzeniu biblioteki klas należy dodać odwołanie do Microsoft.VisualStudio.DebuggerVisualizers.DLL pliku, aby można było używać zdefiniowanych tam klas. Przed dodaniem odwołania należy zmienić nazwę niektórych klas, aby używać znaczących nazw.

Zmień nazwę Class1.cs i dodaj microsoft.VisualStudio.DebuggerVisualizers

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy Class1.cs i wybierz polecenie Zmień nazwę w menu kontekstowym.
Zmień nazwę z Class1.cs na coś znaczącego, takiego jak DebuggerSide.cs.

Uwaga / Notatka

Program Visual Studio automatycznie zmienia deklarację klasy w DebuggerSide.cs, aby pasować do nowej nazwy pliku. Jeśli zostanie wyświetlony monit o ukończenie akcji, wybierz pozycję Tak.
W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy pozycję Odwołania i wybierz polecenie Dodaj odwołanie w menu skrótów.
W oknie dialogowym Dodawanie odwołania na karcie Przeglądaj wybierz pozycję Przeglądaj i znajdź Microsoft.VisualStudio.DebuggerVisualizers.DLL.

Bibliotekę DLL można znaleźć w <katalogu instalacyjnym programu Visual Studio>\Common7\IDE\PublicAssemblies katalogu instalacyjnego programu Visual Studio.
Kliknij przycisk OK.
W DebuggerSide.cs dodaj następujące elementy do using dyrektyw:
```
using Microsoft.VisualStudio.DebuggerVisualizers;
```

Teraz możesz utworzyć kod po stronie debugera. Ten kod jest uruchamiany w debugerze, aby wyświetlić informacje, które chcesz zwizualizować. Najpierw należy zmienić deklarację DebuggerSide obiektu, aby skonfigurować dziedziczenie z klasy DialogDebuggerVisualizerbazowej .

Dziedzicz po DialogDebuggerVisualizer

W DebuggerSide.cs przejdź do następującego wiersza kodu:
```
public class DebuggerSide
```

Zmień kod na:

public class DebuggerSide : DialogDebuggerVisualizer

Dodaj pusty konstruktor, aby można było przekazać do konstruktora klasy bazowej zasady serializacji, które będą używane do komunikacji między składnikami wizualizatora.
```
public DebuggerSide() : base(FormatterPolicy.NewtonsoftJson) // or FormatterPolicy.Json
{
}
```
Uwaga / Notatka

Ze względu na problemy z zabezpieczeniami opisane w sekcji Specjalne zagadnienia po stronie debugera dla platformy .NET 5.0 lub nowszej, począwszy od programu Visual Studio 2022 w wersji 17.11, wizualizatory nie będą mogły określić Legacy zasad formatatora.
DialogDebuggerVisualizer ma jedną metodę abstrakcyjną (Show), którą należy zastąpić.

Przesłoń metodę DialogDebuggerVisualizer.Show

W public class DebuggerSidepliku dodaj następującą metodę:

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

Metoda Show zawiera kod, który faktycznie tworzy okno dialogowe wizualizatora lub inny interfejs użytkownika i wyświetla informacje przekazane do wizualizatora z debugera. Należy dodać kod, który tworzy okno dialogowe i wyświetlać informacje. W tym przewodniku użyjesz pola komunikatu Windows Forms. Najpierw należy dodać odwołanie i using dyrektywę dla elementu System.Windows.Forms.

Dodawanie elementu System.Windows.Forms

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy pozycję Odwołania i wybierz polecenie Dodaj odwołanie w menu skrótów.
W oknie dialogowym Dodawanie odwołania na karcie Przeglądaj wybierz opcję Przeglądaj i znajdź System.Windows.Forms.DLL.

Bibliotekę DLL można znaleźć w folderze C:\Windows\Microsoft.NET\Framework\v4.0.30319.
Kliknij przycisk OK.
W pliku DebuggerSide.cs dodaj następujące dyrektywy using:
```
using System.Windows.Forms;
```

Teraz dodasz kod umożliwiający utworzenie i wyświetlenie interfejsu użytkownika dla wizualizatora. Ponieważ ten przykład jest pierwszym wizualizatorem, możesz zachować prosty interfejs użytkownika i użyć pola komunikatów.

Wyświetlanie danych wyjściowych wizualizatora w oknie dialogowym

W metodzie Show dodaj następujący wiersz kodu:
```
MessageBox.Show(objectProvider.GetObject().ToString());
```
Ten przykładowy kod nie zawiera obsługi błędów. Należy uwzględnić obsługę błędów w rzeczywistym wizualizatorze lub innym typie aplikacji.
W menu Kompilacja wybierz pozycję Kompiluj MyFirstVisualizer. Projekt powinien pomyślnie zostać skompilowany. Przed kontynuowaniem popraw wszelkie błędy kompilacji.

Kod po stronie debugera został ukończony. Jednakże, jest jeszcze jeden krok; to atrybut, który informuje stronę debugowanego, która kolekcja klas tworzy wizualizator.

Dodaj typ do wizualizacji kodu po stronie debugowanej.

W kodzie po stronie debugera należy określić typ do wizualizacji (źródła obiektu) debuggee przy użyciu atrybutu DebuggerVisualizerAttribute . Właściwość Target ustawia typ do wizualizacji.

Dodaj następujący kod atrybutu w pliku DebuggerSide.cs po dyrektywach using, ale przed namespace MyFirstVisualizer.

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

W menu Kompilacja wybierz pozycję Kompiluj MyFirstVisualizer. Projekt powinien pomyślnie zostać skompilowany. Przed kontynuowaniem popraw wszelkie błędy kompilacji.

Na tym etapie pierwszy wizualizator jest gotowy. Jeśli wykonano kroki prawidłowo, możesz skompilować wizualizator i zainstalować go w programie Visual Studio. Przed zainstalowaniem wizualizatora w programie Visual Studio należy go jednak przetestować, aby upewnić się, że działa prawidłowo. Teraz utworzysz uprzężę testową, aby uruchomić wizualizator bez instalowania go w programie Visual Studio.

Dodaj metodę testową, aby pokazać wizualizator

Dodaj następującą metodę do klasy public DebuggerSide:

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

W menu Kompilacja wybierz pozycję Kompiluj MyFirstVisualizer. Projekt powinien pomyślnie zostać skompilowany. Przed kontynuowaniem popraw wszelkie błędy kompilacji.

Następnie należy utworzyć projekt wykonywalny w celu wywołania biblioteki DLL wizualizatora. Dla uproszczenia użyj projektu Aplikacja konsolowa.

Dodawanie projektu aplikacji konsolowej do rozwiązania

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy rozwiązanie, wybierz polecenie Dodaj, a następnie wybierz pozycję Nowy projekt.
Wybierz Plik>Nowy>Projekt. Z listy rozwijanej języka wybierz pozycję C#. W polu wyszukiwania wpisz aplikacja konsolowa, a następnie wybierz pozycję Aplikacja konsolowa (.NET Framework) lub Aplikacja konsolowa dla .NET. Wybierz Dalej. W wyświetlonym oknie dialogowym wpisz nazwę MyTestConsole, a następnie wybierz pozycję Utwórz.

Uwaga / Notatka

Jeśli chcesz łatwo przetestować wizualizator przy użyciu uprzęży testowej, utwórz aplikację konsolową platformy .NET Framework. Zamiast tego możesz utworzyć aplikację konsolową dla platformy .NET, ale opisane później środowisko testowe nie jest jeszcze obsługiwane dla platformy .NET, dlatego musisz zainstalować wizualizator, aby je przetestować. W przypadku aplikacji konsolowej platformy .NET najpierw utwórz aplikację konsolową tutaj, dodaj wymaganą bibliotekę DLL i odwołania do projektu, a następnie wykonaj kroki opisane w temacie Dodawanie obiektu danych po stronie debugowania. Aby zapoznać się z scenariuszami ASP.NET Core, zobacz Specjalne zagadnienia dotyczące strony debugera dla platformy .NET 5.0 lub nowszej.

Teraz należy dodać niezbędne odwołania, aby aplikacja MyTestConsole mogła wywołać metodę MyFirstVisualizer.

Dodaj niezbędne referencje do MyTestConsole

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy pozycję MyTestConsole i wybierz polecenie Dodaj odwołanie w menu skrótów.
W oknie dialogowym Dodawanie odwołania otwórz kartę Przeglądaj i wybierz plik Microsoft.VisualStudio.DebuggerVisualizers.DLL.
Kliknij przycisk OK.
Kliknij prawym przyciskiem myszy pozycję MyTestConsole i ponownie wybierz polecenie Dodaj odwołanie .
W oknie dialogowym Dodawanie odwołania przejdź do karty Projekty i wybierz MyFirstVisualizer.
Kliknij przycisk OK.

Teraz dodasz kod w celu zakończenia środowiska testowego.

Dodaj kod do MyTestConsole

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy Program.cs i wybierz polecenie Zmień nazwę w menu skrótów.
Zmodyfikuj nazwę z Program.cs na coś bardziej znaczącego, takiego jak TestConsole.cs.

Uwaga / Notatka

Program Visual Studio automatycznie zmienia deklarację klasy w TestConsole.cs, aby pasować do nowej nazwy pliku.
W TestConsole.cs dodaj następujący kod do using dyrektyw:
```
using MyFirstVisualizer;
```

W metodzie Maindodaj następujący kod:

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

Teraz możesz przetestować swój pierwszy wizualizator.

Testowanie wizualizatora

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy pozycję MyTestConsole i wybierz polecenie Ustaw jako projekt startowy w menu skrótów.
W menu debugowania wybierz pozycję Start.

Aplikacja konsolowa zostanie uruchomiona i pojawi się wizualizator i wyświetli ciąg "Hello, World".

Gratulacje. Udało Ci się skompilować i przetestować swój pierwszy wizualizator!

Jeśli chcesz użyć wizualizatora w programie Visual Studio, a nie tylko wywołania go z uprzęży testowej, musisz go zainstalować. Aby uzyskać więcej informacji, zobacz How to: Install a Visualizer (Instrukcje: instalowanie wizualizatora).

Dodawanie obiektu danych po stronie debugowania

W tej sekcji przełączysz się z System.String obiektu danych na niestandardowy obiekt danych.

W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy rozwiązanie, wybierz polecenie Dodaj, a następnie wybierz pozycję Nowy projekt. Z listy rozwijanej języka wybierz pozycję C#. W polu wyszukiwania wpisz bibliotekę klas, a następnie wybierz pozycję Biblioteka klas (.NET Framework) lub Biblioteka klas dla platformy .NET Standard.

Uwaga / Notatka

Jeśli używasz aplikacji konsolowej .NET Framework, upewnij się, że utworzono projekt biblioteki klas programu .NET Framework.
Wybierz Dalej. W wyświetlonym oknie dialogowym wpisz nazwę MyDataObject, a następnie wybierz pozycję Utwórz.
(Tylko biblioteka klas .NET Standard) W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy projekt i wybierz polecenie Edytuj plik projektu. Zmień wartość <TargetFramework> na netstandard2.0.
```
<TargetFramework>netstandard2.0</TargetFramework>
```
MyDataObject W przestrzeni nazw zastąp domyślny kod następującym kodem.
```
[Serializable] 
public class CustomDataObject
{
   public CustomDataObject()
   {
      this.MyData = "MyTestData";
   }
   public string MyData { get; set; }
}
```
W przypadku wizualizatora tylko do odczytu, takiego jak w tym przykładzie, nie jest konieczne zaimplementowanie metod visualizerObjectSource.

Następnie zaktualizuj projekt MyFirstVisualizer, aby użyć nowego obiektu danych.
W Eksploratorze rozwiązań w projekcie MyFirstVisualizer kliknij prawym przyciskiem myszy węzeł Odwołania i wybierz polecenie Dodaj odwołanie.
W obszarze Projekty wybierz projekt MyDataObject .
W kodzie atrybutu DebuggerSide.cs zaktualizuj wartość Target, zmieniając wartość System.String na MyDataObject.CustomDataObject.
```
Target = typeof(MyDataObject.CustomDataObject),
```
W projekcie MyFirstVisualizer zastąp kod metody Show poniższym kodem.
```
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);
```
Powyższy kod używa właściwości obiektu danych do wyświetlania w tytule formularza.

Następnie zaktualizuj aplikację konsolową, aby korzystała z niestandardowego obiektu danych.
W Eksploratorze rozwiązań w projekcie MyTestConsole, kliknij prawym przyciskiem węzeł Odwołania lub Zależności, a następnie dodaj odwołanie do projektu MyDataObject.

W Program.cs zastąp kod w metodzie Main poniższym kodem.

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

DebuggerSide.TestShowVisualizer(customDataObject);

(Aplikacja konsolowa platformy .NET) Dołącz wywołanie TestShowVisualizer w instrukcji try-catch, ponieważ środowisko testowe nie jest obsługiwane.
```
try
{
      DebuggerSide.TestShowVisualizer(customDataObject);
}
catch (Exception) {
}
```
Aplikacja konsolowa wymaga referencji środowiskowej do uruchomienia wizualizatora. Możesz zachować odwołanie, pozostawiając poprzedni kod zamiast go komentować.
W przypadku aplikacji konsolowej .NET Framework możesz uruchomić uprzęże testowe (naciśnij F5) lub postępować zgodnie z instrukcjami w temacie Instrukcje: Instalowanie wizualizatora.

Jeśli uruchomisz aplikację przy użyciu narzędzia testowego, aplikacja wyświetli formularz systemu Windows.
W przypadku aplikacji konsolowej platformy .NET skopiuj element MyFirstVisualizer.dll i MyDataObject.dll do folderów opisanych w temacie Instrukcje: Instalowanie wizualizatora.
Po zainstalowaniu wizualizatora ustaw punkt przerwania, uruchom aplikację konsolową i najechać kursorem na customDataObject. Jeśli wszystko jest skonfigurowane poprawnie, powinna zostać wyświetlona ikona lupy .

Po wybraniu opcji MyFirstVisualizer z ikony lupy zobaczysz Formularz z tekstem obiektu danych w tytule.

Udostępnij za pośrednictwem