Gambaran umum analisis kode sumber .NET

  • Artikel

Penganalisis platform kompilator .NET (Roslyn) memeriksa kode C# atau Visual Basic Anda untuk masalah kualitas kode dan gaya. Mulai dari .NET 5, penganalisis ini disertakan dengan .NET SDK dan Anda tidak perlu menginstalnya secara terpisah. Jika proyek Anda menargetkan .NET 5 atau yang lebih baru, analisis kode diaktifkan secara default. Jika proyek Anda menargetkan implementasi .NET yang berbeda, misalnya, .NET Core, .NET Standard, atau .NET Framework, Anda harus mengaktifkan analisis kode secara manual dengan mengatur properti EnableNETAnalyzers ke true.

Jika Anda tidak ingin pindah ke .NET 5+ SDK, memiliki proyek .NET Framework gaya non-SDK, atau lebih suka model berbasis paket NuGet, penganalisis juga tersedia dalam paket NuGet Microsoft.CodeAnalysis.NetAnalyzers. Anda mungkin lebih suka model berbasis paket untuk pembaruan versi sesuai permintaan.

Catatan

Penganalisis .NET adalah agnostik kerangka kerja target. Artinya, proyek Anda tidak perlu menargetkan implementasi .NET tertentu. Penganalisis bekerja untuk proyek yang menargetkan .NET 5+ serta versi .NET sebelumnya, seperti .NET Core 3.1 dan .NET Framework 4.7.2. Namun, untuk mengaktifkan analisis kode menggunakan properti EnableNETAnalyzers , proyek Anda harus mereferensikan proyek SDK.

Jika pelanggaran aturan ditemukan oleh penganalisis, pelanggaran tersebut dilaporkan sebagai saran, peringatan, atau kesalahan, tergantung pada bagaimana setiap aturan dikonfigurasi. Pelanggaran analisis kode muncul dengan awalan "CA" atau "IDE" untuk membedakannya dari kesalahan kompilator.

Analisis kualitas kode

Aturan analisis kualitas kode ("CAxxxx") memeriksa kode C# atau Visual Basic Anda untuk keamanan, performa, desain, dan masalah lainnya. Analisis diaktifkan, secara default, untuk proyek yang menargetkan .NET 5 atau yang lebih baru. Anda dapat mengaktifkan analisis kode pada proyek yang menargetkan versi .NET sebelumnya dengan mengatur properti EnableNETAnalyzers ke true. Anda juga dapat menonaktifkan analisis kode untuk proyek Anda dengan menyetel EnableNETAnalyzers ke false .

Tip

Jika Anda menggunakan Visual Studio, banyak aturan penganalisis memiliki perbaikan kode terkait yang dapat Anda terapkan untuk memperbaiki masalah. Perbaikan kode ditampilkan di menu ikon bola lampu.

Aturan yang diaktifkan

Aturan berikut diaktifkan, secara default, sebagai kesalahan atau peringatan di .NET 8. Aturan tambahan diaktifkan sebagai saran.

ID diagnostik Kategori Tingkat keparahan Versi ditambahkan Deskripsi
CA1416 Interoperabilitas Peringatan .NET 5 Memvalidasi kompatibilitas platform
CA1417 Interoperabilitas Peringatan .NET 5 Jangan gunakan OutAttribute pada parameter string untuk P/Invokes
CA1418 Interoperabilitas Peringatan .NET 6 Menggunakan string platform yang valid
CA1420 Interoperabilitas Peringatan .NET 7 Menggunakan fitur yang memerlukan marshalling runtime saat dinonaktifkan akan menghasilkan pengecualian run-time
CA1422 Interoperabilitas Peringatan .NET 7 Memvalidasi kompatibilitas platform
CA1831 Performa Peringatan .NET 5 Gunakan AsSpan alih-alih pengindeks berbasis rentang untuk string jika sesuai
CA1856 Performa Error .NET 8 Penggunaan atribut yang ConstantExpected salah
CA1857 Performa Peringatan .NET 8 Konstanta diharapkan untuk parameter
CA2013 Keandalan Peringatan .NET 5 Jangan gunakan ReferenceEquals dengan jenis nilai
CA2014 Keandalan Peringatan .NET 5 Jangan gunakan stackalloc dalam perulangan
CA2015 Keandalan Peringatan .NET 5 Jangan tentukan finalizer untuk jenis yang berasal dari MemoryManager<T>
CA2017 Keandalan Peringatan .NET 6 Jumlah parameter tidak cocok
CA2018 Keandalan Peringatan .NET 6 Argumen count untuk Buffer.BlockCopy menentukan jumlah byte yang akan disalin
CA2021 Keandalan Peringatan .NET 8 Jangan memanggil Enumerable.Cast<T> atau Enumerable.OfType<T> dengan tipe yang tidak kompatibel
CA2200 Penggunaan Peringatan .NET 5 Memunculkan ulang untuk mempertahankan detail tumpukan
CA2247 Penggunaan Peringatan .NET 5 Argumen yang diteruskan ke TaskCompletionSource konstruktor harus enum TaskCreationOptions alih-alih TaskContinuationOptions
CA2252 Penggunaan Error .NET 6 Ikut serta dalam fitur pratinjau
CA2255 Penggunaan Peringatan .NET 6 Atribut ModuleInitializer tidak boleh digunakan dalam pustaka
CA2256 Penggunaan Peringatan .NET 6 Semua anggota yang dideklarasikan dalam antarmuka induk harus memiliki implementasi dalam DynamicInterfaceCastableImplementationantarmuka -atribut
CA2257 Penggunaan Peringatan .NET 6 Anggota yang ditentukan pada antarmuka dengan DynamicInterfaceCastableImplementationAttribute harus static
CA2258 Penggunaan Peringatan .NET 6 Menyediakan DynamicInterfaceCastableImplementation antarmuka di Visual Basic tidak didukung
CA2259 Penggunaan Peringatan .NET 7 ThreadStatic hanya memengaruhi bidang statis
CA2260 Penggunaan Peringatan .NET 7 Gunakan parameter jenis yang benar
CA2261 Penggunaan Peringatan .NET 8 Jangan gunakan ConfigureAwaitOptions.SuppressThrowing dengan Task<TResult>

Anda dapat mengubah tingkat keparahan aturan ini untuk menonaktifkannya atau meningkatkannya menjadi kesalahan. Anda juga dapat mengaktifkan lebih banyak aturan.

  • Untuk daftar aturan yang disertakan dengan setiap versi .NET SDK, lihat Rilis analyzer.
  • Untuk daftar semua aturan kualitas kode, lihat Aturan kualitas kode.

Mengaktifkan aturan tambahan

Mode analisis mengacu pada konfigurasi analisis kode yang telah ditentukan sebelumnya di mana tidak ada, beberapa, atau semua aturan diaktifkan. Dalam mode analisis default (Default), hanya sejumlah kecil aturan yang diaktifkan sebagai peringatan build. Anda dapat mengubah mode analisis untuk proyek Anda dengan mengatur <AnalysisMode> properti dalam file proyek. Nilai yang diizinkan adalah:

Nilai Deskripsi
None Semua aturan dinonaktifkan. Anda dapat secara selektif memilih aturan individual untuk mengaktifkannya.
Default Mode default, saat aturan tertentu diaktifkan sebagai peringatan build, aturan tertentu diaktifkan sebagai saran IDE Visual Studio, dan sisanya dinonaktifkan.
Minimum Mode yang lebih agresif daripada Default mode. Saran tertentu yang sangat disarankan untuk penegakan build diaktifkan sebagai peringatan build. Untuk melihat aturan mana yang disertakan, periksa %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig file.
Recommended Mode yang lebih agresif daripada Minimum mode, di mana lebih banyak aturan diaktifkan sebagai peringatan build. Untuk melihat aturan mana yang disertakan, periksa %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig file.
All Semua aturan diaktifkan sebagai peringatan* build. Anda dapat secara selektif keluar dari aturan individual untuk menonaktifkannya.

* Aturan berikut tidak diaktifkan dengan mengatur AnalysisMode ke All atau dengan mengatur AnalysisLevel ke latest-all: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021, dan aturan penganalisis metrik kode (CA1501, CA1502, CA1505, CA1506, dan CA1509). Aturan warisan ini mungkin tidak digunakan lagi dalam versi mendatang. Namun, Anda masih dapat mengaktifkannya satu per satu menggunakan dotnet_diagnostic.CAxxxx.severity = <severity> entri.

Mulai dari .NET 6, Anda dapat menghilangkan <AnalysisMode> demi nilai majemuk untuk <AnalysisLevel> properti . Misalnya, nilai berikut memungkinkan sekumpulan aturan yang direkomendasikan untuk rilis terbaru: <AnalysisLevel>latest-Recommended</AnalysisLevel>. Untuk informasi selengkapnya, lihat AnalysisLevel .

Untuk menemukan tingkat keparahan default untuk setiap aturan yang tersedia dan apakah aturan diaktifkan dalam Default mode analisis atau tidak, lihat daftar lengkap aturan.

Perlakukan peringatan sebagai kesalahan

Jika Anda menggunakan -warnaserror bendera saat membuat proyek, semua peringatan analisis kode juga diperlakukan sebagai kesalahan. Jika Anda tidak ingin peringatan kualitas kode (CAxxxx) diperlakukan sebagai kesalahan di hadapan -warnaserror, Anda dapat mengatur CodeAnalysisTreatWarningsAsErrors properti MSBuild ke false dalam file proyek Anda.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

Anda masih akan melihat peringatan analisis kode apa pun, tetapi tidak akan merusak build Anda.

Pembaruan terkini

Secara default, Anda akan mendapatkan aturan analisis kode terbaru dan tingkat keparahan aturan default saat Anda meningkatkan ke versi .NET SDK yang lebih baru. Jika Anda tidak ingin perilaku ini, misalnya, jika Anda ingin memastikan bahwa tidak ada aturan baru yang diaktifkan atau dinonaktifkan, Anda dapat mengambil alihnya dengan salah satu cara berikut:

  • Atur AnalysisLevel properti MSBuild ke nilai tertentu untuk mengunci peringatan ke set tersebut. Saat meningkatkan ke SDK yang lebih baru, Anda masih akan mendapatkan perbaikan bug untuk peringatan tersebut, tetapi tidak ada peringatan baru yang akan diaktifkan dan tidak ada peringatan yang ada yang akan dinonaktifkan. Misalnya, untuk mengunci sekumpulan aturan ke aturan yang dikirim dengan versi 5.0 dari .NET SDK, tambahkan entri berikut ke file proyek Anda.

    <PropertyGroup>
  <AnalysisLevel>5.0</AnalysisLevel>
</PropertyGroup>

    Tip

    Nilai default untuk AnalysisLevel properti adalah latest, yang berarti Anda selalu mendapatkan aturan analisis kode terbaru saat Anda pindah ke versi .NET SDK yang lebih baru.

    Untuk informasi selengkapnya, dan untuk melihat daftar nilai yang mungkin, lihat AnalysisLevel.

  • Instal paket NuGet Microsoft.CodeAnalysis.NetAnalyzers untuk memisahkan pembaruan aturan dari pembaruan .NET SDK. Untuk proyek yang menargetkan .NET 5+, menginstal paket akan menonaktifkan penganalisis SDK bawaan. Anda akan mendapatkan peringatan build jika SDK berisi versi rakitan penganalisis yang lebih baru daripada paket NuGet. Untuk menonaktifkan peringatan, atur properti ke _SkipUpgradeNetAnalyzersNuGetWarningtrue.

    Catatan

    Jika Anda menginstal paket NuGet Microsoft.CodeAnalysis.NetAnalyzers, Anda tidak boleh menambahkan properti EnableNETAnalyzers ke file proyek atau file Directory.Build.props . Ketika paket NuGet diinstal dan EnableNETAnalyzers properti diatur ke true, peringatan build dihasilkan.

Analisis gaya kode

Aturan analisis gaya kode ("IDExxxx") memungkinkan Anda menentukan dan mempertahankan gaya kode yang konsisten di basis kode Anda. Pengaturan pengaktifan default adalah:

  • Build baris perintah: Analisis gaya kode dinonaktifkan, secara default, untuk semua proyek .NET pada build baris perintah.

    Mulai dari .NET 5, Anda dapat mengaktifkan analisis gaya kode pada build, baik di baris perintah maupun di dalam Visual Studio. Pelanggaran gaya kode muncul sebagai peringatan atau kesalahan dengan awalan "IDE". Ini memungkinkan Anda menerapkan gaya kode yang konsisten pada waktu build.

  • Visual Studio: Analisis gaya kode diaktifkan, secara default, untuk semua proyek .NET di dalam Visual Studio sebagai tindakan cepat pemfaktoran ulang kode.

Untuk daftar lengkap aturan analisis gaya kode, lihat Aturan gaya kode.

Aktifkan pada build

Dengan .NET 5 SDK dan versi yang lebih baru, Anda dapat mengaktifkan analisis gaya kode saat membangun dari baris perintah dan di Visual Studio. (Namun, karena alasan performa, beberapa aturan gaya kode masih hanya akan berlaku di Ide Visual Studio.)

Ikuti langkah-langkah ini untuk mengaktifkan analisis gaya kode pada build:

  1. Atur properti MSBuild EnforceCodeStyleInBuild ke true.

  2. Dalam file .editorconfig, konfigurasikan setiap aturan gaya kode "IDE" yang ingin Anda jalankan pada build sebagai peringatan atau kesalahan. Misalnya:

    [*.{cs,vb}]
# IDE0040: Accessibility modifiers required (escalated to a build warning)
dotnet_diagnostic.IDE0040.severity = warning

    Tip

    Mulai dari .NET 9, Anda juga dapat menggunakan format opsi untuk menentukan tingkat keparahan dan membuatnya dihormati pada waktu build. Misalnya:

    [*.{cs,vb}]
# IDE0040: Accessibility modifiers required (escalated to a build warning)
dotnet_style_require_accessibility_modifiers = always:warning

    Atau, Anda dapat mengonfigurasi seluruh kategori untuk menjadi peringatan atau kesalahan, secara default, lalu secara selektif menonaktifkan aturan dalam kategori yang tidak ingin Anda jalankan pada build. Misalnya:

    [*.{cs,vb}]

# Default severity for analyzer diagnostics with category 'Style' (escalated to build warnings)
dotnet_analyzer_diagnostic.category-Style.severity = warning

# IDE0040: Accessibility modifiers required (disabled on build)
dotnet_diagnostic.IDE0040.severity = silent

Menyembunyikan peringatan

Salah satu cara untuk menekan pelanggaran aturan adalah dengan mengatur opsi tingkat keparahan untuk ID aturan tersebut ke none dalam file EditorConfig. Misalnya:

dotnet_diagnostic.CA1822.severity = none

Untuk informasi selengkapnya dan cara lain untuk menekan peringatan, lihat Cara menekan peringatan analisis kode.

Menjalankan analisis kode sebagai Tindakan GitHub

GitHub Action dotnet/code-analysis memungkinkan Anda menjalankan penganalisis kode .NET sebagai bagian dari integrasi berkelanjutan (CI) dalam mode offline. Untuk informasi selengkapnya, lihat GitHub Action analisis kode .NET.

Penganalisis pihak ketiga

Selain penganalisis .NET resmi, Anda juga dapat menginstal penganalisis pihak ketiga, seperti StyleCop, Roslynator, XUnit Analyzers, dan Sonar Analyzer.

Lihat juga