Overzicht van .NET-broncodeanalyse

  • Artikel

Met .NET-compilerplatformanalyses (Roslyn) wordt uw C# of Visual Basic-code gecontroleerd op problemen met de kwaliteit en stijl van code. Vanaf .NET 5 zijn deze analyses opgenomen in de .NET SDK en hoeft u ze niet afzonderlijk te installeren. Als uw project is gericht op .NET 5 of hoger, is codeanalyse standaard ingeschakeld. Als uw project is gericht op een andere .NET-implementatie, bijvoorbeeld .NET Core, .NET Standard of .NET Framework, moet u codeanalyse handmatig inschakelen door de eigenschap EnableNETAnalyzers in te stellen op true.

Als u niet wilt overstappen op de .NET 5+ SDK, een .NET Framework-project zonder SDK-stijl hebt of liever een NuGet-model op basis van pakketten wilt gebruiken, zijn de analyses ook beschikbaar in het NuGet-pakket Microsoft.CodeAnalysis.NetAnalyzers. Mogelijk geeft u de voorkeur aan een model op basis van pakketten voor updates op aanvraagversies.

Notitie

.NET Analyzers zijn doelframeworkagnostisch. Uw project hoeft zich dus niet te richten op een specifieke .NET-implementatie. De analyses werken voor projecten die gericht zijn op .NET 5+ en eerdere .NET-versies, zoals .NET Core 3.1 en .NET Framework 4.7.2. Als u echter codeanalyse wilt inschakelen met behulp van de eigenschap EnableNETAnalyzers , moet uw project verwijzen naar een project-SDK.

Als schendingen van regels worden gevonden door een analyse, worden ze gerapporteerd als suggestie, waarschuwing of fout, afhankelijk van hoe elke regel is geconfigureerd. Schendingen van codeanalyse worden weergegeven met het voorvoegsel 'CA' of 'IDE' om deze te onderscheiden van compilerfouten.

Analyse van codekwaliteit

Regels voor codekwaliteitsanalyse ('CAxxxx') inspecteren uw C# of Visual Basic-code voor beveiliging, prestaties, ontwerp en andere problemen. Analyse is standaard ingeschakeld voor projecten die zijn gericht op .NET 5 of hoger. U kunt codeanalyse inschakelen voor projecten die zich richten op eerdere .NET-versies door de eigenschap EnableNETAnalyzers in te stellen op true. U kunt ook codeanalyse voor uw project uitschakelen door in te stellen EnableNETAnalyzers op false.

Tip

Als u Visual Studio gebruikt, hebben veel analyseregels codecorrecties gekoppeld die u kunt toepassen om het probleem op te lossen. Codecorrecties worden weergegeven in het pictogrammenu van de gloeilamp.

Ingeschakelde regels

De volgende regels zijn standaard ingeschakeld als fouten of waarschuwingen in .NET 8. Aanvullende regels worden ingeschakeld als suggesties.

Diagnostische id Categorie Ernst Versie toegevoegd Beschrijving
CA1416 Interoperabiliteit Waarschuwing .NET 5 Platformcompatibiliteit valideren
CA1417 Interoperabiliteit Waarschuwing .NET 5 Niet gebruiken OutAttribute voor tekenreeksparameters voor P/Invokes
CA1418 Interoperabiliteit Waarschuwing .NET 6 Geldige platformtekenreeks gebruiken
CA1420 Interoperabiliteit Waarschuwing .NET 7 Het gebruik van functies waarvoor runtime-marshalling is vereist wanneer deze is uitgeschakeld, resulteert in runtime-uitzonderingen
CA1422 Interoperabiliteit Waarschuwing .NET 7 Platformcompatibiliteit valideren
CA1831 Prestaties Waarschuwing .NET 5 Gebruik AsSpan in plaats van op bereik gebaseerde indexeerfuncties voor tekenreeksen indien van toepassing
CA1856 Prestaties Error .NET 8 Onjuist gebruik van ConstantExpected kenmerk
CA1857 Prestaties Waarschuwing .NET 8 Er wordt een constante verwacht voor de parameter
CA2013 Betrouwbaarheid Waarschuwing .NET 5 Niet gebruiken ReferenceEquals met waardetypen
CA2014 Betrouwbaarheid Waarschuwing .NET 5 Niet gebruiken stackalloc in lussen
CA2015 Betrouwbaarheid Waarschuwing .NET 5 Definieer geen finalizers voor typen die zijn afgeleid van MemoryManager<T>
CA2017 Betrouwbaarheid Waarschuwing .NET 6 Aantal parameters komt niet overeen
CA2018 Betrouwbaarheid Waarschuwing .NET 6 Het count argument om Buffer.BlockCopy het aantal te kopiëren bytes op te geven
CA2021 Betrouwbaarheid Waarschuwing .NET 8 Niet aanroepen Enumerable.Cast<T> of Enumerable.OfType<T> met niet-compatibele typen
CA2200 Gebruik Waarschuwing .NET 5 Opnieuw verzamelen om stackdetails te behouden
CA2247 Gebruik Waarschuwing .NET 5 Argument dat is doorgegeven aan TaskCompletionSource constructor, moet enum zijn TaskCreationOptions in plaats van TaskContinuationOptions
CA2252 Gebruik Error .NET 6 Aanmelden voor preview-functies
CA2255 Gebruik Waarschuwing .NET 6 Het ModuleInitializer kenmerk mag niet worden gebruikt in bibliotheken
CA2256 Gebruik Waarschuwing .NET 6 Alle leden die in bovenliggende interfaces zijn gedeclareerd, moeten beschikken over een implementatie in een DynamicInterfaceCastableImplementationtoegewezen interface
CA2257 Gebruik Waarschuwing .NET 6 Leden die zijn gedefinieerd op een interface met de DynamicInterfaceCastableImplementationAttributestatic
CA2258 Gebruik Waarschuwing .NET 6 Het bieden van een DynamicInterfaceCastableImplementation interface in Visual Basic wordt niet ondersteund
CA2259 Gebruik Waarschuwing .NET 7 ThreadStatic is alleen van invloed op statische velden
CA2260 Gebruik Waarschuwing .NET 7 De juiste typeparameter gebruiken
CA2261 Gebruik Waarschuwing .NET 8 Niet gebruiken ConfigureAwaitOptions.SuppressThrowing met Task<TResult>

U kunt de ernst van deze regels wijzigen om ze uit te schakelen of ze te verhogen naar fouten. U kunt ook meer regels inschakelen.

Aanvullende regels inschakelen

De analysemodus verwijst naar een vooraf gedefinieerde configuratie voor codeanalyse waarbij geen, sommige of alle regels zijn ingeschakeld. In de standaardanalysemodus (Default) worden slechts een klein aantal regels ingeschakeld als buildwaarschuwingen. U kunt de analysemodus voor uw project wijzigen door de <AnalysisMode> eigenschap in het projectbestand in te stellen. De toegestane waarden zijn:

Weergegeven als Beschrijving
None Alle regels zijn uitgeschakeld. U kunt selectief kiezen voor afzonderlijke regels om ze in te schakelen.
Default Standaardmodus, waarbij bepaalde regels zijn ingeschakeld als buildwaarschuwingen, worden bepaalde regels ingeschakeld als Visual Studio IDE-suggesties en de rest is uitgeschakeld.
Minimum Agressievere modus dan Default modus. Bepaalde suggesties die sterk worden aanbevolen voor het afdwingen van builds, worden ingeschakeld als buildwaarschuwingen. Als u wilt zien welke regels dit omvat, inspecteert u het bestand %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig .
Recommended Agressievere modus dan Minimum de modus, waarbij meer regels zijn ingeschakeld als buildwaarschuwingen. Als u wilt zien welke regels dit omvat, inspecteert u het bestand %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig .
All Alle regels worden ingeschakeld als buildwaarschuwingen*. U kunt selectief afmelden voor afzonderlijke regels om ze uit te schakelen.

* De volgende regels zijn niet ingeschakeld door instelling in of door in te All stellen AnalysisModeAnalysisLevel oplatest-all: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 en de regels voor metrische gegevensanalyse (CA1501, CA1502, CA1505, CA1506 en CA1509). Deze verouderde regels zijn mogelijk afgeschaft in een toekomstige versie. U kunt ze echter nog steeds afzonderlijk inschakelen met behulp van een dotnet_diagnostic.CAxxxx.severity = <severity> vermelding.

Vanaf .NET 6 kunt u een samengestelde waarde voor de <AnalysisLevel> eigenschap weglaten<AnalysisMode>. Met de volgende waarde kunt u bijvoorbeeld de aanbevolen set regels voor de meest recente release inschakelen: <AnalysisLevel>latest-Recommended</AnalysisLevel> Zie AnalysisLevel voor meer informatie.

Als u de standaard ernst voor elke beschikbare regel wilt vinden en of de regel al dan niet is ingeschakeld in Default de analysemodus, raadpleegt u de volledige lijst met regels.

Waarschuwingen behandelen als fouten

Als u de vlag gebruikt bij het -warnaserror bouwen van uw projecten, worden alle waarschuwingen voor codeanalyse ook behandeld als fouten. Als u niet wilt dat codekwaliteitswaarschuwingen (CAxxxx) worden behandeld als fouten in aanwezigheid van -warnaserror, kunt u de CodeAnalysisTreatWarningsAsErrors eigenschap false MSBuild instellen op in uw projectbestand.

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

U ziet nog steeds waarschuwingen voor codeanalyse, maar uw build wordt hierdoor niet verbroken.

Nieuwste updates

Standaard krijgt u de meest recente codeanalyseregels en standaardregel ernst bij het upgraden naar nieuwere versies van de .NET SDK. Als u dit gedrag niet wilt, bijvoorbeeld als u ervoor wilt zorgen dat er geen nieuwe regels zijn ingeschakeld of uitgeschakeld, kunt u deze op een van de volgende manieren overschrijven:

  • Stel de AnalysisLevel eigenschap MSBuild in op een specifieke waarde om de waarschuwingen op die set te vergrendelen. Wanneer u een upgrade uitvoert naar een nieuwere SDK, krijgt u nog steeds bugfixes voor deze waarschuwingen, maar worden er geen nieuwe waarschuwingen ingeschakeld en worden er geen bestaande waarschuwingen uitgeschakeld. Als u bijvoorbeeld de set regels wilt vergrendelen voor regels die worden verzonden met versie 5.0 van de .NET SDK, voegt u de volgende vermelding toe aan uw projectbestand.

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

    Tip

    De standaardwaarde voor de AnalysisLevel eigenschap is latest, wat betekent dat u altijd de meest recente codeanalyseregels krijgt wanneer u overstapt op nieuwere versies van de .NET SDK.

    Zie AnalysisLevel voor meer informatie en om een lijst met mogelijke waarden weer te geven.

  • Installeer het NuGet-pakket Microsoft.CodeAnalysis.NetAnalyzers om regelupdates van .NET SDK-updates los te koppelen. Voor projecten die gericht zijn op .NET 5+, schakelt het installeren van het pakket de ingebouwde SDK-analyseprogramma's uit. U krijgt een buildwaarschuwing als de SDK een nieuwere versie van de analyzer-assembly bevat dan die van het NuGet-pakket. Als u de waarschuwing wilt uitschakelen, stelt u de _SkipUpgradeNetAnalyzersNuGetWarning eigenschap in op true.

    Notitie

    Als u het NuGet-pakket Microsoft.CodeAnalysis.NetAnalyzers installeert, moet u de eigenschap EnableNETAnalyzers niet toevoegen aan uw projectbestand of een Map.Build.props-bestand . Wanneer het NuGet-pakket is geïnstalleerd en de EnableNETAnalyzers eigenschap is ingesteld op true, wordt er een buildwaarschuwing gegenereerd.

Analyse van codestijl

Met regels voor codestijlanalyse ('IDExxxx') kunt u consistente codestijl definiëren en onderhouden in uw codebasis. De standaardinstellingen voor inschakelen zijn:

  • Opdrachtregelbuild: Analyse van codestijl is standaard uitgeschakeld voor alle .NET-projecten op opdrachtregelbuilds.

    Vanaf .NET 5 kunt u analyse in codestijl inschakelen op build, zowel op de opdrachtregel als in Visual Studio. Schendingen van codestijlen worden weergegeven als waarschuwingen of fouten met een IDE-voorvoegsel. Hiermee kunt u consistente codestijlen afdwingen tijdens het bouwen.

  • Visual Studio: Analyse van codestijl is standaard ingeschakeld voor alle .NET-projecten in Visual Studio als codeherstructurering van snelle acties.

Zie Codestijlregels voor een volledige lijst met regels voor codestijlanalyse.

Inschakelen bij build

Met de .NET 5 SDK en latere versies kunt u analyse in codestijl inschakelen bij het bouwen vanaf de opdrachtregel en in Visual Studio. (Om prestatieredenen zijn er echter nog steeds enkele regels voor codestijlen van toepassing in de Visual Studio IDE.)

Volg deze stappen om analyse in codestijl in te schakelen bij het bouwen:

  1. Stel de msBuild-eigenschap EnforceCodeStyleInBuild in op true.

  2. Configureer in een .editorconfig-bestandelke 'IDE'-codestijlregel die u wilt uitvoeren bij het bouwen als een waarschuwing of een fout. Voorbeeld:

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

    Tip

    Vanaf .NET 9 kunt u ook de optieindeling gebruiken om een ernst op te geven en deze tijdens de build te laten respecteren. Voorbeeld:

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

    U kunt ook een hele categorie configureren als een waarschuwing of fout, standaard en vervolgens selectief regels uitschakelen in die categorie die u niet wilt uitvoeren op build. Voorbeeld:

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

Een waarschuwing onderdrukken

Een manier om een schending van een regel te onderdrukken, is door de ernstoptie voor die regel-id none in te stellen in een EditorConfig-bestand. Voorbeeld:

dotnet_diagnostic.CA1822.severity = none

Zie Codeanalysewaarschuwingen onderdrukken voor meer informatie en andere manieren om waarschuwingen te onderdrukken.

Codeanalyse uitvoeren als een GitHub-actie

Met de GitHub Action dotnet/code-analysis kunt u .NET-codeanalyses uitvoeren als onderdeel van continue integratie (CI) in een offlinemodus. Zie GitHub Action voor .NET-codeanalyse voor meer informatie.

Analyse van derden

Naast de officiële .NET Analyzers kunt u ook analyses van derden installeren, zoals StyleCop, Roslynator, XUnit Analyzers en Sonar Analyzer.

Zie ook