Přehled analýzy zdrojového kódu .NET

  • Článek

Analyzátory platformy kompilátoru .NET (Roslyn) kontrolují problémy s kvalitou a stylem kódu jazyka C# nebo Visual Basic. Počínaje rozhraním .NET 5 jsou tyto analyzátory součástí sady .NET SDK a nemusíte je instalovat samostatně. Pokud váš projekt cílí na .NET 5 nebo novější, je ve výchozím nastavení povolená analýza kódu. Pokud váš projekt cílí na jinou implementaci .NET, například .NET Core, .NET Standard nebo .NET Framework, musíte ručně povolit analýzu kódu nastavením vlastnosti EnableNETAnalyzers na truehodnotu .

Pokud nechcete přejít na sadu .NET 5+ SDK, máte projekt .NET Framework ve stylu sady .NET Framework nebo preferujte model založený na balíčku NuGet NuGet, jsou analyzátory dostupné také v balíčku NuGet Microsoft.CodeAnalysis.NetAnalyzers. Pro aktualizace verzí na vyžádání můžete preferovat model založený na balíčcích.

Poznámka:

Analyzátory .NET jsou nezávislé na cílovém rozhraní. To znamená, že váš projekt nemusí cílit na konkrétní implementaci .NET. Analyzátory fungují pro projekty, které cílí na .NET 5 nebo novější a starší verze .NET, jako jsou .NET Core 3.1 a .NET Framework 4.7.2. Chcete-li však povolit analýzu kódu pomocí vlastnosti EnableNETAnalyzers , musí váš projekt odkazovat na sadu SDK projektu.

Pokud analyzátor najde porušení pravidel, zobrazí se v závislosti na konfiguraci jednotlivých pravidel jako návrh, upozornění nebo chyba. Porušení analýzy kódu se zobrazí s předponou CA nebo IDE, aby se odlišila od chyb kompilátoru.

Analýza kvality kódu

Pravidla analýzy kvality kódu (CAxxxx) kontrolují kód jazyka C# nebo Visual Basic a kontrolují zabezpečení, výkon, návrh a další problémy. Analýza je ve výchozím nastavení povolená pro projekty, které cílí na .NET 5 nebo novější. Analýzu kódu můžete povolit u projektů, které cílí na starší verze rozhraní .NET, nastavením vlastnosti EnableNETAnalyzers na truehodnotu . Analýzu kódu projektu můžete také zakázat nastavením EnableNETAnalyzers na false.

Tip

Pokud používáte Visual Studio, mnoho pravidel analyzátoru má přidružené opravy kódu, které můžete použít k vyřešení problému. Opravy kódu se zobrazují v nabídce ikon žárovky.

Povolená pravidla

Následující pravidla jsou ve výchozím nastavení povolená jako chyby nebo upozornění v .NET 8. Další pravidla jsou povolená jako návrhy.

ID diagnostiky Kategorie Závažnost Přidaná verze Popis
CA1416 Vzájemná funkční spolupráce Upozorňující .NET 5 Ověřit kompatibilitu platformy
CA1417 Vzájemná funkční spolupráce Upozorňující .NET 5 Nepoužívejte OutAttribute u parametrů řetězce pro volání nespravovaného kódu.
CA1418 Vzájemná funkční spolupráce Upozorňující .NET 6 Použití platného řetězce platformy
CA1420 Vzájemná funkční spolupráce Upozorňující .NET 7 Použití funkcí, které vyžadují zařazování za běhu, když je zakázané, způsobí výjimky za běhu.
CA1422 Vzájemná funkční spolupráce Upozorňující .NET 7 Ověřit kompatibilitu platformy
CA1831 Výkon Upozorňující .NET 5 Místo AsSpan indexerů založených na rozsahu pro řetězec použijte, pokud je to vhodné.
CA1856 Výkon Chyba .NET 8 Nesprávné použití atributu ConstantExpected
CA1857 Výkon Upozorňující .NET 8 Pro parametr se očekává konstanta.
CA2013 Spolehlivost Upozorňující .NET 5 Nepoužívejte ReferenceEquals s typy hodnot
CA2014 Spolehlivost Upozorňující .NET 5 Nepoužívat stackalloc ve smyčce
CA2015 Spolehlivost Upozorňující .NET 5 Nedefinujte finalizační metody pro typy odvozené z MemoryManager<T>
CA2017 Spolehlivost Upozorňující .NET 6 Neshoda počtu parametrů
CA2018 Spolehlivost Upozorňující .NET 6 Argument count , který má Buffer.BlockCopy určovat počet bajtů, které se mají zkopírovat
CA2021 Spolehlivost Upozorňující .NET 8 Nevyvolávat Enumerable.Cast<T> nebo Enumerable.OfType<T> s nekompatibilními typy
CA2200 Využití Upozorňující .NET 5 Znovu vyvolejte pro zachování podrobností zásobníku
CA2247 Využití Upozorňující .NET 5 Argument předaný konstruktoru TaskCompletionSource by měl být TaskCreationOptions výčt místo TaskContinuationOptions
CA2252 Využití Chyba .NET 6 Přihlášení k funkcím ve verzi Preview
CA2255 Využití Upozorňující .NET 6 Atribut ModuleInitializer by se neměl používat v knihovnách.
CA2256 Využití Upozorňující .NET 6 Všechny členy deklarované v nadřazených rozhraních musí mít implementaci v DynamicInterfaceCastableImplementationrozhraní -attributed.
CA2257 Využití Upozorňující .NET 6 Členy definované v rozhraní s DynamicInterfaceCastableImplementationAttributestatic
CA2258 Využití Upozorňující .NET 6 DynamicInterfaceCastableImplementation Poskytnutí rozhraní v jazyce Visual Basic není podporováno
CA2259 Využití Upozorňující .NET 7 ThreadStatic má vliv pouze na statická pole.
CA2260 Využití Upozorňující .NET 7 Použít správný parametr typu
CA2261 Využití Upozorňující .NET 8 Nepoužívejte s ConfigureAwaitOptions.SuppressThrowingTask<TResult>

Můžete změnit závažnost těchto pravidel a zakázat je nebo zvýšit jejich úroveň na chyby. Můžete také povolit další pravidla.

  • Seznam pravidel, která jsou součástí každé verze sady .NET SDK, najdete v tématu Verze Analyzátoru.
  • Seznam všech pravidel kvality kódu najdete v tématu Pravidla kvality kódu.

Povolení dalších pravidel

Režim analýzy odkazuje na předdefinovanou konfiguraci analýzy kódu, kde nejsou povolená žádná, některá nebo všechna pravidla. Ve výchozím režimu analýzy (Default) je jako upozornění sestavení povolen pouze malý počet pravidel. Režim analýzy projektu můžete změnit nastavením <AnalysisMode> vlastnosti v souboru projektu. Povolené hodnoty jsou:

Hodnota Popis
None Všechna pravidla jsou zakázaná. Můžete selektivně vyjádřit výslovný souhlas s jednotlivými pravidly, která je povolí.
Default Výchozí režim, kdy jsou určitá pravidla povolená jako upozornění sestavení, jsou určitá pravidla povolená jako návrhy integrovaného vývojového prostředí sady Visual Studio a zbytek je zakázaný.
Minimum Agresivnější režim než Default režim. Některé návrhy, které důrazně doporučujeme pro vynucování sestavení, jsou povolené jako upozornění sestavení. Pokud chcete zjistit, která pravidla to zahrnuje, zkontrolujte soubor %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig .
Recommended Agresivnější režim než Minimum režim, kdy je jako upozornění sestavení povoleno více pravidel. Pokud chcete zjistit, která pravidla zahrnují, zkontrolujte soubor %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig .
All Všechna pravidla jsou povolená jako upozornění* sestavení. Můžete selektivně vyjádřit výslovný nesouhlas s individuálními pravidly a zakázat je.

* Následující pravidla nejsou povolena nastavením AllAnalysisMode na : AnalysisLevellatest-allCA1017, CA1045, CA1005, CA1014, CA1060, CA1021 a pravidly analyzátoru metrik kódu (CA1501, CA1502, CA1505, CA1506 a CA1509). Tato starší pravidla můžou být v budoucí verzi zastaralá. Přesto je ale můžete povolit jednotlivě pomocí dotnet_diagnostic.CAxxxx.severity = <severity> položky.

Počínaje rozhraním .NET 6 můžete vynechat <AnalysisMode> složenou hodnotu vlastnosti <AnalysisLevel> . Například následující hodnota umožňuje doporučenou sadu pravidel pro nejnovější verzi: <AnalysisLevel>latest-Recommended</AnalysisLevel>. Další informace najdete na webu AnalysisLevel.

Pokud chcete zjistit výchozí závažnost pro každé dostupné pravidlo a jestli je pravidlo povolené v Default režimu analýzy, podívejte se na úplný seznam pravidel.

Zacházení s upozorněními jako s chybami

Pokud při sestavování projektů použijete -warnaserror příznak, budou se všechna upozornění analýzy kódu považovat také za chyby. Pokud nechcete, aby se upozornění na kvalitu kódu (CAxxxx) zacházelo jako s chybami v přítomnosti -warnaserror, můžete vlastnost MSBuild nastavit CodeAnalysisTreatWarningsAsErrors v false souboru projektu.

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

Stále se zobrazí upozornění analýzy kódu, ale nebudou přerušovat vaše sestavení.

Nejnovější aktualizace

Ve výchozím nastavení získáte nejnovější pravidla analýzy kódu a výchozí závažnosti pravidel při upgradu na novější verze sady .NET SDK. Pokud například nechcete toto chování používat, pokud chcete zajistit, aby nebyla povolena nebo zakázána žádná nová pravidla, můžete ho přepsat jedním z následujících způsobů:

  • AnalysisLevel Nastavte vlastnost MSBuild na určitou hodnotu, chcete-li uzamknout upozornění na danou sadu. Když upgradujete na novější sadu SDK, stále se zobrazí opravy chyb pro tato upozornění, ale nebudou povolena žádná nová upozornění a nebudou zakázána žádná existující upozornění. Pokud chcete například uzamknout sadu pravidel na ty, které jsou dodávány s verzí 5.0 sady .NET SDK, přidejte do souboru projektu následující položku.

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

    Tip

    Výchozí hodnota AnalysisLevel vlastnosti je latest, což znamená, že při přechodu na novější verze sady .NET SDK vždy získáte nejnovější pravidla analýzy kódu.

    Další informace a zobrazení seznamu možných hodnot naleznete v tématu AnalysisLevel.

  • Nainstalujte balíček NuGet Microsoft.CodeAnalysis.NetAnalyzers a oddělte aktualizace pravidel od aktualizací sady .NET SDK. U projektů, které cílí na .NET 5 nebo novější, vypne instalace balíčku integrované analyzátory sady SDK. Pokud sada SDK obsahuje novější verzi sestavení analyzátoru, než je verze balíčku NuGet, zobrazí se upozornění na sestavení sestavení. Chcete-li upozornění zakázat, nastavte _SkipUpgradeNetAnalyzersNuGetWarning vlastnost na truehodnotu .

    Poznámka:

    Pokud nainstalujete balíček NuGet Microsoft.CodeAnalysis.NetAnalyzers, neměli byste přidat vlastnost EnableNETAnalyzers do souboru projektu nebo do souboru Directory.Build.props . Při instalaci balíčku NuGet a EnableNETAnalyzers vlastnost je nastavena na true, vygeneruje se upozornění sestavení.

Analýza stylu kódu

Pravidla analýzy stylu kódu (IDExxxx) umožňují definovat a udržovat konzistentní styl kódu v základu kódu. Výchozí nastavení povolení jsou:

  • Sestavení příkazového řádku: Analýza stylu kódu je ve výchozím nastavení zakázaná pro všechny projekty .NET v sestaveních příkazového řádku.

    Počínaje rozhraním .NET 5 můžete povolit analýzu stylu kódu při sestavení, a to jak na příkazovém řádku, tak v sadě Visual Studio. Porušení stylu kódu se zobrazují jako upozornění nebo chyby s předponou IDE. To vám umožní vynucovat konzistentní styly kódu v době sestavení.

  • Visual Studio: Analýza stylu kódu je ve výchozím nastavení povolená pro všechny projekty .NET v sadě Visual Studio jako refaktoring rychlých akcí kódu.

Úplný seznam pravidel analýzy stylu kódu najdete v tématu Pravidla stylu kódu.

Povolení při sestavení

Se sadou .NET 5 SDK a novějšími verzemi můžete povolit analýzu stylu kódu při sestavování z příkazového řádku a v sadě Visual Studio. (Z důvodů výkonu však bude několik pravidel stylu kódu platit pouze v integrovaném vývojovém prostředí sady Visual Studio.)

Pokud chcete povolit analýzu stylu kódu při sestavení, postupujte takto:

  1. Nastavte vlastnost MSBuild EnforceCodeStyleInBuild na true.

  2. V souboru .editorconfig nakonfigurujte každé pravidlo stylu kódu IDE, které chcete spustit při sestavení jako upozornění nebo chybu. Příklad:

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

    Tip

    Od verze .NET 9 můžete také použít formát možnosti k určení závažnosti a jeho dodržování v době sestavení. Příklad:

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

    Případně můžete nakonfigurovat celou kategorii tak, aby byla ve výchozím nastavení upozorněním nebo chybou, a pak v této kategorii selektivně vypnout pravidla, která nechcete spouštět při sestavení. Příklad:

    [*.{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

Potlačení upozornění

Jedním ze způsobů, jak potlačit porušení pravidla, je nastavit možnost závažnosti pro toto ID pravidla v none souboru EditorConfig. Příklad:

dotnet_diagnostic.CA1822.severity = none

Další informace a další způsoby potlačení upozornění naleznete v tématu Jak potlačit upozornění analýzy kódu.

Spuštění analýzy kódu jako akce GitHubu

Akce GitHubu pro analýzu kódu umožňuje spouštět analyzátory kódu .NET jako součást kontinuální integrace (CI) v offline režimu. Další informace najdete v tématu Analýza kódu .NET GitHub Action.

Analyzátory jiných výrobců

Kromě oficiálních analyzátorů .NET můžete také nainstalovat analyzátory třetích stran, jako jsou StyleCop, Roslynator, Analyzátory XUnit a Sonar Analyzer.

Viz také