Bagikan melalui

Cara: Membuat, Menginisialisasi, dan Mengonfigurasi Pengalihan Pelacakan

  • Artikel

Catatan

Artikel ini khusus untuk .NET Framework. Ini tidak berlaku untuk implementasi .NET yang lebih baru, termasuk .NET 6 dan versi yang lebih baru.

Pengalihan pelacakan memungkinkan Anda mengaktifkan, menonaktifkan, dan memfilter output pelacakan.

Membuat dan menginisialisasi pengalihan pelacakan

Untuk menggunakan pengalihan pelacakan, Anda harus terlebih dahulu membuatnya dan menempatkannya dalam kode Anda. Ada dua kelas yang telah ditentukan sebelumnya tempat Anda dapat membuat objek pengalihan: kelas System.Diagnostics.BooleanSwitch dan kelas System.Diagnostics.TraceSwitch. Anda akan menggunakan BooleanSwitch jika Anda hanya peduli tentang apakah pesan pelacakan muncul atau tidak; Anda akan menggunakan TraceSwitch jika Anda ingin membedakan di antara tingkat pelacakan. Jika Anda menggunakan TraceSwitch, Anda dapat menentukan pesan penelusuran kesalahan Anda sendiri dan mengaitkannya dengan tingkat pelacakan yang berbeda. Anda dapat menggunakan kedua jenis pengalihan dengan pelacakan atau penelusuran kesalahan. Secara default, BooleanSwitch dinonaktifkan dan TraceSwitch diatur ke tingkat TraceLevel.Off. Pengalihan pelacakan dapat dibuat dan ditempatkan di bagian mana pun dari kode Anda yang mungkin menggunakannya.

Meskipun Anda dapat mengatur tingkat pelacakan dan opsi konfigurasi lainnya dalam kode, sebaiknya gunakan file konfigurasi untuk mengelola status pengalihan Anda. Ini karena mengelola konfigurasi pengalihan Anda dalam sistem konfigurasi memberi Anda fleksibilitas yang lebih besar — Anda dapat mengaktifkan dan menonaktifkan berbagai pengalihan dan mengubah tingkat tanpa mengompilasi ulang aplikasi Anda.

Untuk membuat dan menginisialisasi pengalihan pelacakan

  1. Tentukan pengalihan sebagai jenis System.Diagnostics.BooleanSwitch atau jenis System.Diagnostics.TraceSwitch dan atur nama serta deskripsi pengalihan.

  2. Konfigurasikan pengalihan pelacakan Anda. Untuk informasi selengkapnya, lihat Mengonfigurasi pengalihan pelacakan.

    Kode berikut membuat dua pengalihan, salah satu dari setiap jenis:

    Dim dataSwitch As New BooleanSwitch("Data", "DataAccess module")
Dim generalSwitch As New TraceSwitch("General", "Entire application")

    System.Diagnostics.BooleanSwitch dataSwitch =
   new System.Diagnostics.BooleanSwitch("Data", "DataAccess module");
System.Diagnostics.TraceSwitch generalSwitch =
   new System.Diagnostics.TraceSwitch("General",
   "Entire application");

Mengonfigurasi pengalihan pelacakan

Setelah aplikasi didistribusikan, Anda masih dapat mengaktifkan atau menonaktifkan output pelacakan dengan mengonfigurasi pengalihan pelacakan di aplikasi Anda. Mengonfigurasi pengalihan berarti mengubah nilainya dari sumber eksternal setelah diinisialisasi. Anda dapat mengubah nilai objek pengalihan menggunakan file konfigurasi. Anda mengonfigurasi pengalihan pelacakan untuk mengaktifkan dan menonaktifkannya, atau untuk mengatur tingkatnya, menentukan jumlah, dan jenis pesan yang diteruskannya ke pendengar.

Pengalihan Anda dikonfigurasi menggunakan file .config. Untuk aplikasi Web, ini adalah file Web.config yang terkait dengan proyek. Dalam aplikasi Windows, file ini diberi nama (nama aplikasi).exe.config. Dalam aplikasi yang disebarkan, file ini harus berada di folder yang sama dengan executable.

Saat aplikasi Anda menjalankan kode yang membuat instans pengalihan untuk pertama kalinya, aplikasi tersebut memeriksa file konfigurasi untuk informasi tingkat pelacakan tentang pengalihan yang diberi nama. Sistem pelacakan memeriksa file konfigurasi hanya sekali untuk pengalihan tertentu — pertama kali aplikasi Anda membuat pengalihan.

Dalam aplikasi yang disebarkan, Anda mengaktifkan kode pelacakan dengan mengonfigurasi ulang objek pengalihan saat aplikasi Anda tidak berjalan. Biasanya ini melibatkan mengaktifkan dan menonaktifkan objek pengalihan atau dengan mengubah tingkat pelacakan, lalu menghidupkan ulang aplikasi Anda.

Saat Anda membuat instans pengalihan, Anda juga menginisialisasinya dengan menentukan dua argumen: argumen displayName dan argumen description. Argumen displayName konstruktor mengatur properti Switch.DisplayName dari instans kelas Switch. displayName adalah nama yang digunakan untuk mengonfigurasi pengalihan dalam file .config, dan argumen description harus mengembalikan deskripsi singkat tentang pengalihan dan pesan apa yang dikontrolnya.

Selain menentukan nama pengalihan yang akan dikonfigurasi, Anda juga harus menentukan nilai untuk pengalihan. Nilai ini adalah Bilangan Bulat. Untuk BooleanSwitch, nilai 0 sesuai dengan Off, dan nilai bukan nol apa pun sesuai dengan On. Untuk TraceSwitch, 0,1,2,3, dan 4 sesuai dengan Off, Error, Warning, Info, dan Verbose, berturut-turut. Angka apa pun yang lebih besar dari 4 dianggap sebagai Verbose, dan angka apa pun yang kurang dari nol dianggap sebagai Off.

Catatan

Di .NET Framework versi 2.0, Anda dapat menggunakan teks untuk menentukan nilai untuk sakelar. Misalnya, true untuk BooleanSwitch atau teks yang mewakili nilai enumerasi seperti Error untuk TraceSwitch. Baris <add name="myTraceSwitch" value="Error" /> sama dengan <add name="myTraceSwitch" value="1" />.

Agar pengguna akhir dapat mengonfigurasi pengalihan pelacakan aplikasi, Anda harus memberikan dokumentasi terperinci tentang pengalihan di aplikasi Anda. Anda harus memerinci pengalihan mana yang mengontrol apa dan cara mengaktifkan serta menonaktifkannya. Anda juga harus memberi pengguna akhir Anda file .config yang memiliki Bantuan yang sesuai di komentar.

Untuk mengonfigurasi pengalihan pelacakan

  1. Untuk menggunakan pengalihan pelacakan, Anda harus terlebih dahulu membuatnya dan menempatkannya dalam kode Anda seperti yang dijelaskan di bagian Membuat dan menginisialisasi pengalihan pelacakan.

  2. Jika proyek Anda tidak berisi file konfigurasi (app.config atau Web.config), dari menu Proyek, pilih Tambahkan Item Baru.

    • Visual Basic: Di kotak dialog Tambahkan Item Baru, pilih File Konfigurasi Aplikasi.

      File konfigurasi aplikasi dibuat dan dibuka. Ini adalah dokumen XML yang elemen akarnya adalah <configuration>.

    • Visual C#: Di kotak dialog Tambahkan Item Baru, pilih File XML. Beri nama file ini app.config. Di editor XML, setelah deklarasi XML, tambahkan XML berikut:

      <configuration>
</configuration>

      Saat proyek Anda dikompilasi, file app.config disalin ke folder output proyek dan diganti namanya menjadi applicationname.exe.config.

  3. Setelah tag<configuration>, tetapi sebelum tag </configuration>, tambahkan XML yang sesuai untuk mengonfigurasi pengalihan Anda. Contoh berikut menunjukkan BooleanSwitch dengan properti DisplayName dari DataMessageSwitch dan TraceSwitch dengan properti DisplayName dari TraceLevelSwitch.

    <system.diagnostics>
   <switches>
      <add name="DataMessagesSwitch" value="0" />
      <add name="TraceLevelSwitch" value="0" />
   </switches>
</system.diagnostics>

    Dalam konfigurasi ini, kedua pengalihan nonaktif.

  4. Jika Anda perlu mengaktifkan BooleanSwitch, seperti DataMessagesSwitch yang diperlihatkan dalam contoh sebelumnya, ubah Value menjadi bilangan bulat apa pun selain 0.

  5. Jika Anda perlu mengaktifkan TraceSwitch, seperti TraceLevelSwitch yang diperlihatkan dalam contoh sebelumnya, ubah Value ke pengaturan tingkat yang sesuai (1 hingga 4).

  6. Tambahkan komentar ke file .config sehingga pengguna akhir memiliki pemahaman yang jelas tentang nilai apa yang diubah untuk mengonfigurasi pengalihan dengan tepat.

    Contoh berikut menunjukkan bagaimana kode akhir, termasuk komentar, mungkin terlihat:

    <system.diagnostics>
   <switches>
      <!-- This switch controls data messages. In order to receive data
         trace messages, change value="0" to value="1" -->
      <add name="DataMessagesSwitch" value="0" />
      <!-- This switch controls general messages. In order to
         receive general trace messages change the value to the
         appropriate level. "1" gives error messages, "2" gives errors
         and warnings, "3" gives more detailed error information, and
         "4" gives verbose trace information -->
      <add name="TraceLevelSwitch" value="0" />
   </switches>
</system.diagnostics>

Lihat juga