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

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

Это важно

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

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

Замечание

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

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

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

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

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

  1. Чтобы создать проект библиотеки классов, выберите "Файл>нового>проекта".

  2. В раскрывающемся списке языка выберите C#.

  3. В поле поиска введите библиотеку классов. Выберите библиотеку классов (.NET Framework) и нажмите кнопку "Далее".

  4. В диалоговом окне введите имя MyFirstVisualizerи нажмите кнопку "Создать".

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

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

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

  1. В обозревателе решений щелкните правой кнопкой мыши Class1.cs и выберите "Переименовать " в контекстном меню.

  2. Измените имя с Class1.cs на что-то понятное, например DebuggerSide.cs.

    Замечание

    Visual Studio автоматически изменяет объявление класса в DebuggerSide.cs в соответствии с новым именем файла. Если появится запрос на завершение действия, нажмите кнопку "Да".

  3. В обозревателе решений щелкните правой кнопкой мыши ссылки и выберите "Добавить ссылку " в контекстном меню.

  4. В диалоговом окне "Добавить ссылку " на вкладке "Обзор " выберите "Обзор " и найдите Microsoft.VisualStudio.DebuggerVisualizers.DLL.

    Библиотеку DLL можно найти в подкаталоге <Visual Studio Install Directory>\Common7\IDE\PublicAssemblies каталога установки Visual Studio.

  5. Нажмите ОК.

  6. В DebuggerSide.cs добавьте следующее к директивам using:

    using Microsoft.VisualStudio.DebuggerVisualizers;

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

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

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

    public class DebuggerSide

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

    public class DebuggerSide : DialogDebuggerVisualizer

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

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

    Замечание

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

  4. 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

  1. В обозревателе решений щелкните правой кнопкой мыши ссылки и выберите "Добавить ссылку " в контекстном меню.

  2. В диалоговом окне "Добавить ссылку " на вкладке "Обзор " выберите "Обзор" и найдите System.Windows.Forms.DLL.

    Библиотеку DLL можно найти в C:\Windows\Microsoft.NET\Framework\v4.0.30319.

  3. Нажмите ОК.

  4. В DebuggerSide.cs добавьте следующее к директивам using:

    using System.Windows.Forms;

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

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

  1. В методе Show добавьте следующую строку кода:

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

    Этот пример кода не включает обработку ошибок. Необходимо включить обработку ошибок в реальный визуализатор или любой другой тип приложения.

  2. В меню «Сборка» выберите команду «Сборка MyFirstVisualizer». Проект должен успешно выполнить сборку. Исправьте все ошибки сборки перед продолжением.

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

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

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

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

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

  2. В меню «Сборка» выберите команду «Сборка MyFirstVisualizer». Проект должен успешно выполнить сборку. Исправьте все ошибки сборки перед продолжением.

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

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

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

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

  2. В меню «Сборка» выберите команду «Сборка MyFirstVisualizer». Проект должен успешно выполнить сборку. Исправьте все ошибки сборки перед продолжением.

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

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

  1. В обозревателе решений щелкните правой кнопкой мыши решение, нажмите кнопку "Добавить" и выберите "Создать проект".

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

Замечание

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

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

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

  1. В обозревателе решений щелкните правой кнопкой мыши MyTestConsole и выберите "Добавить ссылку " в контекстном меню.

  2. В диалоговом окне "Добавить ссылку" откройте вкладку "Обзор " и выберите Microsoft.VisualStudio.DebuggerVisualizers.DLL.

  3. Нажмите ОК.

  4. Щелкните правой кнопкой мыши MyTestConsole и снова нажмите кнопку "Добавить ссылку ".

  5. В диалоговом окне "Добавить ссылку" откройте вкладку "Проекты " и выберите MyFirstVisualizer.

  6. Нажмите ОК.

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

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

  1. В обозревателе решений щелкните правой кнопкой мыши Program.cs и выберите "Переименовать " в контекстном меню.

  2. Измените имя из Program.cs на что-то более понятное, например TestConsole.cs.

    Замечание

    Visual Studio автоматически изменяет объявление класса в TestConsole.cs в соответствии с новым именем файла.

  3. В TestConsole.cs добавьте следующий код в using директивы:

    using MyFirstVisualizer;

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

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

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

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

  1. В обозревателе решений щелкните правой кнопкой мыши MyTestConsole и выберите "Задать в качестве запускаемого проекта " в контекстном меню.

  2. В меню Отладка выберите Пуск.

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

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

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

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

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

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

    Замечание

    Если вы используете тестовое консольное приложение .NET Framework, убедитесь, что вы создаете проект библиотеки классов .NET Framework.

  2. Нажмите кнопку Далее. В появившемся диалоговом окне введите имя MyDataObjectи нажмите кнопку "Создать".

  3. (Только библиотека классов .NET Standard) В обозревателе решений щелкните проект правой кнопкой мыши и выберите команду "Изменить файл проекта". Измените значение <TargetFramework> на netstandard2.0.

    <TargetFramework>netstandard2.0</TargetFramework>

  4. Внутри пространства имен MyDataObject замените код по умолчанию следующим кодом.

    [Serializable] 
public class CustomDataObject
{
   public CustomDataObject()
   {
      this.MyData = "MyTestData";
   }
   public string MyData { get; set; }
}

    Для визуализатора только для чтения, например в этом примере, не требуется реализовать методы VisualizerObjectSource.

    Затем обновите проект MyFirstVisualizer, чтобы использовать новый объект данных.

  5. В обозревателе решений в проекте MyFirstVisualizer щелкните правой кнопкой мыши узел "Ссылки" и выберите "Добавить ссылку".

  6. В разделе "Проекты" выберите проект MyDataObject .

  7. В коде атрибута DebuggerSide.cs обновите значение Target, заменив System.String на MyDataObject.CustomDataObject.

    Target = typeof(MyDataObject.CustomDataObject),

  8. В проекте 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);

    Предыдущий код использует свойство объекта данных для отображения в заголовке Формы.

    Затем обновите консольное приложение, чтобы использовать пользовательский объект данных.

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

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

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

DebuggerSide.TestShowVisualizer(customDataObject);

  11. (Консольное приложение .NET) Заключите вызов TestShowVisualizer в инструкцию try-catch, так как тестовый ремень не поддерживается.

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

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

  12. Для консольного приложения .NET Framework можно запустить тестовый ремень (нажмите клавишу F5) или следуйте инструкциям в разделе "Практическое руководство. Установка визуализатора".

    Если вы запускаете приложение с помощью тестового каркаса, приложение отображает Windows Form.

  13. Для консольного приложения .NET скопируйте MyFirstVisualizer.dll и MyDataObject.dll в папки, описанные в статье "Практическое руководство: Установка визуализатора".

  14. После установки визуализатора установите точку останова, запустите консольное приложение и наведите указатель мыши customDataObject. Если все настроено правильно, вы увидите значок лупы.

    Значок лупы визуализатора.

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

    Визуализатор, отображающий форму Windows

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

  • Last updated on