Пошаговое руководство. Написание визуализатора на C#

Статья
10/24/2023

Внимание

Начиная с Visual Studio 2022 версии 17.9 визуализаторы теперь могут быть написаны в .NET 6.0+ с использованием новой модели VisualStudio.Extensibility. Мы рекомендуем авторам визуализаторов ссылаться на новую документацию по созданию визуализаторов отладчика Visual Studio, если они не хотят поддерживать более старые версии Visual Studio или не хотите отправлять пользовательские визуализаторы в составе библиотеки DLL.

В данном пошаговом руководстве показано, как написать простой визуализатор, используя C#. Визуализатор, создаваемый в этом пошаговом руководстве, отображает содержимое строки с помощью Формы Windows Form. Этот простой визуализатор строк не особенно полезен сам по себе, но он показывает основные шаги, которые необходимо выполнить, чтобы создать более полезные визуализаторы для других типов данных.

Примечание.

Отображаемые диалоговые окна и команды меню могут отличаться от описанных в справке в зависимости от действующих параметров или выпуска среды. Для изменения параметров выберите пункт Импорт и экспорт параметров в меню Сервис. Дополнительные сведения см. в разделе Сброс параметров.

Код визуализатора должен быть помещен в dll-файл, считываемый отладчиком. Поэтому первым шагом является создание проекта библиотеки классов для библиотеки DLL.

Создание визуализатора вручную

Выполните следующие задачи, чтобы создать визуализатор.

Создание проекта библиотеки классов

Чтобы создать проект библиотеки классов, выберите "Файл>нового>проекта".
В раскрывающемся списке языка выберите C#.
В поле поиска введите библиотеку классов. Выберите библиотеку классов (платформа .NET Framework), а затем нажмите кнопку "Далее".
В диалоговом окне введите имя MyFirstVisualizerи нажмите кнопку "Создать".

Для проекта визуализатора необходимо выбрать библиотеку классов .NET Framework, а не .NET. Несмотря на то что в качестве визуализатора нужно выбрать .NET Framework, вызывающим приложением может быть .NET.

После создания библиотеки классов необходимо добавить ссылку на Microsoft.VisualStudio.DebuggerVisualizers.DLL файл, чтобы использовать классы, определенные там. Перед добавлением ссылки необходимо переименовать некоторые классы, чтобы использовать значимые имена.

Переименование Class1.cs и добавление Microsoft.VisualStudio.DebuggerVisualizers

В Обозреватель решений щелкните правой кнопкой мыши Class1.cs и выберите "Переименовать" в контекстном меню.
Измените имя с Class1.cs на что-нибудь осмысленное, например, DebuggerSide.cs.

Примечание.

Visual Studio автоматически изменит объявление класса в DebuggerSide.cs согласно новому имени файла. Если появится запрос на завершение действия, нажмите кнопку "Да".
В обозревателе решений щелкните правой кнопкой мыши пункт Ссылки и в контекстном меню выберите команду Добавить ссылку.
В диалоговом окне Добавление ссылки на вкладке Обзор выберите Обзор и найдите Microsoft.VisualStudio.DebuggerVisualizers.DLL.

Библиотеку DLL можно найти в подкаталоге<Visual Studio Install Directory>\Common7\IDE\PublicAssemblies в каталоге установки Visual Studio.
Нажмите ОК.
В файле DebuggerSide.cs добавьте следующее в директивы using:
```
using Microsoft.VisualStudio.DebuggerVisualizers;
```

Теперь вы готовы создать код на стороне отладчика. Этот код выполняется в отладчике, чтобы отобразить сведения, которые требуется визуализировать. Сначала необходимо изменить объявление DebuggerSide объекта, чтобы настроить наследование из базового класса DialogDebuggerVisualizer.

Наследование от DialogDebuggerVisualizer

В DebuggerSide.cs перейдите к следующей строке кода:
```
public class DebuggerSide
```

Измените код на:

public class DebuggerSide : DialogDebuggerVisualizer

Добавьте пустой конструктор, чтобы передать конструктор базового класса политике сериализации, которая будет использоваться для обмена данными между компонентами визуализатора.
```
public DebuggerSide() : base(FormatterPolicy.NewtonsoftJson) // or FormatterPolicy.Json
{
}
```
Примечание.

Из-за проблем безопасности, описанных в статье "Специальный отладчик" для .NET 5.0+, начиная с Visual Studio 2022 версии 17.11 визуализаторы не смогут указывать Legacy политику форматирования.
DialogDebuggerVisualizer имеет один абстрактный метод — Show — который необходимо переопределить.

Переопределите метод DialogDebuggerVisualizer.Show

Добавьте следующий метод в класс public class DebuggerSide:

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

Метод Show содержит код, который фактически создает диалоговое окно визуализатора или другой интерфейс пользователя и отображает сведения, которые были переданы визуализатору из отладчика. Необходимо вручную добавить код, который создает диалоговое окно и отображает информацию. В этом пошаговом руководстве используется окно сообщений Windows Forms. Прежде всего необходимо добавить ссылку и директиву using для System.Windows.Forms.

Добавление System.Windows.Forms

В обозревателе решений щелкните правой кнопкой мыши пункт Ссылки и в контекстном меню выберите команду Добавить ссылку.
В диалоговом окне Добавление ссылки на вкладке Обзор выберите Обзори найдите файл System.Windows.Forms.DLL.

Библиотеку DLL можно найти в C:\Windows\Microsoft.NET\Framework\v4.0.30319.
Нажмите ОК.
В файле DebuggerSide.cs добавьте следующее в директивы using:
```
using System.Windows.Forms;
```

Теперь вы добавите код для создания и отображения пользовательского интерфейса для визуализатора. Так как этот пример является первым визуализатором, вы можете сохранить пользовательский интерфейс простым и использовать окно сообщений.

Отображение выходных данных визуализатора в диалоговом окне

Добавьте в метод Show следующую строку кода:
```
MessageBox.Show(objectProvider.GetObject().ToString());
```
Этот пример кода не включает обработку ошибок. Необходимо включить обработку ошибок в реальный визуализатор или любой другой тип приложения.
В меню Сборка выберите команду Собрать MyFirstVisualizer. Построение проекта должно пройти без ошибок. Если при построении все же возникнут ошибки, исправьте их, прежде чем продолжить.

Теперь код на стороне отладчика завершен. Однако есть еще один шаг. Атрибут, указывающий отладчику, какая коллекция классов состоит из визуализатора.

Добавление типа для визуализации кода на стороне отладчика

В коде на стороне отладчика тип для визуализации (источник объекта) для отлаживаемого кода указывается с помощью атрибута DebuggerVisualizerAttribute. Свойство Target задает тип для визуализации.

Добавьте следующий код атрибута в DebuggerSide.cs — после директив using, но перед namespace MyFirstVisualizer:

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

В меню Сборка выберите команду Собрать MyFirstVisualizer. Построение проекта должно пройти без ошибок. Если при построении все же возникнут ошибки, исправьте их, прежде чем продолжить.

На этом написание вашего первого визуализатора окончено. Если вы правильно следовали процедуре выше, можно построить визуализатор и установить его в Visual Studio. Но перед установкой визуализатора в Visual Studio следует убедиться, что он работает правильно. Теперь вы создадите тестовую программу для запуска визуализатора без установки в Visual Studio.

Добавление метода тестирования для отображения визуализатора

Добавьте следующий метод в класс public DebuggerSide:

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

В меню Сборка выберите команду Собрать MyFirstVisualizer. Построение проекта должно пройти без ошибок. Если при построении все же возникнут ошибки, исправьте их, прежде чем продолжить.

Далее необходимо создать проект исполняемого файла, из которого будет вызваться библиотека DLL визуализатора. Для простоты выберите проект консольного приложения.

Добавление проекта консольного приложения в решение

В Обозреватель решений щелкните решение правой кнопкой мыши, нажмите кнопку "Добавить" и выберите "Создать проект".
Выберите Файл>Создать>Проект. В раскрывающемся списке языков выберите C#. В поле поиска введите консоль и выберите Консольное приложение (.NET Framework) или Консольное приложение для .NET. Выберите Далее. В появившемся диалоговом окне введите имя MyTestConsoleи нажмите кнопку "Создать".

Примечание.

Чтобы протестировать визуализатор с помощью окружения теста, создайте консольное приложение .NET Framework. Вместо этого можно создать консольное приложение .NET, но описываемое в дальнейшем окружение теста еще не поддерживается для .NET, поэтому визуализатор необходимо будет установить, чтобы протестировать его. Для консольного приложения .NET сначала создайте консольное приложение, добавьте необходимые ссылки на библиотеку DLL и проект, а затем выполните действия, описанные в разделе Добавление объекта данных на стороне отлаживаемого кода. Сведения о сценариях ASP.NET Core см. в разделе Особые рекомендации в отношении отладчика для .NET 5.0+.

Теперь необходимо добавить необходимые ссылки, чтобы программа MyTestConsole могла вызывать MyFirstVisualizer.

Добавление необходимых ссылок в MyTestConsole

В обозревателе решений щелкните правой кнопкой мыши MyTestConsole и в контекстном меню выберите пункт Добавить ссылку.
В диалоговом окне "Добавить ссылку" откройте вкладку "Обзор" и выберите Microsoft.VisualStudio.DebuggerVisualizers.DLL.
Нажмите ОК.
Щелкните правой кнопкой мыши MyTestConsole и выберите Добавить ссылку еще раз.
В диалоговом окне "Добавить ссылку" откройте вкладку "Проекты" и выберите MyFirstVisualizer.
Нажмите ОК.

Теперь добавьте код для завершения тестового использования.

Добавление кода в MyTestConsole

Щелкните правой кнопкой мыши Program.cs в обозревателе решений и выберите команду Переименовать в контекстном меню.
Измените имя c Program.cs на что-нибудь более понятное, например на TestConsole.cs.

Примечание.

Visual Studio автоматически изменяет объявление класса в TestConsole.cs так, чтобы оно соответствовало новому имени файла.
В TestConsole.cs добавьте следующий код к директивам using:
```
using MyFirstVisualizer;
```

В метод Main добавьте следующий код:

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

Теперь вы готовы протестировать первый визуализатор.

Тестирование визуализатора

В обозревателе решений щелкните MyTestConsole правой кнопкой мыши и выберите в контекстном меню команду Назначить запускаемым проектом.
В меню Отладка выберите команду Пуск.

Запускается консольное приложение, визуализатор появляется и отображает строку "Hello, World".

Поздравляем. Вы создали и проверили свой первый визуализатор!

Если вам удобнее вызывать визуализатор из Visual Studio, а не из специально тестового окружения, визуализатор необходимо установить. Дополнительные сведения см. в разделе "Практическое руководство. Установка визуализатора".

Добавление объекта данных на стороне отлаживаемого объекта

В этом разделе вы переключитесь с объекта данных System.String на пользовательский объект данных.

В Обозреватель решений щелкните решение правой кнопкой мыши, нажмите кнопку "Добавить" и выберите "Создать проект". В раскрывающемся списке языков выберите C#. В поле поиска введите библиотека классов, а затем выберите Библиотека классов (.NET Framework) или Библиотека классов для .NET Standard.

Примечание.

Если вы используете тестовое консольное приложение .NET Framework, убедитесь, что создан проект библиотеки классов .NET Framework.
Выберите Далее. В появившемся диалоговом окне введите имя MyDataObjectи нажмите кнопку "Создать".
(Только для библиотеки классов .NET Standard) В обозревателе решений щелкните правой кнопкой мыши проект и выберите Изменить файл проекта. Измените значение <TargetFramework> на netstandard2.0.
```
<TargetFramework>netstandard2.0</TargetFramework>
```
В пространстве имен MyDataObject замените код по умолчанию следующим кодом.
```
[Serializable] 
public class CustomDataObject
{
   public CustomDataObject()
   {
      this.MyData = "MyTestData";
   }
   public string MyData { get; set; }
}
```
Для визуализатора только для чтения, например в этом примере, не требуется реализовать методы VisualizerObjectSource.

Затем обновите проект MyFirstVisualizer, чтобы он использовал новый объект данных.
В обозревателе решений в проекте MyFirstVisualizer щелкните правой кнопкой мыши узел Ссылки и выберите команду Добавить ссылку.
В разделе Проектывыберите проект MyDataObject.
В коде атрибута файла DebuggerSide.cs обновите целевое значение, заменив System.String на MyDataObject.CustomDataObject.
```
Target = typeof(MyDataObject.CustomDataObject),
```
В проекте MyFirstVisualizer замените код метода Show следующим кодом.
```
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);
```
Приведенный выше код использует свойство объекта данных для отображения в заголовке формы.

Затем обновите консольное приложение, чтобы использовать пользовательский объект данных.
В обозревателе решений в проекте MyTestConsole щелкните правой кнопкой мыши узел Ссылки или Зависимости и добавьте ссылку на проект в MyDataObject.

В файле Program.cs замените код в методе Main следующим кодом.

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

DebuggerSide.TestShowVisualizer(customDataObject);

(Консольное приложение .NET) Заключите вызов TestShowVisualizer в инструкцию try-catch, поскольку окружение теста не поддерживается.
```
try
{
      DebuggerSide.TestShowVisualizer(customDataObject);
}
catch (Exception) {
}
```
Консольному приложению требуется ссылка на визуализатор в среде выполнения. Вы можете сохранить ссылку, оставив приведенный выше код, вместо того, чтобы раскомментировать его.
Для консольного приложения .NET Framework можно запустить окружение теста (нажать клавишу F5) или следовать инструкциям в разделе, посвященном установке визуализатора.

Если приложение запускается с помощью окружения теста, в приложении отображается форма Windows Forms.
Для консольного приложения .NET скопируйте MyFirstVisualizer.dll и MyDataObject.dll в папки, описанные в разделе, посвященном установке визуализатора.
После установки визуализатора установите точку останова, запустите консольное приложение и наведите указатель мыши на customDataObject. Если все настроено правильно, вы увидите значок лупы.

При выборе MyFirstVisualizer из удлиняющего стекла вы увидите форму с текстом объекта данных в заголовке.

Поделиться через

Пошаговое руководство. Написание визуализатора на C#

Создание визуализатора вручную

Создание проекта библиотеки классов

Переименование Class1.cs и добавление Microsoft.VisualStudio.DebuggerVisualizers

Наследование от DialogDebuggerVisualizer

Переопределите метод DialogDebuggerVisualizer.Show

Добавление System.Windows.Forms

Отображение выходных данных визуализатора в диалоговом окне

Добавление типа для визуализации кода на стороне отладчика

Добавление метода тестирования для отображения визуализатора

Добавление проекта консольного приложения в решение

Добавление необходимых ссылок в MyTestConsole

Добавление кода в MyTestConsole

Тестирование визуализатора

Добавление объекта данных на стороне отлаживаемого объекта

Обратная связь

Дополнительные ресурсы

Поделиться через

Пошаговое руководство. Написание визуализатора на C#

Создание визуализатора вручную

Создание проекта библиотеки классов

Переименование Class1.cs и добавление Microsoft.VisualStudio.DebuggerVisualizers

Наследование от DialogDebuggerVisualizer

Переопределите метод DialogDebuggerVisualizer.Show

Добавление System.Windows.Forms

Отображение выходных данных визуализатора в диалоговом окне

Добавление типа для визуализации кода на стороне отладчика

Добавление метода тестирования для отображения визуализатора

Добавление проекта консольного приложения в решение

Добавление необходимых ссылок в MyTestConsole

Добавление кода в MyTestConsole

Тестирование визуализатора

Добавление объекта данных на стороне отлаживаемого объекта

Связанный контент

Обратная связь

Дополнительные ресурсы