Share via

Visualisasi data kustom untuk debugger Visual Studio (.NET)

  • Artikel

Penting

Dimulai dengan Visual Studio 2022 versi 17.9, visualizer sekarang dapat ditulis dalam .NET 6.0+ yang kehabisan proses menggunakan model VisualStudio.Extensibility baru. Kami mendorong penulis visualizer untuk mereferensikan dokumentasi baru di Membuat visualizer debugger Visual Studio kecuali mereka ingin mendukung versi Visual Studio yang lebih lama atau ingin mengirim visualizer kustom mereka sebagai bagian dari DLL pustaka.

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 dan melihat data. Dalam debugger, visualizer diwakili oleh ikon VisualizerIconkaca pembesar . Anda dapat memilih ikon dalam kotak dialog DataTip, jendela Watch debugger, atau QuickWatch, lalu pilih visualizer yang sesuai untuk objek terkait.

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:

Catatan

Visualizer kustom tidak didukung untuk aplikasi Platform Windows Universal (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 berjalan dalam debugger Visual Studio yang membuat dan menampilkan antarmuka pengguna visualizer.

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

  • Sisi debuggee yang berjalan dalam proses Visual Studio adalah penelusuran kesalahan (debuggee). Objek data untuk divisualisasikan (misalnya objek String) ada dalam proses debuggee. Sisi debuggee mengirimkan objek ke sisi debugger, yang menampilkannya di antarmuka pengguna yang Anda buat.

    Runtime tempat Anda membangun komponen ini harus cocok dengan yang akan dijalankan proses debuggee, yaitu .NET Framework atau .NET Core.

Sisi debugger menerima objek data dari penyedia objek yang mengimplementasikan antarmuka IVisualizerObjectProvider. Sisi debuggee mengirimkan 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 mengambil alih penyedia objek untuk berbicara dengan evaluator ekspresi dan sumber objek.

Sisi debuggee dan sisi debugger berkomunikasi satu sama lain melalui metode Stream yang melakukan serialisasi objek data ke dalam Stream dan membatalkan serialisasi Stream kembali ke objek data.

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

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

Membuat antarmuka pengguna sisi debugger

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

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

  2. Buat kelas yang mewarisi dari DialogDebuggerVisualizer.

Catatan

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

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

  2. Terapkan DebuggerVisualizerAttribute dengan memberinya visualizer untuk ditampilkan (DialogDebuggerVisualizer).

Pertimbangan sisi debugger khusus untuk .NET 5.0+

Visualizer Kustom mentransfer data antara sisi debuggee dan debugger melalui serialisasi biner menggunakan kelas BinaryFormatter secara default. Namun, serialisasi semacam itu sedang dikurasi di .NET 5 ke atas karena masalah keamanan mengenai kerentanannya yang tidak dapat diperbaiki. Selain itu, serialisasi tersebut 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 lakukan untuk memastikan visualizer Anda masih didukung dalam skenario ini.

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

  • Saat mengirim objek, seperti perintah atau data, ke sisi debuggee, gunakan metode IVisualizerObjectProvider2.Serialize untuk meneruskannya ke aliran. Format serialisasi terbaik akan ditentukan untuk digunakan berdasarkan runtime proses debuggee. Kemudian, teruskan aliran ke metode IVisualizerObjectProvider2.TransferData.

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

Silakan lihat bagian Pertimbangan sisi debuggee khusus untuk .NET 5.0+ untuk mempelajari perubahan lain yang diperlukan di sisi debuggee jika penggunaan Serialisasi Biner tidak didukung.

Catatan

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

Membuat sumber objek visualizer untuk sisi debuggee

Dalam kode sisi debugger, edit DebuggerVisualizerAttribute yang memberinya jenis untuk divisualisasikan (sumber objek 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 sisi debuggee:

  • Untuk membiarkan visualizer mengedit objek data, sumber objek harus mewarisi dan VisualizerObjectSource mengambil alih TransferData metode atau CreateReplacementObject .

  • Jika Anda perlu mendukung multi-penargetan di visualizer, Anda dapat menggunakan Moniker Kerangka Kerja Target (TFM) berikut dalam file proyek sisi debuggee.

    <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 terkait metode serialisasi biner dasar yang digunakan secara default. Silakan baca bagian ini sebelum melanjutkan.

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

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

Konten terkait