Bagikan melalui

Visualisasi data kustom untuk debugger Visual Studio (.NET)

Penting

Dimulai dengan Visual Studio 2022 versi 17.9, visualizer sekarang dapat ditulis dalam .NET 6.0+ yang berjalan di luar proses menggunakan model VisualStudio.Extensibility yang baru. Untuk ekstensi yang dibuat menggunakan model baru, lihat dokumentasi di Membuat visualizer debugger Visual Studio sebagai gantinya. Jika Anda perlu mendukung versi Visual Studio yang lebih lama atau ingin mengirim visualizer kustom Anda sebagai bagian dari DLL pustaka, maka gunakan informasi dalam artikel ini, yang hanya berlaku untuk model pengembangan ekstensi (VSSDK) yang lebih lama.

Visualizer adalah bagian dari antarmuka pengguna debugger Visual Studio yang menampilkan variabel atau objek dengan cara yang sesuai dengan jenis datanya. Misalnya, visualizer bitmap menginterpretasikan struktur bitmap dan menampilkan grafik yang diwakilinya. Beberapa visualizer memungkinkan Anda memodifikasi serta melihat data. Dalam debugger, visualizer diwakili oleh ikon kaca pembesar VisualizerIconikon . Anda dapat memilih ikon dalam kotak dialog DataTip, debugger Watch , atau QuickWatch , lalu memilih visualizer yang sesuai untuk objek yang sesuai.

Selain visualizer bawaan standar, lebih banyak visualizer mungkin tersedia untuk diunduh dari Microsoft, pihak ketiga, dan komunitas. Anda juga dapat menulis visualizer Anda sendiri dan menginstalnya di debugger Visual Studio.

Artikel ini menyediakan gambaran umum tingkat tinggi tentang pembuatan visualizer. Untuk instruksi terperinci, lihat artikel berikut ini sebagai gantinya:

Nota

Visualizer kustom tidak didukung untuk aplikasi Universal Windows Platform (UWP) dan Windows 8.x.

Gambaran Umum

Anda dapat menulis visualizer kustom untuk objek dari kelas terkelola apa pun, kecuali Object dan Array.

Arsitektur visualizer debugger memiliki dua bagian:

  • Sisi debugger beroperasi di debugger Visual Studio, dan membuat serta menampilkan antarmuka pengguna pemvisualisasi.

    Karena Visual Studio dijalankan pada .NET Framework Runtime, komponen ini harus ditulis untuk .NET Framework. Untuk alasan ini, tidak mungkin untuk menulisnya untuk .NET Core.

  • Sisi debuggee berjalan dalam proses yang sedang di-debug oleh Visual Studio ( debuggee). Objek data untuk divisualisasikan (misalnya, objek String) ada dalam proses debuggee. Sisi yang didiagnosis mengirimkan objek ke sisi debugger, yang menampilkannya di antarmuka pengguna yang telah Anda buat.

    Runtime di mana Anda membangun komponen ini harus sesuai dengan runtime tempat proses debuggee akan dijalankan, yaitu baik .NET Framework atau .NET Core.

Sisi debugger menerima objek data dari penyedia objek yang mengimplementasikan IVisualizerObjectProvider antarmuka. Sisi debuggee mengirim objek melalui sumber objek, yang berasal dari VisualizerObjectSource.

Penyedia objek juga dapat mengirim data kembali ke sumber objek, yang memungkinkan Anda menulis visualizer yang dapat mengedit data. Anda menggantikan penyedia objek untuk berbicara dengan evaluator ekspresi dan sumber objek.

Sisi debuggee dan sisi debugger saling berkomunikasi melalui Stream, dengan menserialisasi objek data menjadi Stream dan mendeserialisasi Stream kembali menjadi objek data.

Anda dapat menulis visualizer untuk jenis generik hanya jika jenisnya adalah jenis terbuka. Pembatasan ini sama dengan pembatasan saat menggunakan DebuggerTypeProxy atribut . Untuk detailnya, lihat Menggunakan atribut DebuggerTypeProxy.

Visualizer kustom mungkin memiliki pertimbangan keamanan. Lihat Pertimbangan keamanan visualizer.

Membuat antarmuka pengguna untuk sisi debugger

Untuk membuat antarmuka pengguna visualizer di sisi debugger, Anda membuat kelas yang mewarisi dari DialogDebuggerVisualizer, dan mengambil alih Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show metode untuk menampilkan antarmuka. Anda dapat menggunakan IDialogVisualizerService untuk menampilkan formulir, dialog, dan kontrol Windows di visualizer Anda.

  1. Gunakan IVisualizerObjectProvider metode untuk mendapatkan objek yang divisualisasikan di sisi debugger.

  2. Buat kelas yang mewarisi dari DialogDebuggerVisualizer.

Nota

Karena masalah keamanan yang dijelaskan di bagian di bawah ini, mulai dari Visual Studio 2022 versi 17.11, visualizer tidak dapat menentukan kebijakan formatter Legacy di konstruktor kelas dasar. Mulai sekarang, visualizer hanya dapat menggunakan serialisasi JSON untuk berkomunikasi antara komponen debugger dan sisi debuggee .

  1. Gantilah metode Microsoft.VisualStudio.DebuggerVisualizers.DialogDebuggerVisualizer.Show untuk menampilkan antarmuka Anda. Gunakan IDialogVisualizerService metode untuk menampilkan formulir, dialog, dan kontrol Windows di antarmuka Anda.

  2. Terapkan DebuggerVisualizerAttribute, berikan visualizer untuk ditampilkan (DialogDebuggerVisualizer).

Pertimbangan khusus untuk lingkungan debugger dalam .NET 5.0+

Visualizer Kustom mentransfer data antara sisi debuggee dan debugger melalui serialisasi biner dengan menggunakan kelas BinaryFormatter secara default. Namun, serialisasi semacam itu sedang dikurangi di .NET 5 ke atas karena masalah keamanan mengenai kerentanannya yang tidak dapat diperbaiki. Selain itu, telah ditandai sepenuhnya usang di ASP.NET Core 5 dan penggunaannya akan ditampilkan seperti yang dijelaskan dalam Dokumentasi Inti ASP.NET. Bagian ini menjelaskan langkah-langkah yang harus Anda ambil untuk memastikan visualizer Anda masih didukung dalam skenario ini.

  • Untuk alasan kompatibilitas, metode Show yang ditimpa di bagian sebelumnya masih menerima IVisualizerObjectProvider. Namun, mulai dari Visual Studio 2019 versi 16.10, sebenarnya berjenis IVisualizerObjectProvider3. Untuk alasan ini, transmisikan objectProvider objek ke antarmuka yang diperbarui.

  • Saat mengirim objek, seperti perintah atau data, ke sisi debuggee, Anda harus menggunakan metode IVisualizerObjectProvider2.Serialize untuk meneruskannya ke aliran; metode ini akan menentukan format serialisasi terbaik yang akan digunakan berdasarkan runtime dari proses debuggee. Kemudian, operkan aliran ke metode IVisualizerObjectProvider2.TransferData.

  • Jika komponen visualizer sisi debuggee perlu mengembalikan apa pun ke sisi debugger, komponen tersebut akan terletak di objek yang Stream dikembalikan oleh metode TransferData. Gunakan metode IVisualizerObjectProvider2.GetDeserializableObjectFrom untuk mendapatkan instance IDeserializableObject darinya dan memproses sesuai kebutuhan; atau gunakan DeserializeFromJson jika itu adalah tipe yang Anda tahu cara mendeserialisasi.

Silakan merujuk ke bagian Pertimbangan Khusus di Sisi Debuggee untuk .NET 5.0+ untuk mempelajari perubahan lain yang diperlukan di sisi debuggee karena dukungan Serialisasi Biner tidak tersedia.

Nota

Jika Anda ingin informasi selengkapnya tentang masalah ini, lihat panduan keamanan BinaryFormatter.

Buat sumber objek visualizer di sisi debuggee

Dalam kode sisi debugger, edit DebuggerVisualizerAttribute dengan memberi tipe untuk divisualisasikan (sumber objek pada sisi debuggee) (VisualizerObjectSource). Properti Target mengatur sumber objek. Jika Anda menghilangkan sumber objek, visualizer akan menggunakan sumber objek default.

Kode sisi debuggee berisi sumber objek yang divisualisasikan. Objek data dapat mengambil alih metode VisualizerObjectSource. DLL sisi debuggee diperlukan jika Anda ingin membuat visualizer mandiri.

Dalam kode di sisi debuggee:

  • Untuk memungkinkan visualizer mengedit objek data, sumber objek harus mewarisi dari VisualizerObjectSource dan mengganti metode TransferData atau CreateReplacementObject.

  • Jika Anda perlu mendukung penargetan multi pada penampil, Anda dapat menggunakan Target Framework Monikers (TFM) atau penanda Kerangka Kerja berikut dalam file proyek sisi aplikasi yang diuji.

    <TargetFrameworks>net20;netstandard2.0;netcoreapp2.0</TargetFrameworks>

    Ini adalah satu-satunya TFM yang didukung.

Pertimbangan sisi debuggee khusus untuk .NET 5.0+

Penting

Langkah tambahan mungkin diperlukan agar visualizer berfungsi mulai dari .NET 5.0 karena masalah keamanan mengenai metode serialisasi biner yang mendasari yang digunakan secara default. Silakan baca bagian ini sebelum melanjutkan.

  • Jika visualizer mengimplementasikan metode TransferData, gunakan metode GetDeserializableObject yang baru ditambahkan yang tersedia dalam versi terbaru VisualizerObjectSource. IDeserializableObject yang dikembalikan membantu menentukan format serialisasi objek (biner atau JSON) dan mendeserialisasi objek yang mendasarinya agar dapat digunakan.

  • Jika sisi debuggee mengembalikan data ke sisi debugger sebagai bagian TransferData dari panggilan, respons diserialisasi ke aliran sisi debugger melalui metode Serialize.

Konten terkait