Omówienie analizy kodu źródłowego platformy .NET

Analizatory platformy kompilatora .NET (Roslyn) sprawdzają kod C# lub Visual Basic pod kątem problemów z jakością kodu i stylem. Te analizatory są dołączone do zestawu .NET SDK i nie trzeba ich instalować oddzielnie. Jeśli projekt jest przeznaczony dla platformy .NET 5 lub nowszej, analiza kodu jest domyślnie włączona. (Aby uzyskać informacje na temat włączania analizy kodu w projektach przeznaczonych dla platformy .NET Framework, zobacz Włączanie analizy kodu w starszych projektach).

Jeśli naruszenia reguł zostaną znalezione przez analizatora, są zgłaszane jako sugestia, ostrzeżenie lub błąd, w zależności od konfiguracji każdej reguły. Naruszenia analizy kodu są wyświetlane z prefiksem "CA" lub "IDE", aby odróżnić je od błędów kompilatora.

Analiza jakości kodu

Reguły analizy jakości kodu ("CAxxxx") sprawdzają kod C# lub Visual Basic pod kątem zabezpieczeń, wydajności, projektowania i innych problemów. Analiza jest domyślnie włączona dla projektów przeznaczonych dla platformy .NET 5 lub nowszej. Analizę kodu w projektach korzystających z wcześniejszych wersji .NET można włączyć, ustawiając właściwość EnableNETAnalyzers na true. Możesz również wyłączyć analizę kodu dla projektu, ustawiając EnableNETAnalyzers na false.

Wskazówka

Jeśli używasz programu Visual Studio, wiele reguł analizatora ma przypisane poprawki kodu , które można zastosować, aby automatycznie naprawić problem. Poprawki kodu są wyświetlane w menu ikony żarówki.

Włączone reguły

Następujące reguły są domyślnie włączone jako błędy lub ostrzeżenia w .NET 11. Dodatkowe reguły są włączone jako sugestie.

Identyfikator diagnostyczny Kategoria Poziom ważności Dodano wersję Opis
CA1416 Współdziałanie Ostrzeżenie .NET 5 Weryfikowanie zgodności platformy
CA1417 Współdziałanie Ostrzeżenie .NET 5 Nie używaj OutAttribute dla parametrów typu string w P/Invoke
CA1418 Współdziałanie Ostrzeżenie .NET 6 Użyj prawidłowego ciągu platformy
CA1420 Współdziałanie Ostrzeżenie .NET 7 Korzystanie z funkcji wymagających marshalingu środowiska uruchomieniowego, gdy marshaling jest wyłączony, spowoduje wystąpienie wyjątków środowiska uruchomieniowego.
CA1422 Współdziałanie Ostrzeżenie .NET 7 Sprawdzanie zgodności platformy
CA1831 Wydajność Ostrzeżenie .NET 5 Użyj AsSpan zamiast indeksatorów opartych na zakresie dla ciągów, gdy jest to właściwe
CA1856 Wydajność Błąd .NET 8 Nieprawidłowe użycie atrybutu ConstantExpected
CA1857 Wydajność Ostrzeżenie .NET 8 Dla parametru oczekiwano stałej
CA2013 Niezawodność Ostrzeżenie .NET 5 Nie używaj ReferenceEquals z typami wartości
CA2014 Niezawodność Ostrzeżenie .NET 5 Nie używaj stackalloc w pętlach
CA2015 Niezawodność Ostrzeżenie .NET 5 Nie należy definiować finalizatorów dla typów pochodzących z MemoryManager<T>
CA2017 Niezawodność Ostrzeżenie .NET 6 Niezgodność liczby parametrów
CA2018 Niezawodność Ostrzeżenie .NET 6 Argument count przekazywany do Buffer.BlockCopy powinien określać liczbę bajtów do skopiowania
CA2021 Niezawodność Ostrzeżenie .NET 8 Nie wywołuj Enumerable.Cast<T> lub Enumerable.OfType<T> z niezgodnymi typami
CA2022 Niezawodność Ostrzeżenie .NET 9 Unikaj niedokładnego odczytu z Stream.Read
CA2023 Niezawodność Ostrzeżenie .NET 10 Nieprawidłowe nawiasy klamrowe w szablonie wiadomości
CA2200 Zastosowanie Ostrzeżenie .NET 5 Ponownie zgłoś wyjątek, aby zachować szczegóły stosu
CA2247 Użycie Ostrzeżenie .NET 5 Argument przekazany do konstruktora TaskCompletionSource powinien być wyliczeniem TaskCreationOptions zamiast TaskContinuationOptions
CA2252 Użycie Błąd .NET 6 Włączanie funkcji w wersji zapoznawczej
CA2255 Sposób użycia Ostrzeżenie .NET 6 Atrybut ModuleInitializer nie powinien być używany w bibliotekach
CA2256 Użycie Ostrzeżenie .NET 6 Wszystkie elementy członkowskie zadeklarowane w interfejsach nadrzędnych muszą mieć implementację w interfejsie oznaczonym atrybutem DynamicInterfaceCastableImplementation
CA2257 Sposób użycia Ostrzeżenie .NET 6 Elementy członkowskie zdefiniowane w interfejsie z elementem DynamicInterfaceCastableImplementationAttribute powinny być static
CA2258 Sposób użycia Ostrzeżenie .NET 6 Udostępnianie interfejsu DynamicInterfaceCastableImplementation w Visual Basic nie jest obsługiwane
CA2259 Użycie Ostrzeżenie .NET 7 ThreadStatic Dotyczy tylko pól statycznych
CA2260 Użycie Ostrzeżenie .NET 7 Użyj poprawnego parametru typu
CA2261 Użycie Ostrzeżenie .NET 8 Nie należy używać ConfigureAwaitOptions.SuppressThrowing z Task<TResult>
CA2264 Sposób użycia Ostrzeżenie .NET 9 Nie przekazuj wartości nienullowalnej do ArgumentNullException.ThrowIfNull
CA2265 Sposób użycia Ostrzeżenie .NET 9 Nie porównuj Span<T> z null lub default
CA2266 Użycie Ostrzeżenie .NET 10 Punkt wejścia programu oparty na plikach powinien zaczynać się od #!
CA2267 Sposób użycia Ostrzeżenie .NET 11 Ujmij w cudzysłów wartości zawierające białe znaki w dyrektywach programu opartych na plikach

Możesz zmienić ważność tych reguł, aby je wyłączyć lub podnieść ich poziom do błędów. Możesz również włączyć więcej reguł.

Włącz dodatkowe reguły

Tryb analizy odnosi się do wstępnie zdefiniowanej konfiguracji analizy kodu, w której włączone są żadne, niektóre lub wszystkie reguły. W domyślnym trybie analizy (Default) tylko niewielka liczba reguł jest włączonych jako ostrzeżenia kompilacji. Tryb analizy projektu można zmienić, ustawiając <AnalysisMode> właściwość w pliku projektu. Dozwolone wartości to:

Wartość Opis
None Wszystkie reguły są wyłączone. Możesz selektywnie zdecydować się na poszczególne reguły, aby je włączyć.
Default Tryb domyślny, w którym niektóre reguły są włączone jako ostrzeżenia kompilacji, niektóre reguły są włączone jako sugestie środowiska IDE programu Visual Studio, a pozostałe są wyłączone.
Minimum Bardziej agresywny tryb niż Default tryb. Niektóre sugestie, które są zdecydowanie zalecane w przypadku wymuszania kompilacji, są włączone jako ostrzeżenia kompilacji. Aby zobaczyć, które reguły są objęte, sprawdź plik %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.globalconfig. (W przypadku platformy .NET 7 i starszych wersji rozszerzenie pliku jest .editorconfig.
Recommended Bardziej agresywny tryb niż Minimum tryb, w którym więcej reguł jest włączanych jako ostrzeżenia kompilacji. Aby sprawdzić, które reguły są uwzględnione, przeanalizuj plik %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.globalconfig. (W przypadku platformy .NET 7 i starszych wersji rozszerzenie pliku jest .editorconfig.
All Wszystkie reguły są włączone jako ostrzeżenia kompilacji*. Możesz selektywnie zrezygnować z poszczególnych reguł, aby je wyłączyć.

* Następujące reguły nie są włączane przez ustawienie na lub przez ustawienie na : CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 oraz reguły analizatora metryk kodu (CA1501, CA1502, CA1505, CA1506 i CA1509). Te starsze reguły mogą zostać wycofane z użycia w przyszłej wersji. Można je jednak nadal włączać indywidualnie przy użyciu wpisu dotnet_diagnostic.CAxxxx.severity = <severity>.

Można również pominąć <AnalysisMode> na rzecz wartości złożonej dla właściwości <AnalysisLevel>. Na przykład następująca wartość umożliwia zalecany zestaw reguł dla najnowszej wersji: <AnalysisLevel>latest-Recommended</AnalysisLevel>. Aby uzyskać więcej informacji, zobacz AnalysisLevel.

Aby znaleźć domyślną ważność dla każdej dostępnej reguły i określić, czy reguła jest włączona w Default trybie analizy, zobacz pełną listę reguł.

Traktuj ostrzeżenia jako błędy

Jeśli używasz flagi -warnaserror podczas tworzenia projektów, wszystkie ostrzeżenia analizy kodu są również traktowane jako błędy. Jeśli nie chcesz, aby ostrzeżenia dotyczące jakości kodu (CAxxxx) były traktowane jako błędy w obecności -warnaserrorprogramu , możesz ustawić CodeAnalysisTreatWarningsAsErrors właściwość MSBuild na false wartość w pliku projektu.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

Nadal będą widoczne ostrzeżenia dotyczące analizy kodu, ale nie będą one przerywać kompilacji.

Najnowsze aktualizacje

Domyślnie reguły analizy kodu i domyślne poziomy ważności są zgodne z wersją platformy docelowej. Najnowsza wydana wersja .NET obsługiwana przez zestaw SDK używa najnowszych reguł. Starsze platformy docelowe zachowują odpowiednie reguły, nawet jeśli kompilujesz przy użyciu nowszego zestawu SDK. Aby użyć najnowszych reguł niezależnie od platformy docelowej, ustaw AnalysisLevel na latest.

  • Ustaw właściwość AnalysisLevel MSBuild na określoną wartość, aby zablokować ostrzeżenia do tego zestawu. Podczas uaktualniania do nowszego zestawu SDK nadal będziesz otrzymywać poprawki błędów dla tych ostrzeżeń, ale żadne nowe ostrzeżenia nie zostaną włączone i żadne istniejące ostrzeżenia nie zostaną wyłączone. Jeśli na przykład uaktualnisz z .NET 10 do .NET 11, ale chcesz zachować reguły .NET 10, dodaj następujący wpis do pliku projektu.

    <PropertyGroup>
      <AnalysisLevel>10.0</AnalysisLevel>
    </PropertyGroup>
    

    Wskazówka

    Aby uzyskać więcej informacji i wyświetlić listę możliwych wartości, zobacz AnalysisLevel.

  • Zainstaluj pakiet NuGet Microsoft.CodeAnalysis.NetAnalyzers, aby oddzielić aktualizacje reguł od aktualizacji zestawu .NET SDK. W przypadku projektów przeznaczonych dla platformy .NET 5 lub nowszej instalowanie pakietu powoduje wyłączenie wbudowanych analizatorów zestawu SDK. Jeśli zestaw SDK zawiera nowszą wersję zestawu analizatora niż pakiet NuGet, zostanie wyświetlone ostrzeżenie kompilacji. Aby wyłączyć ostrzeżenie, ustaw _SkipUpgradeNetAnalyzersNuGetWarning właściwość na true.

    Uwaga

    Jeśli zainstalujesz pakiet NuGet Microsoft.CodeAnalysis.NetAnalyzers, nie należy dodawać właściwości EnableNETAnalyzers do pliku projektu lub pliku Directory.Build.props . Po zainstalowaniu pakietu NuGet i ustawieniu właściwości EnableNETAnalyzers na true generowane jest ostrzeżenie kompilacji.

Analiza stylu kodu

Reguły analizy stylu kodu ("IDExxxx") umożliwiają definiowanie i utrzymywanie spójnego stylu kodu w bazie kodu. Domyślne ustawienia włączania to:

  • Kompilacja wiersza polecenia: analiza stylu kodu jest domyślnie wyłączona dla wszystkich projektów platformy .NET w kompilacjach wiersza polecenia.

    Możesz włączyć analizę stylu kodu w kompilacji zarówno w wierszu polecenia, jak i w programie Visual Studio. Naruszenia stylu kodu są wyświetlane jako ostrzeżenia lub błędy z prefiksem "IDE". Umożliwia to wymuszanie spójnych stylów kodu w czasie kompilacji.

  • Visual Studio: analiza stylu kodu jest domyślnie włączona dla wszystkich projektów platformy .NET w programie Visual Studio jako szybkie akcje analizy stylu i refaktoryzacji kodu.

Aby uzyskać pełną listę reguł analizy stylu kodu, zobacz Reguły stylu kodu.

Włącz podczas kompilacji

Analizę stylu kodu można włączyć podczas kompilowania z poziomu wiersza polecenia i w programie Visual Studio. (Jednak ze względów na wydajność kilka reguł stylu kodu będzie nadal obowiązywać tylko w środowisku Visual Studio IDE.)

Wykonaj następujące kroki, aby włączyć analizę stylu kodu w kompilacji:

  1. Ustaw właściwość MSBuild EnforceCodeStyleInBuild na true.

  2. W pliku .editorconfigskonfiguruj każdą regułę stylu kodu "IDE", którą chcesz uruchomić w kompilacji jako ostrzeżenie lub błąd. Na przykład:

    [*.{cs,vb}]
    # IDE0040: Accessibility modifiers required (escalated to a build warning)
    dotnet_diagnostic.IDE0040.severity = warning
    

    Wskazówka

    Począwszy od platformy .NET 9, można również użyć formatu opcji, aby określić poziom ważności i zapewnić jego przestrzeganie w czasie kompilacji. Na przykład:

    [*.{cs,vb}]
    # IDE0040: Accessibility modifiers required (escalated to a build warning)
    dotnet_style_require_accessibility_modifiers = always:warning
    

    Alternatywnie można skonfigurować całą kategorię jako ostrzeżenie lub błąd, a następnie selektywnie wyłączyć reguły w tej kategorii, których nie chcesz uruchamiać w kompilacji. Na przykład:

    [*.{cs,vb}]
    
    # Default severity for analyzer diagnostics with category 'Style' (escalated to build warnings)
    dotnet_analyzer_diagnostic.category-Style.severity = warning
    
    # IDE0040: Accessibility modifiers required (disabled on build)
    dotnet_diagnostic.IDE0040.severity = silent
    

Pomiń ostrzeżenie

Jednym ze sposobów wyciszenia naruszenia reguły jest ustawienie opcji poziomu ważności dla tego identyfikatora reguły na wartość none w pliku EditorConfig. Na przykład:

dotnet_diagnostic.CA1822.severity = none

Aby uzyskać więcej informacji i poznać inne sposoby wyciszania ostrzeżeń, zobacz Jak wyciszać ostrzeżenia analizy kodu.

Włączanie analizy kodu w starszych projektach

Jeśli projekt jest przeznaczony dla platformy .NET 5 lub nowszej, analiza kodu jest domyślnie włączona. Jeśli projekt jest przeznaczony dla platformy .NET Standard lub .NET Framework, należy ręcznie włączyć analizę kodu, ustawiając właściwość EnableNETAnalyzers na true.

Jeśli projekt używa starszego formatu pliku projektu, oznacza to, że nie odwołuje się do zestawu SDK projektu, należy wykonać kilka dodatkowych czynności w celu włączenia analizy kodu:

  1. Dodaj odwołanie do 📦 pakietu NuGet Microsoft.CodeAnalysis.NetAnalyzers.
  2. Zamiast ustawiać wartość AnalysisLevel, która nie jest zrozumiała dla projektów innych niż zestaw SDK, dodaj następujące właściwości do pliku projektu:
  <EffectiveAnalysisLevel>9</EffectiveAnalysisLevel>
  <AnalysisMode>Recommended</AnalysisMode>

Analizatory innych firm

Oprócz oficjalnych analizatorów .NET można również zainstalować analizatory innych firm, takie jak StyleCop, Roslynator, Meziantou.Analyzer, XUnit Analyzer i Sonar Analyzer.

Zobacz też