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

  • Artykuł

Analizatory platformy kompilatora .NET (Roslyn) sprawdzają kod C# lub Visual Basic pod kątem problemów z jakością kodu i stylem. Począwszy od platformy .NET 5, 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. Jeśli projekt jest przeznaczony dla innej implementacji platformy .NET, na przykład .NET Core, .NET Standard lub .NET Framework, należy ręcznie włączyć analizę kodu, ustawiając właściwość EnableNETAnalyzers na true.

Jeśli nie chcesz przechodzić do zestawu .NET 5+ SDK, masz projekt .NET Framework w stylu innym niż SDK lub preferujesz model oparty na pakietach NuGet, analizatory są również dostępne w pakiecie NuGet Microsoft.CodeAnalysis.NetAnalyzers. Możesz preferować model oparty na pakietach dla aktualizacji wersji na żądanie.

Uwaga

Analizatory platformy .NET są niezależne od platformy docelowej. Oznacza to, że projekt nie musi być przeznaczony dla określonej implementacji platformy .NET. Analizatory działają w przypadku projektów przeznaczonych dla platformy .NET 5+ oraz starszych wersji platformy .NET, takich jak .NET Core 3.1 i .NET Framework 4.7.2. Jednak aby włączyć analizę kodu przy użyciu właściwości EnableNETAnalyzers , projekt musi odwoływać się do zestawu SDK projektu.

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 dla projektów docelowych wcześniejszych wersji platformy .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 wartość EnableNETAnalyzersfalse.

Napiwek

Jeśli używasz programu Visual Studio, wiele reguł analizatora ma skojarzone poprawki kodu, które można zastosować, aby rozwiązać ten 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 na platformie .NET 8. Dodatkowe reguły są włączone jako sugestie.

Identyfikator diagnostyczny Kategoria Ważność 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 parametrów ciągu dla parametró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 jest wyłączone, spowoduje wyjątki czasu wykonywania
CA1422 Współdziałanie Ostrzeżenie .NET 7 Weryfikowanie zgodności platformy
CA1831 Wydajność Ostrzeżenie .NET 5 Użyj AsSpan zamiast indeksatorów opartych na zakresie dla ciągu, jeśli jest to konieczne
CA1856 Wydajność Błąd .NET 8 Nieprawidłowe użycie atrybutu ConstantExpected
CA1857 Wydajność Ostrzeżenie .NET 8 Stała jest oczekiwana dla parametru
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 count Argument , który Buffer.BlockCopy ma określać liczbę bajtów do skopiowania
CA2021 Niezawodność Ostrzeżenie .NET 8 Nie wywoływanie Enumerable.Cast<T> lub Enumerable.OfType<T> z niezgodnymi typami
CA2200 Użycie Ostrzeżenie .NET 5 Ponowie zgłoś wyjątek, aby zachować szczegóły stosu
CA2247 Użycie Ostrzeżenie .NET 5 Argument przekazany do TaskCompletionSource konstruktora powinien być TaskCreationOptions wyliczenie zamiast TaskContinuationOptions
CA2252 Użycie Błąd .NET 6 Włączanie funkcji w wersji zapoznawczej
CA2255 Użycie 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 przypisanym DynamicInterfaceCastableImplementation
CA2257 Użycie Ostrzeżenie .NET 6 Składowe zdefiniowane w interfejsie z elementem DynamicInterfaceCastableImplementationAttribute powinny być static
CA2258 Użycie Ostrzeżenie .NET 6 Udostępnianie interfejsu DynamicInterfaceCastableImplementation w Visual Basic jest nieobsł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ć z ConfigureAwaitOptions.SuppressThrowingTask<TResult>

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ł.

  • Aby uzyskać listę reguł dołączonych do każdej wersji zestawu SDK platformy .NET, zobacz Wydania analizatora.
  • Aby uzyskać listę wszystkich reguł jakości kodu, zobacz Reguły jakości kodu.

Włączanie dodatkowych reguł

Tryb analizy odnosi się do wstępnie zdefiniowanej konfiguracji analizy kodu, w której nie są włączone żadne, niektóre lub wszystkie reguły. W domyślnym trybie analizy (Default) tylko niewielka liczba reguł jest włączona 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 wyrazić zgodę 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 sprawdzić, które reguły obejmują, sprawdź plik %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.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 obejmują, sprawdź plik %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.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łączone przez ustawienie AnalysisMode na All lub przez ustawienie AnalysisLevellatest-allna : CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 i reguły analizatora metryk kodu (CA1501, CA1502, CA1505, CA1506 i CA1509). Te starsze reguły mogą być przestarzałe w przyszłej wersji. Można je jednak nadal włączać indywidualnie przy użyciu dotnet_diagnostic.CAxxxx.severity = <severity> wpisu.

Począwszy od platformy .NET 6, można pominąć <AnalysisMode> wartość złożoną dla <AnalysisLevel> właściwości. 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 podczas uaktualniania do nowszych wersji zestawu SDK platformy .NET uzyskasz najnowsze reguły analizy kodu i domyślne ważności reguł. Jeśli na przykład nie chcesz tego zachowania, jeśli chcesz upewnić się, że żadne nowe reguły nie są włączone lub wyłączone, możesz je zastąpić w jeden z następujących sposobów:

  • AnalysisLevel Ustaw właściwość 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. Aby na przykład zablokować zestaw reguł dla tych, które są dostarczane z wersją 5.0 zestawu .NET SDK, dodaj następujący wpis do pliku projektu.

    <PropertyGroup>
  <AnalysisLevel>5.0</AnalysisLevel>
</PropertyGroup>

    Napiwek

    Wartość domyślna właściwości AnalysisLevel to latest, co oznacza, że zawsze uzyskujesz najnowsze reguły analizy kodu podczas przechodzenia do nowszych wersji zestawu .NET SDK.

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

  • Zainstaluj pakiet NuGet Microsoft.CodeAnalysis.NetAnalyzers, aby rozdzielić aktualizacje reguł z 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 EnableNETAnalyzers ustawieniu właściwości na truewartość zostanie wygenerowane 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.

    Począwszy od platformy .NET 5, możesz włączyć analizę w 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 refaktoryzacji kodu.

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

Włączanie kompilacji

Korzystając z zestawu .NET 5 SDK i nowszych wersji, można włączyć analizę stylu kodu podczas kompilowania z poziomu wiersza polecenia i w programie Visual Studio. (Jednak ze względu na wydajność kilka reguł stylu kodu będzie nadal stosować tylko w środowisku IDE programu Visual Studio).

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

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

  2. W pliku .editorconfig skonfiguruj 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

    Napiwek

    Począwszy od platformy .NET 9, można również użyć formatu opcji, aby określić ważność i zapewnić jej 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

Pomijanie ostrzeżenia

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

dotnet_diagnostic.CA1822.severity = none

Aby uzyskać więcej informacji i inne sposoby pomijania ostrzeżeń, zobacz Jak pominąć ostrzeżenia analizy kodu.

Uruchamianie analizy kodu jako akcji usługi GitHub

Akcja dotnet/code-analysis w usłudze GitHub umożliwia uruchamianie analizatorów kodu platformy .NET w ramach ciągłej integracji w trybie offline. Aby uzyskać więcej informacji, zobacz Akcja github analizy kodu platformy .NET.

Analizatory innych firm

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

Zobacz też