Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
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ł.
- 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łą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ść
AnalysisLevelMSBuild 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
_SkipUpgradeNetAnalyzersNuGetWarningwłaściwość natrue.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
EnableNETAnalyzersnatruegenerowane 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:
Ustaw właściwość MSBuild EnforceCodeStyleInBuild na
true.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 = warningWskazó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:warningAlternatywnie 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:
- Dodaj odwołanie do 📦 pakietu NuGet Microsoft.CodeAnalysis.NetAnalyzers.
- 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.