Dostosowywanie reguł analizatora Roslyn

Każda reguła analizatora Roslyn lub diagnostyka ma domyślną ważność i stan pomijania, który można dostosować dla projektu. W tym artykule opisano ważność analizatora ustawień i pomijanie naruszeń analizatora.

Poziomy ważności

W programie Visual Studio 2019 w wersji 16.3 lub nowszej można skonfigurować ważność reguł analizatora w pliku EditorConfig z menu żarówki i w oknie Lista błędów.

W poniższej tabeli przedstawiono różne opcje ważności, które można skonfigurować dla diagnostyki:

Ważność (Eksplorator rozwiązań)	Ważność (plik EditorConfig)	Zachowanie w czasie kompilacji	Zachowanie edytora
Błąd	error	Naruszenia są wyświetlane na karcie Błąd w oknie Lista błędów i w danych wyjściowych kompilacji wiersza polecenia i powodują niepowodzenie kompilacji.	Kod obrażania jest podkreślony czerwoną linią wywijania i oznaczony małym czerwonym polem na pasku przewijania.
Ostrzeżenie	warning	Naruszenia są wyświetlane na karcie Ostrzeżenie w oknie Lista błędów i w danych wyjściowych kompilacji wiersza polecenia, ale nie powodują niepowodzenia kompilacji.	Kod obrażania jest podkreślony zielonym linią wywijanki i oznaczony małym zielonym polem na pasku przewijania.
Sugestia	suggestion	Naruszenia są wyświetlane na karcie Komunikat w oknie Lista błędów, ale nie w danych wyjściowych kompilacji wiersza polecenia.	Kod, którego dotyczy problem, jest podkreślony szarym linią zquiggle i oznaczony małym szarym polem na pasku przewijania.
Dyskretny	silent	Niewidoczne dla użytkownika.	Niewidoczne dla użytkownika, ale diagnostyka jest zgłaszana aparatowi diagnostycznemu IDE.
Brak	none	Całkowicie pominięte.	Całkowicie pominięte.
Wartość domyślna	default	Odpowiada domyślnej ważności reguły. Aby określić wartość domyślną reguły, wyświetl jej okno Właściwości.	Odpowiada domyślnej ważności reguły.

Wyświetlanie naruszeń reguł

Jeśli analizator znajdzie jakiekolwiek naruszenia reguł analizatora, zgłasza je w oknie Lista błędów i w edytorze kodu.

Poniższy zrzut ekranu przedstawia naruszenia reguł zgłoszone w oknie Lista błędów. Naruszenia analizatora zgłoszone na liście błędów są zgodne z ustawieniem poziomu ważności reguły:

Naruszenia reguły analizatora są również wyświetlane w edytorze kodu jako wiersze zwijania w kodzie obraźliwym. Na przykład na poniższym zrzucie ekranu przedstawiono trzy naruszenia: jeden błąd (czerwona linia zquiggle), jedno ostrzeżenie (zielona linia zquiggle) i jedna sugestia (trzy szare kropki):

Wiele diagnostyki ma co najmniej jedną skojarzą poprawkę kodu, którą można zastosować w celu skorygowania naruszenia reguły. Poprawki kodu są wyświetlane w menu ikon żarówki wraz z innymi typami szybkich akcji. Aby uzyskać więcej informacji na temat poprawek kodu, zobacz Typowe szybkie akcje.

Konfigurowanie poziomów ważności

Ważność reguły można ustawić przy użyciu dowolnej z następujących metod:

• EditorConfig
• Menu żarówki
• Okno Lista błędów
• Eksplorator rozwiązań

Dyskretna a brak ważności

Silent Reguły ważności, które są domyślnie włączone, różnią się od wyłączonych lub None reguł ważności:

• Jeśli poprawka kodu jest zarejestrowana dla Silent reguły ważności, program Visual Studio oferuje poprawkę kodu jako akcję refaktoryzacji żarówki, nawet jeśli ukryta diagnostyka nie jest widoczna dla użytkownika. Jeśli reguła ważności jest wyłączona jako None, poprawka kodu nie jest oferowana.
• Wpisy, które ustawiają ważność wielu reguł analizatora jednocześnie w pliku EditorConfig, mogą zbiorczo konfigurować Silent reguły ważności. None Nie można skonfigurować w ten sposób reguł ważności. Zamiast tego należy skonfigurować je za pomocą wpisów, które ustawiają ważność w pliku EditorConfig dla każdego identyfikatora reguły.

Ustawianie ważności reguły w pliku EditorConfig

Pliki EditorConfig są dostępne w programie Visual Studio 2019 w wersji 16.3 lub nowszej.

Ustawienie ważności reguły w pliku EditorConfig ma pierwszeństwo przed dowolną ważnością ustawioną w zestawie reguł lub w Eksplorator rozwiązań. Ważność można skonfigurować ręcznie w pliku EditorConfig lub automatycznie za pomocą żarówki wyświetlanej obok naruszenia.

Ręczne konfigurowanie ważności reguły w pliku EditorConfig

Aby skonfigurować ważność reguły, wykonaj następujące kroki:

1. Dodaj plik EditorConfig do projektu, jeśli jeszcze go nie masz.

2. Dodaj wpis dla każdej reguły, którą chcesz skonfigurować w ramach odpowiedniego rozszerzenia pliku.

   Na przykład wpis ustawiający ważność dla ca1822 error dla plików języka C# jest następujący:

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. Ważność reguły dla każdego identyfikatora reguły diagnostycznej w pliku EditorConfig można ustawić przy użyciu następującej składni:

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

4. W przypadku analizatorów w stylu kodu IDE można je również skonfigurować w pliku EditorConfig przy użyciu innej składni.

   Na przykład dotnet_style_qualification_for_field = false:suggestion. Jeśli jednak ustawisz ważność przy użyciu dotnet_diagnostic składni, pierwszeństwo ma. Aby uzyskać więcej informacji, zobacz Konwencje językowe dla pliku EditorConfig.

Ustawianie ważności wielu reguł analizatora jednocześnie w pliku EditorConfig

Możliwość ustawiania wielu reguł analizatora jednocześnie w pliku EditorConfig jest dostępna w programie Visual Studio 2019 w wersji 16.5 lub nowszej.

Można ustawić ważność dla określonej kategorii reguł analizatora lub dla wszystkich reguł analizatora z pojedynczym wpisem w pliku EditorConfig:

• Ustaw ważność reguły dla kategorii reguł analizatora:

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

• Ustaw ważność reguły dla wszystkich reguł analizatora:

  dotnet_analyzer_diagnostic.severity = <severity>

Wpisy, które konfigurują wiele reguł analizatora jednocześnie, mają zastosowanie tylko do reguł, które są domyślnie włączone. Reguły analizatora, które są domyślnie wyłączone w pakiecie analizatora, muszą być włączone za pomocą jawnych dotnet_diagnostic.<rule ID>.severity = <severity> wpisów.

Jeśli masz wiele wpisów, które mają zastosowanie do określonego identyfikatora reguły, kolejność pierwszeństwa dla odpowiedniego wpisu jest następująca:

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

Rozważmy następujący przykład EditorConfig, w którym CA1822 jest regułą wydajności:

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

W tym przykładzie wszystkie trzy wpisy dotyczą reguły wydajności CA1822. Jednak przy użyciu określonych reguł pierwszeństwa pierwszy wpis ważności opartej na identyfikatorze reguły ma pierwszeństwo przed kolejnymi wpisami. W tym przykładzie ca1822 ma obowiązującą ważność error. Pozostałe reguły wydajności mają ważność warning. Reguły analizatora, które nie są regułami suggestionwydajności, mają ważność .

Ustawianie ważności reguły z menu żarówki

Program Visual Studio zapewnia wygodny sposób konfigurowania ważności reguły z menu żarówki Szybkie akcje . Wykonaj te kroki:

1. Po wystąpieniu naruszenia zatrzymaj wskaźnik myszy na linii przełącznika naruszenia w edytorze i wybierz pozycję Pokaż potencjalne poprawki , aby otworzyć menu żarówki. Możesz też umieścić kursor w wierszu i nacisnąć klawisze Ctrl+. (kropka).

2. W menu żarówki umieść wskaźnik myszy na poziomie ważności dla podglądu zmiany, a następnie skonfiguruj ważność zgodnie z następującymi opcjami:

   • Skonfiguruj ważność <identyfikatora> reguły. Ustaw ważność dla określonej reguły.

   • Skonfiguruj ważność dla wszystkich <analizatorów stylów> . Ustaw ważność dla wszystkich reguł w określonej kategorii reguł.

   • Skonfiguruj ważność dla wszystkich analizatorów. Ustaw ważność dla wszystkich kategorii reguł analizatora.

     W poniższym przykładzie wybierz pozycję Pomiń lub skonfiguruj problemy>Konfigurowanie <ważności identyfikatora> reguły.

     

3. Wybierz jedną z opcji ważności.

   

   Program Visual Studio dodaje wpis do pliku EditorConfig, aby skonfigurować regułę do żądanego poziomu ważności, jak pokazano w polu podglądu.

   Jeśli nie masz jeszcze pliku EditorConfig w projekcie, program Visual Studio utworzy go dla Ciebie.

Ustawianie ważności reguły w oknie Lista błędów

Program Visual Studio zapewnia również wygodny sposób konfigurowania ważności reguły z menu kontekstowego listy błędów. Wykonaj te kroki:

1. Po wystąpieniu naruszenia kliknij prawym przyciskiem myszy wpis diagnostyczny na liście błędów.

2. Z menu kontekstowego wybierz pozycję Ustaw ważność, a następnie wybierz jedną z opcji ważności.

   

   Program Visual Studio dodaje wpis do pliku EditorConfig, aby skonfigurować regułę do żądanego poziomu.

   Jeśli nie masz jeszcze pliku EditorConfig w projekcie, program Visual Studio utworzy go dla Ciebie.

Ustawianie ważności reguły z Eksplorator rozwiązań

Aby ustawić ważność reguły z Eksplorator rozwiązań, wykonaj następujące kroki:

1. W Eksplorator rozwiązań rozwiń węzeł Analizatory odwołań>(lub Analizatory zależności>dla projektów platformy .NET Core).

2. Rozwiń zestaw zawierający regułę, dla której chcesz ustawić ważność.

3. Kliknij prawym przyciskiem myszy regułę i wybierz pozycję Ustaw ważność. W menu kontekstowym wybierz jedną z opcji ważności.

   Program Visual Studio dodaje wpis do pliku EditorConfig, aby skonfigurować regułę do żądanego poziomu. Jeśli projekt używa pliku zestawu reguł zamiast pliku EditorConfig, wpis ważności zostanie dodany do pliku zestawu reguł.

   Jeśli nie masz jeszcze pliku EditorConfig lub pliku zestawu reguł w projekcie, program Visual Studio utworzy nowy plik EditorConfig.

Wyświetlanie analizatorów i diagnostyki z Eksplorator rozwiązań

Wiele możliwości dostosowywania diagnostyki analizatora można wykonać z Eksplorator rozwiązań. Jeśli zainstalujesz analizator jako pakiet NuGet, węzeł Analizatory pojawi się w węźle Odwołania (lub węźle Zależności dla projektów platformy .NET Core) w Eksplorator rozwiązań. Wykonaj następujące kroki, aby wyświetlić analizatory i diagnostykę:

1. W Eksplorator rozwiązań rozwiń projekt, rozwiń węzeł Odwołania lub Zależności, a następnie rozwiń węzeł Analizatory. Rozwiń jeden z zestawów analizatorów, aby wyświetlić diagnostykę w zestawie.

   Ikona obok każdej diagnostyki wskazuje jej poziom ważności:

   • xw okręgu wskazuje ważność błędu
   • ! w trójkącie wskazuje ważność ostrzeżenia
   • iw okręgu stałym wskazuje ważność sugestii
   • iw okręgu kropkowym wskazuje ważność dyskretnego
   • Strzałka skierowana w dół w okręgu stałym wskazuje ważność none

   

2. Aby wyświetlić właściwości diagnostyki, w tym jej opis i ważność domyślną, kliknij prawym przyciskiem myszy diagnostykę, a następnie wybierz polecenie Właściwości. Możesz też wybrać diagnostykę, a następnie naciśnij klawisz Alt+Enter.

   Zostanie wyświetlone okno Właściwości .

   

3. Aby wyświetlić właściwości reguł stylu kodu (prefiks IDE) w oknie Właściwości , takim jak ważność domyślna, ustaw właściwość EnforceCodeStyleInBuild na truewartość .

4. Aby uzyskać dokumentację online dotyczącą diagnostyki, kliknij prawym przyciskiem myszy diagnostykę, a następnie wybierz pozycję Wyświetl pomoc.

Konwertowanie istniejącego pliku zestawu reguł na plik EditorConfig

W programie Visual Studio 2019 w wersji 16.5 lub nowszej pliki zestawu reguł są przestarzałe na rzecz plików EditorConfig dla konfiguracji analizatora dla kodu zarządzanego. Pliki EditorConfig są bardziej elastyczne i umożliwiają skonfigurowanie zarówno ważności reguł analizatora, jak i opcji analizatora, w tym opcji stylu kodu środowiska IDE programu Visual Studio. Ponieważ narzędzia programu Visual Studio dla konfiguracji ważności reguł analizatora są teraz zoptymalizowane pod kątem pracy z plikami EditorConfig zamiast plików zestawu reguł, zachęcamy do konwertowania istniejących projektów, które nadal używają plików zestawu reguł.

Po przekonwertowaniu istniejącego pliku zestawu reguł na plik EditorConfig zapisz go w katalogu głównym repozytorium lub w folderze rozwiązania. Dzięki temu ustawienia ważności tego pliku będą automatycznie stosowane do całego repozytorium lub rozwiązania.

Istniejący plik zestawu reguł można przekonwertować na plik EditorConfig przy użyciu edytora zestawu reguł lub wiersza polecenia.

Uwaga

Projekty .NET Core i .NET Standard nie obsługują poleceń menu dla zestawów reguł w Eksplorator rozwiązań, na przykład Otwórz aktywny zestaw reguł. Aby określić zestaw reguł innych niż domyślne dla projektu .NET Core lub .NET Standard, ręcznie dodaj właściwość CodeAnalysisRuleSet do pliku projektu. Nadal można skonfigurować reguły w zestawie reguł w edytorze zestawu reguł.

Aby użyć edytora zestawu reguł, wykonaj następujące kroki. Jeśli projekt używa już określonego pliku zestawu reguł dla jego CodeAnalysisRuleSet wartości właściwości, możesz przekonwertować go na równoważny plik EditorConfig z edytora zestawu reguł:

1. Kliknij dwukrotnie plik zestawu reguł w Eksplorator rozwiązań.

   Plik zestawu reguł zostanie otwarty w edytorze zestawu reguł z klikalnym paskiem informacyjnym u góry.

   

2. Wybierz link paska informacji, aby przeprowadzić migrację pliku edytora zestawu reguł.

3. W oknie dialogowym Zapisz jako wybierz katalog, w którym chcesz wygenerować plik EditorConfig, a następnie wybierz pozycję Zapisz.

   Wygenerowany plik EditorConfig zostanie otwarty w edytorze. Ponadto właściwość CodeAnalysisRuleSet MSBuild jest aktualizowana w pliku projektu, aby nie odwoływać się do oryginalnego pliku zestawu reguł.

Aby użyć wiersza polecenia, wykonaj następujące kroki:

1. Zainstaluj pakiet NuGet Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.

2. Wykonaj RulesetToEditorconfigConverter.exe z zainstalowanego pakietu ze ścieżkami do pliku zestawu reguł i plik EditorConfig jako argumenty wiersza polecenia.

   Na przykład:

   Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
   

W poniższym przykładzie pokazano plik zestawu reguł, który ma być konwertowany na plik EditorConfig:

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

Poniższy przykład przedstawia wynikowy plik EditorConfig po konwersji:

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning
dotnet_diagnostic.CA1821.severity = warning
dotnet_diagnostic.CA2213.severity = warning
dotnet_diagnostic.CA2231.severity = warning

Konfigurowanie wygenerowanego kodu

Analizatory są uruchamiane na plikach źródłowych w projekcie i zgłaszają wszelkie napotkane naruszenia. Jednak te naruszenia nie są przydatne w przypadku plików generowanych przez system. Przykłady to generowane pliki kodu, takie jak pliki kodu generowane przez projektanta, tymczasowe pliki źródłowe generowane przez system kompilacji itd. W przypadku tych typów plików użytkownicy nie mogą ręcznie edytować plików i nie są zaniepokojeni naprawieniem żadnych naruszeń.

W związku z tym sterownik analizatora domyślnie sprawdza tylko pliki o określonych nazwach, rozszerzeniach plików lub automatycznie wygenerowanych nagłówkach plików jako wygenerowanych plikach kodu. Na przykład nazwa pliku kończąca się .designer.cs lub .generated.cs jest traktowana jako wygenerowany kod. Jednak te heurystyki mogą nie być w stanie zidentyfikować wszystkich niestandardowych wygenerowanych plików kodu w kodzie źródłowym użytkownika.

W programie Visual Studio 2019 w wersji 16.5 lub nowszej użytkownicy końcowi mogą skonfigurować określone pliki i foldery, które będą traktowane jako wygenerowany kod w pliku EditorConfig.

Aby dodać taką konfigurację, wykonaj następujące kroki:

1. Jeśli nie masz jeszcze pliku EditorConfig dla projektu, dodaj go.

2. generated_code = true | false Dodaj wpis dla określonych plików i folderów. Aby na przykład traktować wszystkie pliki, których nazwa kończy się .MyGenerated.cs jako wygenerowany kod, użyj następującego wpisu:

   [*.MyGenerated.cs]
   generated_code = true
   

Pomijanie naruszeń

Naruszenia reguł można pominąć przy użyciu różnych metod. Aby uzyskać informacje, zobacz Pomijanie naruszeń analizy kodu.

Użycie wiersza polecenia

Podczas kompilowanie projektu w wierszu polecenia naruszenia reguły są wyświetlane w danych wyjściowych kompilacji, jeśli spełnione są następujące warunki:

• Analizatory są instalowane z zestawem .NET SDK lub pakietem NuGet, a nie jako rozszerzenie .vsix .

  W przypadku analizatorów zainstalowanych przy użyciu zestawu .NET SDK może być konieczne włączenie analizatorów. W przypadku stylów kodu można również wymusić style kodu na kompilacjach , ustawiając właściwość MSBuild.

• Co najmniej jedna reguła jest naruszana w kodzie projektu.

• Poziom ważności naruszonej reguły jest ustawiony na ostrzeżenie, w którym przypadku naruszenia nie powodują niepowodzenia kompilacji lub błędu, w którym przypadku naruszenia powodują niepowodzenie kompilacji.

Szczegółowość danych wyjściowych kompilacji nie ma wpływu na to, czy są wyświetlane naruszenia reguły. Nawet w przypadku cichej szczegółowości naruszenia reguł są wyświetlane w danych wyjściowych kompilacji.

Jeśli jesteś przyzwyczajony do uruchamiania starszej analizy z poziomu wiersza polecenia, z FxCopCmd.exe lub za pośrednictwem msbuild z flagą RunCodeAnalysis , możesz to zrobić za pomocą analizatorów kodu.

Aby wyświetlić naruszenia analizatora w wierszu polecenia podczas kompilowania projektu przy użyciu programu msbuild, uruchom polecenie podobne do:

msbuild myproject.csproj /target:rebuild /verbosity:minimal

Poniższy zrzut ekranu przedstawia dane wyjściowe kompilacji wiersza polecenia z kompilowania projektu zawierającego naruszenie reguły analizatora:

Projekty zależne

W projekcie platformy .NET Core, jeśli dodasz odwołanie do projektu z analizatorami NuGet, program Visual Studio automatycznie dodaje te analizatory do projektu zależnego. Aby wyłączyć to zachowanie (na przykład jeśli projekt zależny jest projektem testowym jednostkowym), oznacz pakiet NuGet jako prywatny, ustawiając PrivateAssets atrybut w pliku csproj lub vbproj projektu, do których się odwołujesz:

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />

Powiązana zawartość

• Omówienie analizatorów kodu w programie Visual Studio
• Przesyłanie usterki analizatora kodu
• Korzystanie z zestawów reguł
• Pomijanie naruszeń analizy kodu
• Opcje konfiguracji analizy kodu