Menyesuaikan aturan penganalisis Roslyn

Setiap aturan penganalisis Roslyn, atau diagnostik, memiliki status tingkat keparahan dan penekanan default yang dapat Anda sesuaikan untuk proyek Anda. Artikel ini membahas pengaturan tingkat keparahan penganalisis dan menekan pelanggaran penganalisis.

Tingkat keparahan

Di Visual Studio 2019 versi 16.3 dan yang lebih baru, Anda dapat mengonfigurasi tingkat keparahan aturan penganalisis dalam file EditorConfig, dari menu bola lampu, dan dari jendela Daftar Kesalahan.

Tabel berikut ini memperlihatkan berbagai opsi tingkat keparahan yang bisa Anda konfigurasi untuk diagnostik:

Tingkat keparahan (Penjelajah Solusi)	Tingkat keparahan (file EditorConfig)	Perilaku waktu-build	Perilaku editor
Kesalahan	error	Pelanggaran muncul di tab Kesalahan di jendela Daftar Kesalahan dan dalam output build baris perintah, dan menyebabkan build gagal.	Kode yang menyinggung digaris bawahi dengan garis berlekuk merah, dan ditandai dengan kotak merah kecil di bilah gulir.
Peringatan	warning	Pelanggaran muncul di tab Peringatan di jendela Daftar Kesalahan dan dalam output build baris perintah, tetapi tidak menyebabkan build gagal.	Kode yang menyinggung digarisbawahi dengan garis berlekuk hijau dan ditandai dengan kotak hijau kecil di bilah gulir.
Saran	suggestion	Pelanggaran muncul di tab Pesan di jendela Daftar Kesalahan tetapi tidak dalam output build baris perintah.	Kode yang terpengaruh digaris bawahi dengan garis berlekuk abu-abu dan ditandai dengan kotak abu-abu kecil di bilah gulir.
Diam	silent	Tidak terlihat oleh pengguna.	Tidak terlihat oleh pengguna, tetapi diagnostik dilaporkan ke mesin diagnostik IDE.
Tidak	none	Ditahan sepenuhnya.	Ditahan sepenuhnya.
Default	default	Sesuai dengan tingkat keparahan default aturan. Untuk menentukan nilai default untuk aturan, lihat jendela Propertinya.	Sesuai dengan tingkat keparahan default aturan.

Menampilkan pelanggaran aturan

Jika penganalisis menemukan pelanggaran aturan penganalisis, penganalisis melaporkannya di jendela Daftar Kesalahan dan di editor kode.

Cuplikan layar berikut menunjukkan pelanggaran aturan yang dilaporkan di jendela Daftar Kesalahan. Pelanggaran penganalisis yang dilaporkan dalam daftar kesalahan cocok dengan pengaturan tingkat keparahan aturan:

Pelanggaran aturan penganalisis juga muncul di editor kode sebagai garis berlekuk di bawah kode yang menyinggung. Misalnya, cuplikan layar berikut menunjukkan tiga pelanggaran: satu kesalahan (garis berlekuk merah), satu peringatan (garis berlekuk hijau), dan satu saran (tiga titik abu-abu):

Banyak diagnostik memiliki satu atau beberapa perbaikan kode terkait yang dapat Anda terapkan untuk memperbaiki pelanggaran aturan. Perbaikan kode ditampilkan di menu ikon bola lampu bersama dengan jenis Tindakan Cepat lainnya. Untuk informasi selengkapnya tentang perbaikan kode, lihat Tindakan Cepat Umum.

Mengonfigurasi tingkat keparahan

Anda dapat mengatur tingkat keparahan aturan menggunakan salah satu metode berikut:

• EditorConfig
• Menu bola lampu
• Jendela Daftar Kesalahan
• Penjelajah Solusi

Senyap vs. Tingkat keparahan tidak ada

Silent Aturan tingkat keparahan yang diaktifkan secara default berbeda dari aturan yang dinonaktifkan atau None tingkat keparahan:

• Jika perbaikan kode didaftarkan untuk Silent aturan tingkat keparahan, Visual Studio menawarkan perbaikan kode sebagai tindakan pemfaktoran ulang kode bola lampu meskipun diagnostik tersembunyi tidak terlihat oleh pengguna. Jika aturan tingkat keparahan dinonaktifkan sebagai None, perbaikan kode tidak ditawarkan.
• Entri yang mengatur tingkat keparahan beberapa aturan penganalisis sekaligus dalam file EditorConfig dapat mengonfigurasi Silent aturan tingkat keparahan secara massal. None Aturan tingkat keparahan tidak dapat dikonfigurasi dengan cara ini. Sebaliknya, mereka harus dikonfigurasi melalui entri yang mengatur tingkat keparahan dalam file EditorConfig untuk setiap ID aturan.

Mengatur tingkat keparahan aturan dalam file EditorConfig

File EditorConfig tersedia di Visual Studio 2019 versi 16.3 dan yang lebih baru.

Mengatur tingkat keparahan aturan dalam file EditorConfig lebih diutamakan daripada tingkat keparahan apa pun yang ditetapkan dalam seperangkat aturan atau di Penjelajah Solusi. Anda dapat mengonfigurasi tingkat keparahan baik secara manual dalam file EditorConfig atau secara otomatis melalui bola lampu yang muncul di samping pelanggaran.

Mengonfigurasi tingkat keparahan aturan secara manual dalam file EditorConfig

Untuk mengonfigurasi tingkat keparahan aturan, ikuti langkah-langkah berikut:

1. Tambahkan file EditorConfig ke proyek Anda, jika Anda belum memilikinya.

2. Tambahkan entri untuk setiap aturan yang ingin Anda konfigurasi di ekstensi file yang sesuai.

   Misalnya, entri untuk mengatur tingkat keparahan untuk CA1822 ke error untuk file C# adalah sebagai berikut:

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. Anda dapat mengatur tingkat keparahan aturan untuk setiap ID aturan diagnostik dalam file EditorConfig dengan sintaks berikut:

   dotnet_diagnostic.<rule ID>.severity = <severity>

4. Untuk penganalisis gaya kode IDE, Anda juga dapat mengonfigurasinya dalam file EditorConfig dengan menggunakan sintaks yang berbeda.

   Contohnya,dotnet_style_qualification_for_field = false:suggestion. Namun akan lebih diutamakan jika Anda mengatur tingkat keparahan menggunakan sintaks dotnet_diagnostic. Untuk informasi selengkapnya, lihat Konvensi bahasa untuk EditorConfig.

Mengatur tingkat keparahan beberapa aturan penganalisis sekaligus dalam file EditorConfig

Kemampuan untuk mengatur beberapa aturan penganalisis sekaligus dalam file EditorConfig tersedia di Visual Studio 2019 versi 16.5 dan yang lebih baru.

Anda dapat mengatur tingkat keparahan untuk kategori aturan penganalisis tertentu atau untuk semua aturan penganalisis dengan satu entri dalam file EditorConfig:

• Atur tingkat keparahan aturan untuk kategori aturan penganalisis:

  dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity>

• Atur tingkat keparahan aturan untuk semua aturan penganalisis:

  dotnet_analyzer_diagnostic.severity = <severity>

Entri yang mengonfigurasi beberapa aturan penganalisis sekaligus hanya berlaku untuk aturan yang diaktifkan secara default. Aturan penganalisis yang ditandai sebagai nonaktif secara default dalam paket penganalisis harus diaktifkan melalui entri dotnet_diagnostic.<rule ID>.severity = <severity> eksplisit.

Jika Anda memiliki beberapa entri yang berlaku untuk ID aturan tertentu, urutan prioritas untuk entri yang berlaku adalah sebagai berikut:

• Entri tingkat keparahan untuk aturan individual menurut ID lebih diutamakan daripada entri tingkat keparahan untuk kategori.
• Entri tingkat keparahan untuk kategori lebih diutamakan daripada entri tingkat keparahan untuk semua aturan penganalisis.

Pertimbangkan contoh EditorConfig berikut, di mana CA1822 adalah aturan performa:

[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion

Dalam contoh ini, ketiga entri berlaku untuk aturan performa CA1822. Namun, menggunakan aturan prioritas yang ditentukan, entri tingkat keparahan berbasis ID aturan pertama lebih diutamakan daripada entri berikutnya. Dalam contoh ini, CA1822 memiliki tingkat keparahan yang efektif dari error. Aturan performa yang tersisa memiliki tingkat keparahan warning. Aturan penganalisis yang bukan aturan performa memiliki tingkat keparahan suggestion.

Mengatur tingkat keparahan aturan dari menu bola lampu

Visual Studio menyediakan cara mudah untuk mengonfigurasi tingkat keparahan aturan dari menu bola lampu Tindakan Cepat. Ikuti langkah-langkah ini:

1. Setelah pelanggaran terjadi, arahkan mouse ke atas garis berlekuk pelanggaran di editor dan pilih Tampilkan perbaikan potensial untuk membuka menu bola lampu. Atau, letakkan kursor Anda pada baris dan tekan Ctrl+. (titik).

2. Dari menu bola lampu, arahkan mouse ke tingkat keparahan untuk pratinjau perubahan, lalu konfigurasikan tingkat keparahan sesuai dengan opsi berikut:

   • Mengonfigurasi <tingkat keparahan ID> aturan. Atur tingkat keparahan untuk aturan tertentu.

   • Mengonfigurasi tingkat keparahan untuk semua <penganalisis gaya> . Atur tingkat keparahan untuk semua aturan dalam kategori aturan tertentu.

   • Konfigurasikan tingkat keparahan untuk semua penganalisis. Atur tingkat keparahan untuk semua kategori aturan penganalisis.

     Dalam contoh berikut, pilih Sembunyikan atau konfigurasikan masalah>Konfigurasikan <tingkat keparahan ID> aturan.

     

3. Pilih salah satu opsi tingkat keparahan.

   

   Visual Studio menambahkan entri ke file EditorConfig untuk mengonfigurasi aturan ke tingkat keparahan yang diminta, seperti yang ditunjukkan dalam kotak pratinjau.

   Jika Anda belum memiliki file EditorConfig dalam proyek, Visual Studio akan membuatnya untuk Anda.

Mengatur tingkat keparahan aturan dari jendela Daftar Kesalahan

Visual Studio juga menyediakan cara mudah untuk mengonfigurasi tingkat keparahan aturan dari menu konteks daftar kesalahan. Ikuti langkah-langkah ini:

1. Setelah pelanggaran terjadi, klik kanan entri diagnostik di daftar kesalahan.

2. Dari menu konteks, pilih Atur tingkat keparahan, lalu pilih salah satu opsi tingkat keparahan.

   

   Visual Studio menambahkan entri ke file EditorConfig untuk mengonfigurasi aturan ke tingkat yang diminta.

   Jika Anda belum memiliki file EditorConfig dalam proyek, Visual Studio akan membuatnya untuk Anda.

Mengatur tingkat keparahan aturan dari Penjelajah Solusi

Untuk mengatur tingkat keparahan aturan dari Penjelajah Solusi, ikuti langkah-langkah berikut:

1. Di Penjelajah Solusi, perluasReferensi>Penganalisis (atauDependensi>Penganalisis untuk proyek .NET Core).

2. Perluas rakitan yang berisi aturan yang ingin Anda atur tingkat keparahannya.

3. Klik kanan aturan dan pilih Atur tingkat keparahan. Di menu konteks, pilih salah satu opsi tingkat keparahan.

   Visual Studio menambahkan entri ke file EditorConfig untuk mengonfigurasi aturan ke tingkat yang diminta. Jika proyek Anda menggunakan file seperangkat aturan alih-alih file EditorConfig, entri tingkat keparahan ditambahkan ke file seperangkat aturan.

   Jika Anda belum memiliki file EditorConfig atau file seperangkat aturan dalam proyek, Visual Studio akan membuat file EditorConfig baru untuk Anda.

Melihat penganalisis dan diagnostik dari Penjelajah Solusi

Anda dapat melakukan banyak penyesuaian diagnostik penganalisis dari Penjelajah Solusi. Jika Anda menginstal penganalisis sebagai paket NuGet, simpul Analyzers muncul di bawah node Referensi (atau node Dependensi untuk proyek .NET Core) di Penjelajah Solusi. Ikuti langkah-langkah berikut untuk melihat penganalisis dan diagnostik:

1. Di Penjelajah Solusi, perluas proyek Anda, perluas Referensi atau Dependensi, lalu perluas Penganalisis. Perluas salah satu rakitan penganalisis untuk melihat diagnostik di rakitan.

   Ikon di samping setiap diagnostik menunjukkan tingkat keparahannya:

   • x dalam lingkaran menunjukkan tingkat keparahan Kesalahan
   • ! dalam segitiga menunjukkan tingkat keparahan Peringatan
   • i dalam lingkaran solid menunjukkan tingkat keparahan Saran
   • i dalam lingkaran putus-putus menunjukkan tingkat keparahan Senyap
   • Panah menunjuk ke bawah dalam lingkaran solid menunjukkan tingkat keparahan Tidak Ada

   

2. Untuk melihat properti diagnostik, termasuk deskripsi dan tingkat keparahan defaultnya, klik kanan diagnostik, lalu pilih Properti. Atau, pilih diagnostik, lalu tekan Alt+Enter.

   Jendela Properti terbuka.

   

3. Untuk melihat properti untuk aturan gaya kode (awalan IDE) di jendela Properti , seperti tingkat keparahan default, atur properti EnforceCodeStyleInBuild ke true.

4. Untuk dokumentasi online untuk diagnostik, klik kanan diagnostik, lalu pilih Tampilkan Bantuan.

Mengonversi file seperangkat aturan yang ada ke file EditorConfig

Di Visual Studio 2019 versi 16.5 dan yang lebih baru, file seperangkat aturan tidak digunakan lagi demi file EditorConfig untuk konfigurasi penganalisis untuk kode terkelola. File EditorConfig lebih fleksibel dan memungkinkan Anda mengonfigurasi tingkat keparahan aturan penganalisis dan opsi penganalisis, termasuk opsi gaya kode Visual Studio IDE. Karena alat Visual Studio untuk konfigurasi tingkat keparahan aturan penganalisis sekarang dioptimalkan untuk bekerja dengan file EditorConfig alih-alih file seperangkat aturan, Anda dianjurkan untuk mengonversi proyek yang ada yang masih menggunakan file seperangkat aturan.

Saat Anda mengonversi file seperangkat aturan yang ada ke file EditorConfig, simpan di akar repositori Anda atau di folder solusi. Melakukannya memastikan bahwa pengaturan tingkat keparahan dari file ini secara otomatis berlaku untuk seluruh repositori atau solusi.

Anda dapat mengonversi file seperangkat aturan yang ada ke file EditorConfig dengan menggunakan editor seperangkat aturan atau baris perintah.

Catatan

Proyek .NET Core dan .NET Standard tidak mendukung perintah menu untuk seperangkat aturan di Penjelajah Solusi, misalnya, Buka Seperangkat Aturan Aktif. Untuk menentukan seperangkat aturan non-default untuk proyek .NET Core atau .NET Standard, tambahkan properti CodeAnalysisRuleSet secara manual ke file proyek. Anda masih dapat mengonfigurasi aturan dalam seperangkat aturan di editor seperangkat aturan.

Untuk menggunakan editor seperangkat aturan, ikuti langkah-langkah ini. Jika proyek Anda sudah menggunakan file seperangkat aturan tertentu untuk nilai propertinya CodeAnalysisRuleSet , Anda dapat mengonversinya ke file EditorConfig yang setara dari editor seperangkat aturan:

1. Klik dua kali file seperangkat aturan di Penjelajah Solusi.

   File seperangkat aturan terbuka di editor seperangkat aturan dengan bilah info yang dapat diklik di bagian atas.

   

2. Pilih tautan infobar untuk memigrasikan file editor seperangkat aturan.

3. Dari dialog Simpan Sebagai, pilih direktori tempat Anda ingin membuat file EditorConfig, lalu pilih Simpan.

   EditorConfig yang dihasilkan terbuka di editor. Selain itu, properti CodeAnalysisRuleSet MSBuild diperbarui dalam file proyek sehingga tidak lagi mereferensikan file seperangkat aturan asli.

Untuk menggunakan baris perintah, ikuti langkah-langkah berikut:

1. Pasang paket NuGet Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.

2. Jalankan RulesetToEditorconfigConverter.exe dari paket yang diinstal, dengan jalur ke file seperangkat aturan dan file EditorConfig sebagai argumen baris perintah.

   Contohnya:

   Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
   

Contoh berikut menunjukkan file seperangkat aturan untuk dikonversi ke file EditorConfig:

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

Contoh berikut menunjukkan file EditorConfig yang dihasilkan setelah konversi:

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning
dotnet_diagnostic.CA1821.severity = warning
dotnet_diagnostic.CA2213.severity = warning
dotnet_diagnostic.CA2231.severity = warning

Mengonfigurasi kode yang dihasilkan

Penganalisis berjalan pada file sumber dalam proyek dan melaporkan pelanggaran apa pun yang mereka temukan. Namun, pelanggaran ini tidak berguna untuk file yang dihasilkan sistem. Contohnya adalah file kode yang dihasilkan, seperti file kode yang dihasilkan desainer, file sumber sementara yang dihasilkan oleh sistem build, dan sebagainya. Untuk jenis file ini, pengguna tidak dapat mengedit file secara manual dan tidak khawatir tentang memperbaiki pelanggaran apa pun.

Oleh karena itu, secara default, driver penganalisis hanya memeriksa file dengan nama tertentu, ekstensi file, atau header file yang dibuat secara otomatis sebagai file kode yang dihasilkan. Misalnya, nama file yang diakhir dengan .designer.cs atau .generated.cs dianggap sebagai kode yang dihasilkan. Namun, heuristik ini mungkin tidak dapat mengidentifikasi semua file kode yang dihasilkan khusus dalam kode sumber pengguna.

Di Visual Studio 2019 versi 16.5 dan yang lebih baru, pengguna akhir dapat mengonfigurasi file dan folder tertentu untuk diperlakukan sebagai kode yang dihasilkan dalam file EditorConfig.

Untuk menambahkan konfigurasi seperti itu, ikuti langkah-langkah berikut:

1. Jika Anda belum memiliki file EditorConfig untuk proyek Anda, tambahkan file tersebut.

2. generated_code = true | false Tambahkan entri untuk file dan folder tertentu. Misalnya, untuk memperlakukan semua file yang namanya berakhir dengan .MyGenerated.cs sebagai kode yang dihasilkan, gunakan entri ini:

   [*.MyGenerated.cs]
   generated_code = true
   

Menyembunyikan pelanggaran

Anda dapat menekan pelanggaran aturan menggunakan berbagai metode. Untuk informasi, lihat Menyembunyikan pelanggaran analisis kode.

Penggunaan Baris Perintah

Saat Anda membangun proyek di baris perintah, pelanggaran aturan akan muncul di output build jika kondisi berikut terpenuhi:

• Penganalisis diinstal dengan .NET SDK atau sebagai paket NuGet, dan bukan sebagai ekstensi .vsix .

  Untuk penganalisis yang diinstal menggunakan .NET SDK, Anda mungkin perlu mengaktifkan penganalisis. Untuk gaya kode, Anda juga dapat menerapkan gaya kode pada build dengan mengatur properti MSBuild.

• Satu atau beberapa aturan dilanggar dalam kode proyek.

• Tingkat keparahan aturan yang dilanggar diatur ke peringatan, dalam hal ini pelanggaran tidak menyebabkan build gagal, atau kesalahan, dalam hal ini pelanggaran menyebabkan build gagal.

Verbositas output build tidak memengaruhi pelanggaran aturan ditampilkan atau tidak. Bahkan dengan verbositas yang tenang, pelanggaran aturan tetap muncul dalam output build.

Jika Anda terbiasa menjalankan analisis warisan dari baris perintah, baik dengan FxCopCmd.exe atau melalui msbuild dengan RunCodeAnalysis bendera , Anda dapat melakukannya dengan penganalisis kode sebagai gantinya.

Untuk melihat pelanggaran penganalisis di baris perintah saat Anda membangun proyek menggunakan msbuild, jalankan perintah yang mirip dengan:

msbuild myproject.csproj /target:rebuild /verbosity:minimal

Cuplikan layar berikut menunjukkan output build baris perintah dari membangun proyek yang berisi pelanggaran aturan penganalisis:

Proyek dependen

Dalam proyek .NET Core, jika Anda menambahkan referensi ke proyek yang memiliki penganalisis NuGet, Visual Studio secara otomatis menambahkan penganalisis tersebut ke proyek dependen. Untuk menonaktifkan perilaku ini (misalnya, jika proyek dependen adalah proyek pengujian unit), tandai paket NuGet sebagai privat dengan mengatur PrivateAssets atribut dalam file .csproj atau .vbproj dari proyek yang dirujuk:

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />

Konten terkait

• Gambaran umum penganalisis kode di Visual Studio
• Mengirimkan bug penganalisis kode
• Menggunakan seperangkat aturan
• Menyembunyikan pelanggaran analisis kode
• Opsi konfigurasi untuk analisis kode