Pliki konfiguracji reguł analizy kodu
Reguły analizy kodu mają różne opcje konfiguracji. Te opcje można określić jako pary klucz-wartość w jednym z następujących plików konfiguracji analizatora:
- EditorConfig plik: opcje konfiguracji oparte na plikach lub folderach.
- Plik Global AnalyzerConfig : opcje konfiguracji na poziomie projektu. Przydatne, gdy niektóre pliki projektu znajdują się poza folderem projektu.
Napiwek
Możesz również ustawić właściwości konfiguracji analizy kodu w pliku projektu. Te właściwości konfigurują analizę kodu na poziomie zbiorczym, od całkowitego włączania lub wyłączania analizy kodu do konfiguracji reguły na poziomie kategorii. Aby uzyskać więcej informacji, zobacz EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<Category> i AnalysisMode.
EditorConfig
EditorConfig pliki są używane do udostępniania opcji, które mają zastosowanie do określonych plików źródłowych lub folderów. Opcje są umieszczane w nagłówkach sekcji, aby zidentyfikować odpowiednie pliki i foldery. Dodaj wpis dla każdej reguły, którą chcesz skonfigurować, i umieść go w odpowiedniej sekcji rozszerzenia pliku, na przykład [*.cs].
[*.cs]
<option_name> = <option_value>
W powyższym przykładzie jest nagłówkiem sekcji, [*.cs] który editorconfig umożliwia wybranie wszystkich plików C# z .cs rozszerzeniem pliku w bieżącym folderze, w tym podfolderów. Kolejny wpis , <option_name> = <option_value>jest opcją analizatora, która zostanie zastosowana do wszystkich plików C#.
Konwencje plików można stosować EditorConfig do folderu, projektu lub całego repozytorium, umieszczając plik w odpowiednim katalogu. Te opcje są stosowane podczas wykonywania analizy w czasie kompilacji i podczas edytowania kodu w programie Visual Studio.
Uwaga
EditorConfig opcje mają zastosowanie tylko do plików źródłowych w projekcie lub katalogu. Pliki uwzględnione w projekcie jako AdditionalFiles nie są traktowane jako pliki źródłowe , a EditorConfig opcje nie są stosowane do tych plików. Aby zastosować opcję reguły do plików innych niż źródłowe, określ opcję w pliku konfiguracji globalnej.
Jeśli masz istniejący plik .editorconfig dla ustawień edytora, takich jak rozmiar wcięcia lub czy przycinanie końcowego odstępu, możesz umieścić opcje konfiguracji analizy kodu w tym samym pliku.
Napiwek
Program Visual Studio udostępnia szablon elementu ,editorconfig który ułatwia dodawanie jednego z tych plików do projektu. Aby uzyskać więcej informacji, zobacz Dodawanie EditorConfig pliku do projektu.
Przykład
Poniżej znajduje się przykładowy EditorConfig plik do konfigurowania opcji i ważności reguły:
# 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
Konfiguracja globalna analizatora
Można również skonfigurować opcje analizatora za pomocą plików global AnalyzerConfig . Te pliki są używane do udostępniania opcji, które mają zastosowanie do wszystkich plików źródłowych w projekcie, niezależnie od ich nazw plików lub ścieżek plików.
W przeciwieństwie do EditorConfig plików pliki konfiguracji globalnej nie mogą służyć do konfigurowania ustawień stylu edytora dla identyfikatorów IDE, takich jak rozmiar wcięcia lub czy przycinanie końcowego odstępu. Zamiast tego są one przeznaczone wyłącznie do określania opcji konfiguracji analizatora na poziomie projektu.
Formatuj
W przeciwieństwie do EditorConfig plików, które muszą mieć nagłówki sekcji, takie jak [*.cs], aby zidentyfikować odpowiednie pliki i foldery, pliki global AnalyzerConfig nie mają nagłówków sekcji. Zamiast tego wymagają wpisu najwyższego poziomu formularza is_global = true , aby odróżnić je od zwykłych EditorConfig plików. Oznacza to, że wszystkie opcje w pliku mają zastosowanie do całego projektu. Na przykład:
is_global = true
<option_name> = <option_value>
Nazewnictwo
W przeciwieństwie do EditorConfig plików, które muszą mieć nazwę .editorconfig, pliki konfiguracji globalnej nie muszą mieć określonej nazwy ani rozszerzenia. Jeśli jednak nazwisz te pliki jako .globalconfig, zostaną one niejawnie zastosowane do wszystkich projektów C# i Visual Basic w bieżącym folderze, w tym podfolderów. W przeciwnym razie należy jawnie dodać GlobalAnalyzerConfigFiles element do pliku projektu MSBuild:
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>
Rozważ następujące zalecenia dotyczące nazewnictwa:
- Użytkownicy końcowi powinni nazwać pliki konfiguracji globalnej .globalconfig.
- Twórcy pakietów NuGet powinni nazwać pliki konfiguracji <globalnej %Package_Name%>.globalconfig.
- Pliki konfiguracji globalnej wygenerowane przez narzędzia MSBuild powinny mieć nazwę <%Target_Name%>_Generated.globalconfig lub podobne.
Uwaga
Wpis is_global = true najwyższego poziomu nie jest wymagany, gdy plik ma nazwę .globalconfig, ale jest zalecany w celu zapewnienia przejrzystości.
Dołączanie warunkowe
Możesz użyć globalnego pliku konfiguracji, aby wyłączyć lub włączyć określone reguły analizy kodu w różnych środowiskach. Na przykład możesz wyłączyć niektóre reguły analizy kodu dla projektów testów jednostkowych. W tym celu można ustawić ważność odpowiednich reguł none w pliku konfiguracji, na przykład:
# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none
Następnie możesz dostosować kompilację, aby uwzględnić tylko plik konfiguracji w projektach testowych na podstawie warunków specyficznych dla kompilacji. Na przykład:
<ItemGroup Condition="'$(IsShipping)' == 'false'">
<!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
<GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>
Dystrybucja w pakietach NuGet
Pliki Global AnalyzerConfig można rozpowszechniać za pomocą pakietów NuGet. W tym celu dodaj plik props do pakietu NuGet. W pliku .props dodaj GlobalAnalyzerConfigFiles element w węźleProject:
<Project>
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
</ItemGroup>
</Project>
Przykład
Poniżej przedstawiono przykładowy plik global AnalyzerConfig do konfigurowania opcji i ważności reguły na poziomie projektu:
# 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
Pierwszeństwo
Zarówno pliki, jak EditorConfig i pliki global AnalyzerConfig określają parę klucz-wartość dla każdej opcji. Konflikty występują, gdy istnieje wiele wpisów z tym samym kluczem, ale różnymi wartościami. Następujące reguły pierwszeństwa są używane do rozwiązywania konfliktów.
| Lokalizacje wejścia powodujące konflikt | Reguła pierwszeństwa |
|---|---|
| W tym samym pliku konfiguracji | Wpis, który pojawi się później w pliku, wygrywa. Dotyczy to konfliktów wpisów w jednym EditorConfig pliku, a także w jednym pliku global AnalyzerConfig. |
| W dwóch EditorConfig plikach | Wpis w EditorConfig pliku, który jest głębiej w systemie plików, i dlatego ma dłuższą ścieżkę pliku, wygrywa. |
| W dwóch plikach global AnalyzerConfig | .NET 5: zgłaszane jest ostrzeżenie kompilatora i oba wpisy są ignorowane. .NET 6 i nowsze wersje: wpis z pliku o wyższej wartości global_level ma pierwszeństwo. Jeśli global_level plik nie jest jawnie zdefiniowany, a plik ma nazwę .globalconfig, global_level wartość domyślna 100to ; dla wszystkich innych plików global_level global AnalyzerConfig wartość domyślna to 0. global_level Jeśli wartości plików konfiguracji z wpisów powodujących konflikt są równe, zgłaszane jest ostrzeżenie kompilatora i oba wpisy są ignorowane. |
| EditorConfig W pliku i pliku Global AnalyzerConfig | Wpis w EditorConfig pliku wygrywa. |
Opcje ważności
W przypadku opcji konfiguracji ważności obowiązują następujące dodatkowe reguły pierwszeństwa:
Opcje ważności określone w wierszu polecenia jako opcje kompilatora (
-nowarnlub-warnaserror) zawsze zastępują opcje konfiguracji ważności określone w EditorConfig plikach Global AnalyzerConfig.Reguły pierwszeństwa dla konfliktów wpisów ważności z pliku zestawu reguł i EditorConfig plik lub global AnalyzerConfig jest niezdefiniowany.
Pliki zestawu reguł są przestarzałe na rzecz EditorConfig plików Global AnalyzerConfig. Zalecamy przekonwertowanie plików zestawu reguł na równoważny EditorConfig plik.
Aby uzyskać informacje o regułach pierwszeństwa dla powiązanych opcji ważności z różnymi kluczami, na przykład w przypadku określenia różnych ważności dla pojedynczej reguły i kategorii, w których znajduje się reguła, zobacz Opcje konfiguracji do analizy kodu.
