Bagikan melalui

Panduan: Menulis Visualizer di C#

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

Panduan ini menunjukkan cara menulis visualizer sederhana 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.

Catatan

Kotak dialog dan perintah menu yang Anda lihat mungkin berbeda dari yang dijelaskan di Bantuan, bergantung pada pengaturan atau edisi aktif Anda. Untuk mengubah pengaturan Anda, buka menu Alat dan pilih Pengaturan Impor dan Ekspor. Untuk mengetahui informasi selengkapnya, lihat Mengatur ulang dan menjalankan ulang.

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

  1. Untuk membuat proyek pustaka kelas baru, pilih File>Proyek Baru.>

  2. Di menu drop-down bahasa, pilih C#.

  3. Di kotak pencarian, masukkan pustaka kelas. Pilih Pustaka Kelas (.NET Framework) lalu pilih Berikutnya.

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

  1. Di Penjelajah Solusi, klik kanan Class1.cs dan pilih Ganti Nama pada menu konteks.

  2. Ubah nama dari Class1.cs menjadi sesuatu yang bermakna, seperti DebuggerSide.cs.

    Catatan

    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.

  3. Di Penjelajah Solusi, klik kanan Referensi dan pilih Tambahkan Referensi pada menu pintasan.

  4. Di kotak dialog Tambahkan Referensi, pada tab Telusuri, pilih Telusuri dan temukan Microsoft.VisualStudio.DebuggerVisualizers.DLL.

    Anda dapat menemukan DLL di subdirektori <Direktori Instal Visual Studio>\Common7\IDE\PublicAssemblies dari direktori penginstalan Visual Studio.

  5. Pilih OK.

  6. Di DebuggerSide.cs, tambahkan yang berikut ini ke arahan using:

    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 DebuggerSide objek untuk mengonfigurasi warisan dari kelas DialogDebuggerVisualizerdasar .

Mewarisi dari DialogDebuggerVisualizer

  1. Di DebuggerSide.cs, buka baris kode berikut:

    public class DebuggerSide

  2. Ubah kode menjadi:

    public class DebuggerSide : DialogDebuggerVisualizer

  3. Tambahkan konstruktor kosong sehingga Anda dapat meneruskan ke konstruktor kelas dasar kebijakan serialisasi yang akan digunakan untuk berkomunikasi antara komponen visualizer.

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

    Catatan

    Karena masalah keamanan yang dijelaskan dalam Pertimbangan sisi debugger khusus untuk .NET 5.0+, dimulai dengan Visual Studio 2022 versi 17.11, visualizer tidak akan dapat menentukan Legacy kebijakan formatter.

  4. 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 berisi kode yang benar-benar membuat kotak dialog visualizer atau antarmuka pengguna lain 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 arahan using untuk System.Windows.Forms.

Tambahkan System.Windows.Forms

  1. Di Penjelajah Solusi, klik kanan Referensi dan pilih Tambahkan Referensi pada menu pintasan.

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

  3. Pilih OK.

  4. Di DebuggerSide.cs, tambahkan yang berikut ini ke arahan 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

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

  2. Pada menu Build, pilih Build MyFirstVisualizer. Proyek harus berhasil dibangun. Perbaiki semua kesalahan build sebelum melanjutkan.

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

Menambahkan jenis untuk memvisualisasikan kode sisi debuggee

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

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

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

  2. Pada menu Build, pilih Build MyFirstVisualizer. Proyek harus berhasil dibangun. Perbaiki semua kesalahan build sebelum melanjutkan.

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

Menambahkan Metode Pengujian untuk menampilkan visualizer

  1. Tambahkan metode berikut ke kelas public DebuggerSide:

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

  2. Pada menu Build, pilih Build MyFirstVisualizer. Proyek harus berhasil dibangun. Perbaiki semua kesalahan build sebelum melanjutkan.

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

Menambahkan proyek aplikasi konsol ke solusi

  1. Di Penjelajah Solusi, klik kanan solusi, pilih Tambahkan, lalu pilih Proyek Baru.

  2. Pilih File>Baru>Proyek. Di menu drop-down bahasa, pilih C#. Di 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.

Catatan

Jika Anda ingin menguji visualizer dengan mudah menggunakan test harness, buat aplikasi konsol .NET Framework. Anda dapat membuat aplikasi konsol .NET sebagai gantinya, tetapi test harness yang dijelaskan nanti belum didukung untuk .NET, jadi Anda perlu menginstal visualizer untuk mengujinya. Untuk aplikasi konsol .NET, pertama 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

  1. Di Penjelajah Solusi, klik kanan MyTestConsole dan pilih Tambahkan Referensi pada menu pintasan.

  2. Dalam kotak dialog Tambahkan Referensi , buka tab Telusuri dan pilih Microsoft.VisualStudio.DebuggerVisualizers.DLL.

  3. Pilih OK.

  4. Klik kanan MyTestConsole dan pilih Tambahkan Referensi lagi.

  5. Dalam kotak dialog Tambahkan Referensi , buka tab Proyek dan pilih MyFirstVisualizer.

  6. Pilih OK.

Sekarang, Anda menambahkan kode untuk menyelesaikan test harness.

Menambahkan kode ke MyTestConsole

  1. Di Penjelajah Solusi, klik kanan Program.cs dan pilih Ubah Nama pada menu pintasan.

  2. Edit nama dari Program.cs menjadi sesuatu yang lebih bermakna, seperti TestConsole.cs.

    Catatan

    Visual Studio secara otomatis mengubah deklarasi kelas di TestConsole.cs agar sesuai dengan nama file baru.

  3. Di TestConsole.cs, tambahkan kode berikut ke arahan using:

    using MyFirstVisualizer;

  4. Dalam metode Main, tambahkan kode berikut:

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

Sekarang, Anda siap untuk menguji visualizer pertama Anda.

Menguji visualizer

  1. Di Penjelajah Solusi, klik kanan MyTestConsole dan pilih Tetapkan sebagai Proyek Startup pada menu pintasan.

  2. Pada menu Debug, pilih Mulai.

    Aplikasi konsol dimulai dan Visualizer muncul dan menampilkan string, "Halo, Dunia."

Selamat. Anda telah membangun dan menguji visualizer pertama Anda!

Jika Anda ingin menggunakan visualizer Anda di Visual Studio alih-alih hanya memanggilnya dari rangkaian pengujian, Anda harus menginstalnya. Untuk informasi selengkapnya, lihat Cara: Menginstal Visualizer.

Menambahkan objek data sisi debuggee

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

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

    Catatan

    Jika Anda menggunakan aplikasi konsol pengujian .NET Framework, pastikan Anda membuat proyek pustaka kelas .NET Framework.

  2. Pilih Selanjutnya. Dalam kotak dialog yang muncul, ketik nama MyDataObject, lalu pilih Buat.

  3. (Hanya pustaka kelas .NET Standard) Di Penjelajah Solusi, klik kanan proyek dan pilih Edit File Proyek. Ubah nilai <TargetFramework> menjadi netstandard2.0.

    <TargetFramework>netstandard2.0</TargetFramework>

  4. Di dalam namespace layanan MyDataObject, ganti kode default dengan kode berikut.

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

    Untuk visualizer baca-saja, seperti dalam contoh ini, tidak perlu menerapkan metode VisualizerObjectSource.

    Selanjutnya, perbarui proyek MyFirstVisualizer untuk menggunakan objek data baru.

  5. Di Penjelajah Solusi di bawah proyek MyFirstVisualizer, klik kanan node Referensi dan pilih Tambahkan Referensi.

  6. Di bawah Proyek, pilih proyek MyDataObject.

  7. Dalam kode atribut DebuggerSide.cs, perbarui nilai Target, ubah System.String menjadi MyDataObject.CustomDataObject.

    Target = typeof(MyDataObject.CustomDataObject),

  8. Dalam proyek MyFirstVisualizer, ganti kode untuk metode Show 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.

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

  10. Pada Program.cs, ganti kode pada metode Main dengan kode berikut.

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

DebuggerSide.TestShowVisualizer(customDataObject);

  11. (Aplikasi konsol.NET) Sertakan panggilan ke TestShowVisualizer dalam pernyataan try-catch, karena test harness tidak didukung.

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

    Aplikasi konsol memerlukan referensi runtime ke visualizer. Anda dapat mempertahankan referensi dengan menyimpan kode sebelumnya bukan mengomentarinya.

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

  13. Untuk aplikasi konsol .NET, salin MyFirstVisualizer.dll dan MyDataObject.dll ke folder yang dijelaskan dalam Cara: Menginstal Visualizer.

  14. Setelah menginstal visualizer, atur titik henti, jalankan aplikasi konsol, dan arahkan kursor ke customDataObject. Jika semuanya diatur dengan benar, Anda akan melihat ikon VisualizerIconkaca pembesar .

    Ikon kaca pembesar visualizer.

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

    Visualizer memperlihatkan Formulir Windows

Konten terkait