A .NET-forráskódelemzés áttekintése

  • Cikk

A .NET fordítóplatform (Roslyn) elemzői ellenőrzik a C# vagy a Visual Basic kód minőségét és stílusát. A .NET 5-től kezdve ezek az elemzők a .NET SDK részét képezik, és nem kell külön telepíteni őket. Ha a projekt a .NET 5-ös vagy újabb verzióját célozza meg, a kódelemzés alapértelmezés szerint engedélyezve van. Ha a projekt egy másik .NET-implementációt céloz meg, például .NET Core, .NET Standard vagy .NET-keretrendszer, manuálisan engedélyeznie kell a kódelemzést az EnableNETAnalyzers tulajdonság truebeállításával.

Ha nem szeretne a .NET 5+ SDK-ra váltani, nem SDK-stílusú .NET-keretrendszer projektje van, vagy inkább Egy NuGet-csomagalapú modellt szeretne, az elemzők a Microsoft.CodeAnalysis.NetAnalyzers NuGet csomagban is elérhetők. Igény szerinti verziófrissítésekhez érdemes csomagalapú modellt használni.

Feljegyzés

A .NET-elemzők a target-framework agnosztikusak. Ez azt jelenti, hogy a projektnek nem kell egy adott .NET-implementációt céloznia. Az elemzők a .NET 5+ és a korábbi .NET-verziók, például a .NET Core 3.1 és .NET-keretrendszer 4.7.2-et megcélzó projekteken dolgoznak. Ha azonban engedélyezni szeretné a kódelemzést az EnableNETAnalyzers tulajdonság használatával, a projektnek egy projekt SDK-ra kell hivatkoznia.

Ha egy elemző szabálysértéseket talál, a rendszer javaslatként, figyelmeztetésként vagy hibaként jelenti őket az egyes szabályok konfigurálásának módjától függően. A kódelemzési szabálysértések a "CA" vagy az "IDE" előtaggal jelennek meg, hogy megkülönböztessék őket a fordítóhibáktól.

Kódminőség-elemzés

A kódminőség-elemzés ("CAxxxx") szabályai biztonsági, teljesítménybeli, tervezési és egyéb problémák esetén ellenőrzik a C# vagy a Visual Basic kódot. Az elemzés alapértelmezés szerint engedélyezve van a .NET 5 vagy újabb verziót célzó projektek esetében. Az EnableNETAnalyzers tulajdonság beállításával engedélyezheti a kódelemzést a korábbi .NET-verziókat megcélzó projektekentrue. A projekt kódelemzését a következő beállítással EnableNETAnalyzersfalseis letilthatja: .

Tipp.

Ha Visual Studio-t használ, számos elemző szabály rendelkezik a probléma megoldásához alkalmazható kódjavításokkal . A kódjavítások a villanykörte ikon menüjében jelennek meg.

Engedélyezett szabályok

A következő szabályok alapértelmezés szerint engedélyezve vannak hibaként vagy figyelmeztetésként a .NET 8-ban. További szabályok is engedélyezve vannak javaslatként.

Diagnosztikai azonosító Kategória Súlyosság Hozzáadott verzió Leírás
CA1416 Együttműködési lehetőség Figyelmeztetés .NET 5 Platformkompatibilitás ellenőrzése
CA1417 Együttműködési lehetőség Figyelmeztetés .NET 5 Ne használjon OutAttribute sztringparamétereket a P/Invokes esetében
CA1418 Együttműködési lehetőség Figyelmeztetés .NET 6 Érvényes platformsztring használata
CA1420 Együttműködési lehetőség Figyelmeztetés .NET 7 Az olyan funkciók használata, amelyek futásidejű rendezést igényelnek, ha le van tiltva, futásidejű kivételekhez vezetnek
CA1422 Együttműködési lehetőség Figyelmeztetés .NET 7 Platformkompatibilitás ellenőrzése
CA1831 Teljesítmény Figyelmeztetés .NET 5 Ha szükséges, tartományalapú indexelők helyett használjon AsSpan sztringet
CA1856 Teljesítmény Hiba .NET 8 Az attribútum helytelen használata ConstantExpected
CA1857 Teljesítmény Figyelmeztetés .NET 8 Konstans várható a paraméterhez
CA2013 Megbízhatóság Figyelmeztetés .NET 5 Ne használjon ReferenceEquals értéktípusokat
CA2014 Megbízhatóság Figyelmeztetés .NET 5 Nem használható stackalloc hurkokban
CA2015 Megbízhatóság Figyelmeztetés .NET 5 Ne definiáljon véglegesítőket a következőből származtatott típusok esetében: MemoryManager<T>
CA2017 Megbízhatóság Figyelmeztetés .NET 6 A paraméterek száma nem egyezik
CA2018 Megbízhatóság Figyelmeztetés .NET 6 A count másolandó Buffer.BlockCopy bájtok számát meghatározó argumentum
CA2021 Megbízhatóság Figyelmeztetés .NET 8 Nem hívható Enumerable.Cast<T> vagy Enumerable.OfType<T> nem kompatibilis típusok
CA2200 Használat Figyelmeztetés .NET 5 Újrafedés a verem részleteinek megőrzése érdekében
CA2247 Használat Figyelmeztetés .NET 5 A konstruktornak TaskCompletionSource átadott argumentumnak számnak kell lennie ahelyett, hogy TaskCreationOptionsTaskContinuationOptions
CA2252 Használat Hiba .NET 6 Az előzetes verziójú funkciók használata
CA2255 Használat Figyelmeztetés .NET 6 Az ModuleInitializer attribútum nem használható kódtárakban
CA2256 Használat Figyelmeztetés .NET 6 A szülőfelületeken deklarált összes tagnak implementációval kell rendelkeznie egy DynamicInterfaceCastableImplementation-attribútummal rendelkező felületen
CA2257 Használat Figyelmeztetés .NET 6 Az interfészen DynamicInterfaceCastableImplementationAttribute definiált tagoknak static
CA2258 Használat Figyelmeztetés .NET 6 DynamicInterfaceCastableImplementation A Visual Basic felületének megadása nem támogatott
CA2259 Használat Figyelmeztetés .NET 7 ThreadStatic csak a statikus mezőket érinti
CA2260 Használat Figyelmeztetés .NET 7 Helyes típusparaméter használata
CA2261 Használat Figyelmeztetés .NET 8 Ne használja a következővel ConfigureAwaitOptions.SuppressThrowing : Task<TResult>

A szabályok súlyosságát módosíthatja, hogy letiltsa őket, vagy hibákra emelje őket. További szabályokat is engedélyezhet.

  • Az egyes .NET SDK-verziókhoz tartozó szabályok listáját az Analyzer kiadásaiban találja.
  • Az összes kódminőségi szabály listáját a Kódminőségi szabályok című témakörben találja.

További szabályok engedélyezése

Az elemzési mód egy előre definiált kódelemzési konfigurációra utal, amelyben nincs, néhány vagy minden szabály engedélyezve van. Az alapértelmezett elemzési módban (Default) a rendszer csak kis számú szabályt engedélyez összeállítási figyelmeztetésként. A projekt elemzési módjának módosításához állítsa be a <AnalysisMode> tulajdonságot a projektfájlban. Az engedélyezett értékek a következők:

Érték Leírás
None Minden szabály le van tiltva. Az egyes szabályok engedélyezéséhez szelektíven is dönthet.
Default Alapértelmezett mód, ahol bizonyos szabályok buildértesítésként vannak engedélyezve, bizonyos szabályok Visual Studio IDE-javaslatokként vannak engedélyezve, a többi pedig le van tiltva.
Minimum Agresszívebb mód, mint Default mód. A buildkényszerítéshez erősen ajánlott javaslatok build figyelmeztetésként engedélyezve vannak. Ha meg szeretné tekinteni, hogy ez mely szabályokat tartalmazza, vizsgálja meg a %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig fájlt.
Recommended Agresszívebb mód, mint Minimum a mód, ahol több szabály engedélyezve van a buildekre vonatkozó figyelmeztetésekként. Ha meg szeretné tekinteni, hogy ez mely szabályokat tartalmazza, tekintse meg a %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig fájlt.
All A rendszer minden szabályt engedélyez összeállítási figyelmeztetésként*. A letiltásukhoz szelektíven letilthatja az egyes szabályokat.

* A következő szabályok nem engedélyezettek a következő beállításokkal AllAnalysisModeAnalysisLevellatest-all: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 és a kódmetrikaelemző szabályok (CA1501, CA1502, CA1505, CA1506 és CA1509). Ezek az örökölt szabályok elavultak lehetnek egy későbbi verzióban. A bejegyzésekkel dotnet_diagnostic.CAxxxx.severity = <severity> azonban egyenként is engedélyezheti őket.

A .NET 6-tól kezdve kihagyhatja <AnalysisMode> a tulajdonság összetett értékét <AnalysisLevel> . A következő érték például a legújabb kiadáshoz javasolt szabálykészletet teszi lehetővé: <AnalysisLevel>latest-Recommended</AnalysisLevel>. További információ: AnalysisLevel.

Ha meg szeretné állapítani az egyes elérhető szabályok alapértelmezett súlyosságát, és hogy a szabály engedélyezve van-e elemzési Default módban, tekintse meg a szabályok teljes listáját.

Figyelmeztetések kezelése hibákként

Ha a projektek létrehozásakor használja a -warnaserror jelzőt, a kódelemzési figyelmeztetések is hibaüzenetként lesznek kezelve. Ha nem szeretné, hogy a kódminőségre vonatkozó figyelmeztetések (CAxxxx) hibákként -warnaserrorlegyenek kezelve, beállíthatja az CodeAnalysisTreatWarningsAsErrors MSBuild tulajdonságot false a projektfájlban.

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

A kódelemzési figyelmeztetések továbbra is megjelennek, de nem fogják megszakítani a buildet.

Legújabb frissítések

Alapértelmezés szerint a .NET SDK újabb verzióira való frissítéskor a legújabb kódelemzési szabályokat és az alapértelmezett szabály súlyosságait fogja megkapni. Ha nem szeretné ezt a viselkedést, például ha meg szeretné győződni arról, hogy nincsenek új szabályok engedélyezve vagy letiltva, felülbírálhatja az alábbi módokon:

  • Állítsa az AnalysisLevel MSBuild tulajdonságot egy adott értékre, hogy zárolja a figyelmeztetéseket erre a halmazra. Az újabb SDK-ra való frissítéskor továbbra is hibajavítások jelennek meg ezekhez a figyelmeztetésekhez, de új figyelmeztetések nem lesznek engedélyezve, és a meglévő figyelmeztetések nem lesznek letiltva. Ha például a szabályok készletét a .NET SDK 5.0-s verziójával szállítja, adja hozzá a következő bejegyzést a projektfájlhoz.

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

    Tipp.

    A tulajdonság latestalapértelmezett értéke, AnalysisLevel ami azt jelenti, hogy a .NET SDK újabb verzióira való áttéréskor mindig a legújabb kódelemzési szabályokat kapja meg.

    További információkért és a lehetséges értékek listájának megtekintéséhez tekintse meg az AnalysisLevelet.

  • Telepítse a Microsoft.CodeAnalysis.NetAnalyzers NuGet-csomagot a szabályfrissítések .NET SDK-frissítésektől való leválasztásához. A .NET 5+-et megcélzó projektek esetében a csomag telepítése kikapcsolja a beépített SDK-elemzőket. Buildre vonatkozó figyelmeztetést kap, ha az SDK a NuGet-csomagénál újabb elemzőszerelvény-verziót tartalmaz. A figyelmeztetés letiltásához állítsa a tulajdonságot a _SkipUpgradeNetAnalyzersNuGetWarning következőre true: .

    Feljegyzés

    Ha telepíti a Microsoft.CodeAnalysis.NetAnalyzers NuGet-csomagot, nem szabad hozzáadnia az EnableNETAnalyzers tulajdonságot sem a projektfájlhoz, sem a Directory.Build.props fájlhoz . Ha a NuGet-csomag telepítve van, és a EnableNETAnalyzers tulajdonság értéke be van állítva true, létrejön egy összeállítási figyelmeztetés.

Kódstílus-elemzés

A kódstílus-elemzés ("IDExxxx") szabályai lehetővé teszik, hogy konzisztens kódstílust definiáljon és tartson fenn a kódbázisban. Az alapértelmezett engedélyezési beállítások a következők:

  • Parancssori build: A kódstílus-elemzés alapértelmezés szerint le van tiltva a parancssori buildeken lévő összes .NET-projekt esetében.

    A .NET 5-től kezdve engedélyezheti a kódstílusok elemzését a buildelés során, mind a parancssorban, mind a Visual Studióban. A kódstílusok megsértései figyelmeztetésként vagy "IDE" előtaggal kapcsolatos hibákként jelennek meg. Ez lehetővé teszi a konzisztens kódstílusok kikényszerítését a létrehozáskor.

  • Visual Studio: A kódstílus-elemzés alapértelmezés szerint engedélyezve van a Visual Studióban lévő összes .NET-projekthez, mint a gyorsműveletek kódjának újrabontása.

A kódstílus-elemzési szabályok teljes listáját a Kódstílus-szabályok című témakörben találja.

Engedélyezés builden

A .NET 5 SDK-val és újabb verzióival engedélyezheti a kódstílus-elemzést a parancssorból és a Visual Studióban való készítéskor. (Teljesítménybeli okokból azonban néhány kódstílus-szabály továbbra is csak a Visual Studio IDE-ben lesz érvényben.)

Kövesse az alábbi lépéseket a kódstílusok builden történő elemzésének engedélyezéséhez:

  1. Állítsa az MSBuild EnforceCodeStyleInBuild tulajdonságot a következőretrue: .

  2. A .editorconfig fájlban konfiguráljon minden olyan "IDE" kódstílus-szabályt, amelyet figyelmeztetésként vagy hibaként szeretne futtatni a builden. Példa:

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

    Tipp.

    A .NET 9-től kezdődően a beállításformátumot is használhatja a súlyosság megadásához, és a létrehozáskor figyelembe kell venni. Példa:

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

    Másik lehetőségként konfigurálhat egy teljes kategóriát alapértelmezés szerint figyelmeztetésként vagy hibaként, majd szelektíven kikapcsolhatja a szabályokat abban a kategóriában, amelyet nem szeretne builden futtatni. Példa:

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

Figyelmeztetés mellőzése

A szabálysértések letiltásának egyik módja, ha az adott szabályazonosító none súlyossági beállítását egy Szerkesztőkonfigurációs fájlban állítja be. Példa:

dotnet_diagnostic.CA1822.severity = none

További információkért és a figyelmeztetések letiltásának egyéb módjaiért lásd : Kódelemzési figyelmeztetések letiltása.

Kódelemzés futtatása GitHub-műveletként

A dotnet/code-analysis GitHub Action lehetővé teszi a .NET-kódelemzők offline módban történő futtatását a folyamatos integráció (CI) részeként. További információ: .NET-kódelemzés GitHub Action.

Külső elemzők

A hivatalos .NET-elemzők mellett külső elemzőket is telepíthet, például StyleCop, Roslynator, XUnit Analyzers és Sonar Analyzer.

Lásd még