File konfigurasi untuk aturan analisis kode
Aturan analisis kode memiliki berbagai opsi konfigurasi. Anda menentukan opsi ini sebagai pasangan kunci-nilai dalam salah satu file konfigurasi penganalisis berikut:
- EditorConfig file: Opsi konfigurasi berbasis file atau berbasis folder.
- File Global AnalyzerConfig : Opsi konfigurasi tingkat proyek. Berguna ketika beberapa file proyek berada di luar folder proyek.
Tip
Anda juga dapat mengatur properti konfigurasi analisis kode di file proyek Anda. Properti ini mengonfigurasi analisis kode pada tingkat massal, dari mengaktifkan atau menonaktifkan analisis kode sepenuhnya ke konfigurasi aturan tingkat kategori. Untuk informasi selengkapnya, lihat EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<Category>, dan AnalysisMode.
EditorConfig
EditorConfig file digunakan untuk menyediakan opsi yang berlaku untuk file atau folder sumber tertentu. Opsi ditempatkan di bawah header bagian untuk mengidentifikasi file dan folder yang berlaku. Tambahkan entri untuk setiap aturan yang ingin Anda konfigurasi, dan letakkan di bawah bagian ekstensi file yang sesuai, misalnya, [*.cs].
[*.cs]
<option_name> = <option_value>
Dalam contoh di atas, [*.cs] adalah header bagian konfigurasi editor untuk memilih semua file C# dengan .cs ekstensi file dalam folder saat ini, termasuk subfolder. Entri berikutnya, , <option_name> = <option_value>adalah opsi penganalisis yang akan diterapkan ke semua file C#.
Anda dapat menerapkan EditorConfig konvensi file ke folder, proyek, atau seluruh repositori dengan menempatkan file di direktori yang sesuai. Opsi ini diterapkan saat menjalankan analisis pada waktu build dan saat Anda mengedit kode di Visual Studio.
Catatan
EditorConfig opsi hanya berlaku untuk file sumber dalam proyek atau direktori. File yang disertakan dalam proyek karena AdditionalFiles tidak dianggap sebagai file sumber , dan EditorConfig opsi tidak diterapkan ke file-file ini. Untuk menerapkan opsi aturan ke file non-sumber, tentukan opsi dalam file konfigurasi global.
Jika Anda memiliki file .editorconfig yang ada untuk pengaturan editor seperti ukuran inden atau apakah akan memangkas spasi kosong berikutnya, Anda dapat menempatkan opsi konfigurasi analisis kode dalam file yang sama.
Tip
Visual Studio menyediakan templat item .editorconfig yang memudahkan untuk menambahkan salah satu file ini ke proyek Anda. Untuk informasi selengkapnya, lihat Menambahkan EditorConfig file ke proyek.
Contoh
Berikut ini adalah contoh EditorConfig file untuk mengonfigurasi opsi dan tingkat keparahan aturan:
# Remove the line below if you want to inherit .editorconfig settings from higher directories
root = true
# C# files
[*.cs]
#### Core EditorConfig Options ####
# Indentation and spacing
indent_size = 4
indent_style = space
tab_width = 4
#### .NET Coding Conventions ####
# this. and Me. preferences
dotnet_style_qualification_for_method = true
#### Diagnostic configuration ####
# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning
Global AnalyzerConfig
Anda juga dapat mengonfigurasi opsi penganalisis dengan file AnalyzerConfig global. File-file ini digunakan untuk menyediakan opsi yang berlaku untuk semua file sumber dalam proyek, terlepas dari nama file atau jalur file mereka.
Tidak seperti EditorConfig file, file konfigurasi global tidak dapat digunakan untuk mengonfigurasi pengaturan gaya editor untuk IDEs, seperti ukuran inden atau apakah akan memangkas spasi kosong berikutnya. Sebaliknya, mereka dirancang murni untuk menentukan opsi konfigurasi penganalisis tingkat proyek.
Format
Tidak seperti EditorConfig file, yang harus memiliki header bagian, seperti [*.cs], untuk mengidentifikasi file dan folder yang berlaku, file AnalyzerConfig global tidak memiliki header bagian. Sebaliknya, mereka memerlukan entri tingkat atas formulir is_global = true untuk membedakannya dari file reguler EditorConfig . Ini menunjukkan bahwa semua opsi dalam file berlaku untuk seluruh proyek. Contohnya:
is_global = true
<option_name> = <option_value>
Penamaan
Tidak seperti EditorConfig file, yang harus diberi nama .editorconfig, file konfigurasi global tidak perlu memiliki nama atau ekstensi tertentu. Namun, jika Anda menamai file-file ini sebagai .globalconfig, maka file tersebut secara implisit diterapkan ke semua proyek C# dan Visual Basic dalam folder saat ini, termasuk subfolder. Jika tidak, Anda harus secara eksplisit menambahkan item ke GlobalAnalyzerConfigFiles file proyek MSBuild Anda:
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>
Pertimbangkan rekomendasi penamaan berikut:
- Pengguna akhir harus memberi nama file konfigurasi global mereka .globalconfig.
- Pembuat paket NuGet harus memberi nama file <konfigurasi global mereka %Package_Name%>.globalconfig.
- MSBuild tooling-generated global config files harus bernama <%Target_Name%>_Generated.globalconfig atau sejenisnya .
Catatan
Entri is_global = true tingkat atas tidak diperlukan saat file diberi nama .globalconfig, tetapi disarankan untuk kejelasan.
Penyertaan bersyarkat
Anda dapat menggunakan file konfigurasi global untuk menonaktifkan atau mengaktifkan aturan analisis kode tertentu di lingkungan yang berbeda. Misalnya, Anda mungkin ingin menonaktifkan beberapa aturan analisis kode untuk proyek pengujian unit. Untuk melakukannya, Anda dapat mengatur tingkat keparahan untuk aturan yang berlaku ke none dalam file konfigurasi, misalnya:
# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none
Anda kemudian dapat menyesuaikan build Anda untuk hanya menyertakan file konfigurasi dalam proyek pengujian berdasarkan kondisi khusus untuk build Anda. Contohnya:
<ItemGroup Condition="'$(IsShipping)' == 'false'">
<!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
<GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>
Distribusi dalam paket NuGet
File Global AnalyzerConfig dapat didistribusikan dengan paket NuGet. Untuk melakukannya, tambahkan file .props ke paket NuGet. Dalam file .props, tambahkan GlobalAnalyzerConfigFiles item di bawah simpulProject:
<Project>
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
</ItemGroup>
</Project>
Contoh
Berikut adalah contoh file AnalyzerConfig global untuk mengonfigurasi opsi dan tingkat keparahan aturan di tingkat proyek:
# Top level entry required to mark this as a global AnalyzerConfig file
is_global = true
# NOTE: No section headers for configuration entries
#### .NET Coding Conventions ####
# this. and Me. preferences
dotnet_style_qualification_for_method = true:warning
#### Diagnostic configuration ####
# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning
Prioritas
File EditorConfig dan file AnalyzerConfig global menentukan pasangan kunci-nilai untuk setiap opsi. Konflik muncul ketika ada beberapa entri dengan kunci yang sama tetapi nilai yang berbeda. Aturan prioritas berikut digunakan untuk mengatasi konflik.
| Lokasi entri yang bertentangan | Aturan prioritas |
|---|---|
| Dalam file konfigurasi yang sama | Entri yang muncul nanti dalam file menang. Ini berlaku untuk entri yang bertentangan dalam satu EditorConfig file dan juga dalam satu file AnalyzerConfig global. |
| Dalam dua EditorConfig file | Entri dalam EditorConfig file yang lebih dalam dalam sistem file, dan karenanya memiliki jalur file yang lebih panjang, menang. |
| Dalam dua file AnalyzerConfig global | .NET 5: Peringatan kompilator dilaporkan dan kedua entri diabaikan. .NET 6 dan versi yang lebih baru: Entri dari file dengan nilai yang lebih tinggi untuk global_level diutamakan. Jika global_level tidak didefinisikan secara eksplisit dan file diberi nama .globalconfig, global_level nilai default ke 100; untuk semua file AnalyzerConfig global lainnya, global_level default ke 0. global_level Jika nilai untuk file konfigurasi dengan entri yang bertentangan sama, peringatan kompilator akan dilaporkan dan kedua entri diabaikan. |
| EditorConfig Dalam file dan file Global AnalyzerConfig | Entri dalam EditorConfig file menang. |
Opsi tingkat keparahan
Untuk opsi konfigurasi tingkat keparahan, aturan prioritas tambahan berikut berlaku:
Opsi tingkat keparahan yang ditentukan di baris perintah sebagai opsi pengkompilasi (
-nowarnatau ) selalu menimpa opsi konfigurasi tingkat keparahan yang ditentukan dalam EditorConfig dan file AnalyzerConfig-warnaserrorglobal.Aturan prioritas untuk entri tingkat keparahan yang bertentangan dari file ruleset dan EditorConfig file AnalyzerConfig global atau tidak terdefinisi.
File ruleset tidak digunakan lagi untuk file EditorConfig AnalyzerConfig global. Kami menyarankan agar Anda mengonversi file ruleset ke file yang setaraEditorConfig.
Untuk informasi tentang aturan prioritas untuk opsi tingkat keparahan terkait dengan kunci yang berbeda, misalnya, ketika tingkat keparahan yang berbeda ditentukan untuk satu aturan dan untuk kategori yang aturannya termasuk dalam, lihat Opsi konfigurasi untuk analisis kode.
