Panduan: Menulis Visualizer di C#

2025-06-27

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.

Panduan ini menunjukkan cara menulis visualizer sederhana dengan menggunakan C#. Visualizer yang Anda buat dalam panduan ini menampilkan konten string menggunakan Formulir Windows. Visualizer string sederhana ini tidak terlalu berguna dalam dirinya sendiri, tetapi menunjukkan langkah-langkah dasar yang harus Anda ikuti untuk membuat visualizer yang lebih berguna untuk jenis data lainnya.

Nota

Kotak dialog dan perintah menu yang Anda lihat mungkin berbeda dari yang dijelaskan dalam Bantuan, tergantung pada pengaturan atau edisi aktif Anda. Untuk mengubah pengaturan Anda, buka menu Alat dan pilih Pengaturan Impor dan Ekspor. Untuk informasi selengkapnya, lihat pengaturan reset .

Kode visualizer harus ditempatkan dalam file DLL yang dibaca debugger. Oleh karena itu, langkah pertama adalah membuat proyek Pustaka Kelas untuk DLL.

Membuat visualizer secara manual

Selesaikan tugas berikut untuk membuat visualizer.

Membuat proyek pustaka kelas

Untuk membuat proyek pustaka kelas baru, pilih File>ProyekBaru>.
Di menu drop-down bahasa, pilih C#.
Di kotak pencarian, masukkan pustaka kelas. Pilih Pustaka Kelas (.NET Framework) lalu pilih Berikutnya.
Dalam kotak dialog, masukkan nama MyFirstVisualizer, lalu pilih Buat.

Untuk proyek visualizer, pastikan Anda memilih pustaka kelas .NET Framework dan bukan .NET. Meskipun visualizer harus .NET Framework, aplikasi panggilan bisa menjadi .NET.

Setelah membuat pustaka kelas, Anda harus menambahkan referensi ke Microsoft.VisualStudio.DebuggerVisualizers.DLL file sehingga Anda dapat menggunakan kelas yang ditentukan di sana. Sebelum menambahkan referensi, Anda harus mengganti nama beberapa kelas untuk menggunakan nama yang bermakna.

Ganti nama Class1.cs dan tambahkan Microsoft.VisualStudio.DebuggerVisualizers

Di Penjelajah Solusi, klik kanan Class1.cs dan pilih Ganti Nama pada menu konteks.
Ubah nama dari Class1.cs menjadi sesuatu yang bermakna, seperti DebuggerSide.cs.

Nota

Visual Studio secara otomatis mengubah deklarasi kelas di DebuggerSide.cs agar sesuai dengan nama file baru. Jika Anda melihat perintah untuk menyelesaikan tindakan, pilih Ya.
Di Penjelajah Solusi, klik kanan Referensi dan pilih Tambahkan Referensi pada menu pintasan.
Dalam kotak dialog Tambahkan Referensi , pada tab Telusuri , pilih Telusuri dan temukan Microsoft.VisualStudio.DebuggerVisualizers.DLL.

Anda dapat menemukan DLL di <Visual Studio Install Directory>\Common7\IDE\PublicAssemblies subdirektori direktori penginstalan Visual Studio.
Pilih OK.
Di DebuggerSide.cs, tambahkan yang berikut ini ke using direktif:
```
using Microsoft.VisualStudio.DebuggerVisualizers;
```

Sekarang Anda siap untuk membuat kode sisi debugger. Kode ini berjalan dalam debugger untuk menampilkan informasi yang ingin Anda visualisasikan. Pertama, Anda harus mengubah deklarasi objek DebuggerSide untuk mengonfigurasi pewarisan dari kelas dasar DialogDebuggerVisualizer.

Mewarisi dari DialogDebuggerVisualizer

Di DebuggerSide.cs, buka baris kode berikut:
```
public class DebuggerSide
```

Ubah kode menjadi:

public class DebuggerSide : DialogDebuggerVisualizer

Tambahkan konstruktor kosong sehingga Anda dapat meneruskan kebijakan serialisasi ke konstruktor kelas dasar yang akan digunakan untuk komunikasi antar komponen visualizer.
```
public DebuggerSide() : base(FormatterPolicy.NewtonsoftJson) // or FormatterPolicy.Json
{
}
```
Nota

Karena masalah keamanan yang dijelaskan dalam Pertimbangan sisi debugger khusus untuk .NET 5.0+, dimulai dengan Visual Studio 2022 versi 17.11, para visualizer tidak akan dapat menentukan Legacy kebijakan pemformat.
DialogDebuggerVisualizer memiliki satu metode abstrak (Show) yang harus Anda ambil alih.

Mengambil alih metode DialogDebuggerVisualizer.Show

Di public class DebuggerSide, tambahkan metode berikut :

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

Metode Show ini berisi kode yang benar-benar membuat kotak dialog visualizer atau antarmuka pengguna lainnya dan menampilkan informasi yang telah diteruskan ke visualizer dari debugger. Anda harus menambahkan kode yang membuat kotak dialog dan menampilkan informasi. Dalam panduan ini, Anda menggunakan kotak pesan Formulir Windows. Pertama, Anda harus menambahkan referensi dan direktif using untuk System.Windows.Forms.

Tambahkan System.Windows.Forms

Di Penjelajah Solusi, klik kanan Referensi dan pilih Tambahkan Referensi pada menu pintasan.
Dalam kotak dialog Tambahkan Referensi , pada tab Telusuri , pilih Telusuri, dan temukan System.Windows.Forms.DLL.

Anda dapat menemukan DLL di C:\Windows\Microsoft.NET\Framework\v4.0.30319.
Pilih OK.
Di DebuggerSide.cs, tambahkan berikut ke direktif using:
```
using System.Windows.Forms;
```

Sekarang, Anda menambahkan beberapa kode untuk membuat dan menampilkan antarmuka pengguna untuk visualizer Anda. Karena sampel ini adalah visualizer pertama Anda, Anda dapat menjaga antarmuka pengguna tetap sederhana dan menggunakan Kotak Pesan.

Perlihatkan Output Visualizer dalam kotak dialog

Dalam metode , Show tambahkan baris kode berikut:
```
MessageBox.Show(objectProvider.GetObject().ToString());
```
Contoh kode ini tidak menyertakan penanganan kesalahan. Anda harus menyertakan penanganan kesalahan dalam visualizer nyata atau jenis aplikasi lainnya.
Pada menu Build , pilih Build MyFirstVisualizer. Proyek diharapkan berhasil dibangun. Koreksi kesalahan build apa pun sebelum melanjutkan.

Kode sisi debugger sekarang selesai. Namun, ada satu langkah lagi; atribut yang memberi tahu sisi debuggee koleksi kelas mana yang membentuk visualizer.

Tambahkan jenis untuk memvisualisasikan kode sisi debuggee

Dalam kode debugger, Anda menentukan tipe objek yang akan divisualisasikan (sumber objek) untuk debuggee dengan menggunakan atribut DebuggerVisualizerAttribute. Properti Target mengatur jenis yang akan divisualisasikan.

Tambahkan kode atribut berikut ke DebuggerSide.cs, setelah direktif using tetapi sebelum namespace MyFirstVisualizer:

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

Pada menu Build , pilih Build MyFirstVisualizer. Proyek diharapkan berhasil dibangun. Koreksi kesalahan build apa pun sebelum melanjutkan.

Pada titik ini, visualizer pertama Anda selesai. Jika Anda telah mengikuti langkah-langkah dengan benar, Anda dapat membangun visualizer dan menginstalnya ke Visual Studio. Namun, sebelum menginstal visualizer ke Visual Studio, Anda harus mengujinya untuk memastikan bahwa visualizer berjalan dengan benar. Sekarang Anda membuat rangka uji coba untuk menjalankan visualizer tanpa menginstalnya ke dalam Visual Studio.

Menambahkan Metode Pengujian untuk menampilkan visualizer

Tambahkan metode berikut ke kelas public DebuggerSide:

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

Pada menu Build , pilih Build MyFirstVisualizer. Proyek diharapkan berhasil dibangun. Koreksi kesalahan build apa pun sebelum melanjutkan.

Selanjutnya, Anda harus membuat proyek yang dapat dieksekusi untuk memanggil DLL visualizer Anda. Untuk kesederhanaan, gunakan proyek Aplikasi Konsol.

Menambahkan proyek aplikasi konsol ke solusi

Di Penjelajah Solusi, klik kanan solusi, pilih Tambahkan, lalu pilih Proyek Baru.
Pilih File>Baru>Proyek. Di menu drop-down bahasa, pilih C#. Dalam kotak pencarian, ketik aplikasi konsol, lalu pilih Aplikasi Konsol (.NET Framework) atau Aplikasi Konsol untuk .NET. Pilih Selanjutnya. Dalam kotak dialog yang muncul, ketik nama MyTestConsole, lalu pilih Buat.

Nota

Jika Anda ingin dengan mudah menguji visualizer menggunakan test harness, buat aplikasi konsol .NET Framework. Anda dapat membuat aplikasi konsol .NET sebagai gantinya, tetapi kerangka pengujian yang akan dijelaskan kemudian belum kompatibel untuk .NET, jadi Anda harus menginstal visualizer untuk mengujinya. Untuk aplikasi konsol .NET, pertama-tama buat aplikasi konsol di sini, tambahkan DLL dan referensi proyek yang diperlukan, lalu ikuti langkah-langkah yang dijelaskan di Menambahkan objek data sisi debuggee. Untuk skenario ASP.NET Core, lihat Pertimbangan sisi debugger khusus untuk .NET 5.0+.

Sekarang, Anda harus menambahkan referensi yang diperlukan sehingga MyTestConsole dapat memanggil MyFirstVisualizer.

Menambahkan referensi yang diperlukan ke MyTestConsole

Di Penjelajah Solusi, klik kanan MyTestConsole dan pilih Tambahkan Referensi pada menu pintasan.
Dalam kotak dialog Tambahkan Referensi , buka tab Telusuri dan pilih Microsoft.VisualStudio.DebuggerVisualizers.DLL.
Pilih OK.
Klik kanan MyTestConsole dan pilih Tambahkan Referensi lagi.
Dalam kotak dialog Tambahkan Referensi , buka tab Proyek dan pilih MyFirstVisualizer.
Pilih OK.

Sekarang, Anda tambahkan kode untuk menyelesaikan kerangka uji.

Menambahkan kode ke MyTestConsole

Di Penjelajah Solusi, klik kanan Program.cs dan pilih Ganti Nama pada menu pintasan.
Edit nama dari Program.cs menjadi sesuatu yang lebih bermakna, seperti TestConsole.cs.

Nota

Visual Studio secara otomatis mengubah deklarasi kelas di TestConsole.cs agar sesuai dengan nama file baru.
Di TestConsole.cs, tambahkan kode berikut ke arahan using :
```
using MyFirstVisualizer;
```

Dalam metode Main, tambahkan kode berikut:

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

Sekarang, Anda siap untuk menguji visualizer pertama Anda.

Menguji visualizer

Di Penjelajah Solusi, klik kanan MyTestConsole dan pilih Atur sebagai Proyek Startup pada menu pintasan.
Pada menu Debug, pilih Mulai.

Aplikasi konsol dimulai dan Visualizer muncul dan menampilkan string, "Hello, World."

Selamat. Anda telah membangun dan menguji visualizer pertama Anda!

Jika Anda ingin menggunakan visualizer Anda di Visual Studio daripada sekadar memanggilnya dari test harness, Anda harus menginstalnya. Untuk informasi selengkapnya, lihat Cara: Menginstal Visualizer.

Menambahkan objek data pada sisi debuggee

Di bagian ini, Anda beralih dari System.String objek data ke objek data kustom.

Di Penjelajah Solusi, klik kanan solusi, pilih Tambahkan, lalu pilih Proyek Baru. Di menu drop-down bahasa, pilih C#. Dalam kotak pencarian, ketik pustaka kelas, lalu pilih Pustaka Kelas (.NET Framework) atau Pustaka Kelas untuk .NET Standard.

Nota

Jika Anda menggunakan aplikasi konsol uji .NET Framework, pastikan Anda membuat proyek pustaka kelas .NET Framework.
Pilih Selanjutnya. Dalam kotak dialog yang muncul, ketik nama MyDataObject, lalu pilih Buat.
(hanya pustaka kelas Standar.NET) Di Penjelajah Solusi, klik kanan proyek dan pilih Edit File Proyek. Ubah nilai <TargetFramework> menjadi netstandard2.0.
```
<TargetFramework>netstandard2.0</TargetFramework>
```
MyDataObject Di dalam namespace, ganti kode default dengan kode berikut.
```
[Serializable] 
public class CustomDataObject
{
   public CustomDataObject()
   {
      this.MyData = "MyTestData";
   }
   public string MyData { get; set; }
}
```
Untuk visualisator baca-saja, seperti dalam contoh ini, tidak perlu menerapkan metode VisualizerObjectSource.

Selanjutnya, perbarui proyek MyFirstVisualizer untuk menggunakan objek data baru.
Di Penjelajah Solusi di bawah proyek MyFirstVisualizer, klik kanan simpul Referensi dan pilih Tambahkan Referensi.
Di bawah Proyek, pilih proyek MyDataObject .
Dalam kode atribut DebuggerSide.cs, perbarui nilai Target, ubah System.String ke MyDataObject.CustomDataObject.
```
Target = typeof(MyDataObject.CustomDataObject),
```

Dalam proyek MyFirstVisualizer, ganti kode untuk Show metode dengan kode berikut.

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);

Kode sebelumnya menggunakan properti objek data untuk ditampilkan dalam judul Formulir.

Selanjutnya, perbarui aplikasi konsol untuk menggunakan objek data kustom.

Di Penjelajah Solusi di bawah proyek MyTestConsole, klik kanan node Referensi atau Dependensi , dan tambahkan referensi proyek ke MyDataObject.

Di Program.cs, ganti kode dalam Main metode dengan kode berikut.

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

DebuggerSide.TestShowVisualizer(customDataObject);

(Aplikasi konsol .NET) Sertakan panggilan ke TestShowVisualizer dalam pernyataan try-catch, karena rangkaian pengujian tidak didukung.
```
try
{
      DebuggerSide.TestShowVisualizer(customDataObject);
}
catch (Exception) {
}
```
Aplikasi konsol memerlukan referensi runtime ke visualizer. Anda dapat mempertahankan referensi dengan menyimpan kode sebelumnya alih-alih mengomentarinya.
Untuk aplikasi konsol .NET Framework, Anda dapat menjalankan test harness (tekan F5), atau Anda dapat mengikuti instruksi di Cara: Menginstal Visualizer.

Jika Anda menjalankan aplikasi menggunakan test harness, aplikasi akan menampilkan Formulir Windows.
Untuk aplikasi konsol .NET, salin MyFirstVisualizer.dll dan MyDataObject.dll ke folder yang dijelaskan dalam Cara: Menginstal Visualizer.
Setelah menginstal visualizer, atur titik henti, jalankan aplikasi konsol, dan arahkan mouse ke atas customDataObject. Jika semuanya disiapkan dengan benar, Anda akan melihat ikon kaca pembesar .

Saat Anda memilih MyFirstVisualizer dari kaca pembesar, Anda akan melihat Formulir dengan teks objek data dalam judul.

Bagikan melalui