Opcje konfiguracji analizy kodu

Reguły analizy kodu mają różne opcje konfiguracji. Niektóre z tych opcji są określane jako pary klucz-wartość w pliku konfiguracji analizatora przy użyciu składni <option key> = <option value>. Inne opcje, które konfigurują analizę kodu jako całość, są dostępne jako właściwości MSBuild w pliku projektu.

Najbardziej typową opcją , którą skonfigurujesz, jest ważność reguły. Można skonfigurować poziom ważności dla dowolnej reguły, w tym reguły jakości kodu i reguły stylu kodu. Aby na przykład włączyć regułę jako ostrzeżenie, dodaj następującą parę klucz-wartość do pliku konfiguracji analizatora:

dotnet_diagnostic.<rule ID>.severity = warning

Możesz również skonfigurować dodatkowe opcje, aby dostosować zachowanie reguły:

• Reguły jakości kodu mają opcje zachowania, takie jak nazwy metod, do których należy zastosować regułę.
• Reguły stylu kodu mają opcje preferencji stylu, takie jak tam, gdzie nowe wiersze są pożądane.
• Reguły analizatora innych firm mogą definiować własne opcje konfiguracji z niestandardowymi nazwami kluczy i formatami wartości.

Opcje ogólne

Te opcje mają zastosowanie do analizy kodu jako całości. Nie można ich stosować tylko do określonej reguły.

• Tryb analizy
• Włączanie analizy kodu
• Wyklucz wygenerowany kod

Aby uzyskać dodatkowe opcje, zobacz Właściwości analizy kodu.

Tryb analizy

Zestaw .NET SDK zawiera wszystkie reguły analizy kodu, ale tylko niektóre z nich są domyślnie włączone. Tryb analizy określa, który, jeśli istnieje, zestaw reguł do włączenia. Możesz wybrać bardziej agresywny tryb analizy, w którym włączono większość lub wszystkie reguły. Możesz też wybrać bardziej konserwatywny tryb analizy, w którym większość lub wszystkie reguły są wyłączone, a następnie w razie potrzeby możesz wyrazić zgodę na określone reguły. Ustaw tryb analizy, dodając <właściwość AnalysisMode> MSBuild do pliku projektu.

<PropertyGroup>
  <AnalysisMode>Recommended</AnalysisMode>
</PropertyGroup>

Począwszy od platformy .NET 6, można również zbiorczo włączyć kategorię reguł przy użyciu <właściwości AnalysisMode<Category>> MSBuild.

Uwaga

Jeśli skonfigurujesz analizę kodu przy użyciu właściwości programu MSBuild, takich jak AnalysisMode, wszystkie opcje konfiguracji zbiorczej ustawione w pliku konfiguracji zostaną zignorowane. Jeśli na przykład zbiorczo włączono wszystkie reguły lub kategorię reguł w pliku .editorconfig, ta konfiguracja jest ignorowana.

Włączanie analizy kodu

Analiza kodu jest domyślnie włączona dla projektów przeznaczonych dla platformy .NET 5 i nowszych wersji. Jeśli masz zestaw .NET 5+ SDK, ale projekt jest przeznaczony dla innej implementacji platformy .NET, możesz ręcznie włączyć analizę kodu, ustawiając właściwość EnableNETAnalyzers w pliku projektu na true.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

Wyklucz wygenerowany kod

Ostrzeżenia analizatora kodu platformy .NET nie są przydatne w przypadku wygenerowanych plików kodu, takich jak pliki generowane przez projektanta, których użytkownicy nie mogą edytować w celu naprawienia naruszeń. W większości przypadków analizatory kodu pomijają wygenerowane pliki kodu i nie zgłaszają naruszeń tych plików.

Domyślnie pliki z określonymi rozszerzeniami plików lub automatycznie generowanymi nagłówkami plików są traktowane jako wygenerowane pliki kodu. Na przykład nazwa pliku kończąca się ciągiem .designer.cs lub .generated.cs jest uznawana za wygenerowany kod. Ta opcja konfiguracji umożliwia określenie dodatkowych wzorców nazewnictwa, które mają być traktowane jako wygenerowany kod. Dodatkowe pliki i foldery można skonfigurować, dodając generated_code = true | false wpis do pliku konfiguracji. Aby na przykład traktować wszystkie pliki, których nazwa kończy się .MyGenerated.cs jako wygenerowany kod, dodaj następujący wpis:

[*.MyGenerated.cs]
generated_code = true

Opcje specyficzne dla reguły

Opcje specyficzne dla reguły można stosować do jednej reguły, zestawu reguł lub wszystkich reguł. Opcje specyficzne dla reguły obejmują:

• Poziom ważności reguły
• Opcje specyficzne dla reguł jakości kodu

Poziom ważności

W poniższej tabeli przedstawiono różne ważności reguł, które można skonfigurować dla wszystkich reguł analizatora, w tym reguły jakości kodu i stylu kodu.

Wartość konfiguracji ważności	Zachowanie w czasie kompilacji
error	Naruszenia są wyświetlane jako błędy kompilacji i powodują niepowodzenie kompilacji.
warning	Naruszenia są wyświetlane jako ostrzeżenia kompilacji, ale nie powodują niepowodzenia kompilacji (chyba że masz opcję, aby traktować ostrzeżenia jako błędy).
suggestion	Naruszenia są wyświetlane jako komunikaty kompilacji i sugestie w środowisku IDE programu Visual Studio. (W programie Visual Studio sugestie są wyświetlane jako trzy szare kropki poniżej pierwszych dwóch znaków).
silent	Naruszenia nie są widoczne dla użytkownika. Jednak w przypadku reguł w stylu kodu funkcje generowania kodu programu Visual Studio nadal generują kod w tym stylu. Te reguły uczestniczą również w czyszczeniu i są wyświetlane w menu Szybkie akcje i refaktoryzacje w programie Visual Studio.
none	Reguła jest całkowicie pomijana. Jednak w przypadku reguł w stylu kodu funkcje generowania kodu programu Visual Studio nadal generują kod w tym stylu.
default	Używana jest domyślna ważność reguły. Domyślne ważności dla każdej wersji platformy .NET są wymienione w repozytorium roslyn-analyzers. W tej tabeli wyrażenie "Disabled" odpowiada nonewartości , "Hidden" odpowiada silentelementowi , a "Info" odpowiada .suggestion

Scope

• Pojedyncza reguła

  Aby ustawić ważność reguły dla pojedynczej reguły, użyj następującej składni.

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

• Kategoria reguł

  Aby ustawić domyślną ważność reguły dla kategorii reguł, użyj następującej składni. Jednak to ustawienie ważności ma wpływ tylko na reguły w tej kategorii, które są domyślnie włączone.

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

  Różne kategorie są wymienione i opisane w sekcji Kategorie reguł. Ponadto na stronie referencyjnej można znaleźć kategorię określonej reguły, na przykład CA1000.

• Wszystkie reguły

  Aby ustawić domyślną ważność reguły dla wszystkich reguł analizatora, użyj następującej składni. Jednak to ustawienie ważności dotyczy tylko reguł, które są domyślnie włączone.

  dotnet_analyzer_diagnostic.severity = <severity value>
  

Ważne

Podczas konfigurowania poziomu ważności dla wielu reguł z pojedynczym wpisem dla kategorii reguł lub dla wszystkich reguł ważność ma zastosowanie tylko do reguł, które są domyślnie włączone. Jeśli włączysz wszystkie reguły przy użyciu właściwości <programu MSBuild AnalysisMode> lub <AnalysisLevel>, wszystkie opcje zbiorcze dotnet_analyzer_diagnostic są ignorowane. Z tego powodu lepiej jest włączyć kategorię reguł, ustawiając <parametr AnalysisMode<Category>> na All.

Uwaga

Prefiks ustawiania ważności dla pojedynczej reguły dotnet_diagnosticjest nieco inny niż prefiks konfigurowania ważności za pomocą kategorii lub dla wszystkich reguł. dotnet_analyzer_diagnostic

Pierwszeństwo

Jeśli masz wiele wpisów konfiguracji ważności, które można zastosować do tego samego identyfikatora reguły, pierwszeństwo jest wybierane w następującej kolejności:

• Wpis dla kategorii ma pierwszeństwo przed wpisem dla wszystkich reguł analizatora.
• Wpis dla pojedynczej reguły według identyfikatora ma pierwszeństwo przed wpisem dla kategorii.

Rozważmy następujący przykład, w którym CA1822 ma kategorię "Wydajność":

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

W poprzednim przykładzie wszystkie trzy wpisy ważności mają zastosowanie do CA1822. Jednak przy użyciu określonych reguł pierwszeństwa pierwszy wpis oparty na identyfikatorze reguły wygrywa w kolejnych wpisach. W tym przykładzie ca1822 będzie mieć obowiązującą ważność error. Wszystkie inne reguły w kategorii "Wydajność" będą miały ważność warning.

Aby uzyskać informacje na temat sposobu decydowania o pierwszeństwie między plikami, zobacz sekcję Pierwszeństwo w artykule Pliki konfiguracji.