Share via

Pliki konfiguracji reguł analizy kodu

  • Artykuł

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łączenia lub wyłączenia jej do konfiguracji 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 editorconfig, [*.cs] aby wybrać wszystkie pliki C# z .cs rozszerzeniem pliku w bieżącym folderze, w tym podfoldery. 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 Pliki dodatkowe 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

Począwszy od zestawu .NET 5 SDK (obsługiwanego w programie Visual Studio 2019 lub nowszym), 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 te pliki zostaną nazwane jako .globalconfig, zostaną one niejawnie zastosowane do wszystkich projektów języka 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.

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 (-nowarn lub -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.

Zobacz też