Übersicht über die Analyse von .NET-Quellcode

  • Artikel

Die Analysetools für die .NET-Compilerplattform (Roslyn) untersuchen Ihren C#- oder Visual Basic-Code auf Probleme hinsichtlich Codequalität und -format. Ab .NET 5 sind diese Analysetools im .NET SDK enthalten und müssen nicht separat installiert werden. Wenn Ihr Projekt auf .NET 5 oder höher ausgerichtet ist, ist Codeanalyse standardmäßig aktiviert. Wenn das Projekt eine andere .NET-Implementierung als Ziel verwendet, z. B. .NET Core, .NET Standard oder .NET Framework, müssen Sie Codeanalyse manuell aktivieren, indem Sie die EnableNETAnalyzers-Eigenschaft auf true festlegen.

Wenn Sie nicht auf das .NET 5 SDK oder höher umsteigen möchten, ein .NET Framework-Projekt im Nicht-SDK-Stil verwenden oder ein NuGet-Paket-basiertes Modell bevorzugen, sind die Analysetools auch im NuGet-Paket Microsoft.CodeAnalysis.NetAnalyzers verfügbar. Möglicherweise bevorzugen Sie ein paketbasiertes Modell für bedarfsgesteuerte Versionsaktualisierungen.

Hinweis

.NET-Analysetools sind zielframework-agnostisch. Das heißt, das Projekt muss keine bestimmte .NET-Implementierung als Ziel verwenden. Die Analysetools funktionieren für Projekte, die .NET 5 oder höher sowie frühere .NET-Versionen als Ziel verwenden, z. B. .NET Core 3.1 und .NET Framework 4.7.2. Um Code Analyse mithilfe der EnableNETAnalyzers-Eigenschaft zu aktivieren, muss das Projekt jedoch auf ein Projekt-SDK verweisen.

Wenn Regelverstöße von einem Analysetool gefunden werden, werden sie abhängig von der Konfiguration der einzelnen Regeln als Vorschlag, Warnung oder Fehler gemeldet. Codeanalyseverstöße werden mit dem Präfix „CA“ oder „IDE“ angezeigt, um sie von Compilerfehlern zu unterscheiden.

Analyse der Codequalität

Regeln der Analyse der Codequalität analysieren Ihren C#- oder Visual Basic-Code hinsichtlich Sicherheit, Leistung, Design und anderen Problemen. Analyse ist für Projekte, die auf .NET 5 oder höher ausgerichtet sind, standardmäßig aktiviert. Sie können die Codeanalyse für Projekte aktivieren, die auf frühere Versionen von .NET abzielen, indem Sie die Eigenschaft EnableNETAnalyzers auf true festlegen. Sie können Codeanalyse für Ihr Projekt auch deaktivieren, indem Sie EnableNETAnalyzers auf false festlegen.

Tipp

Wenn Sie Visual Studio verwenden, verfügen viele Analysetoolregeln über zugehörige Codekorrekturen, die Sie zur Problembehebung anwenden können. Codekorrekturen werden im Fehlerbehebungsmenü (Glühbirnensymbol) angezeigt.

Aktivieren von Regeln

Die folgenden Regeln sind standardmäßig als Fehler oder Warnungen in .NET 8 aktiviert. Zusätzliche Regeln werden als Vorschläge aktiviert.

Diagnose-ID Kategorie Severity Hinzugefügte Version Beschreibung
CA1416 Interoperabilität Warnung .NET 5 Plattformkompatibilität überprüfen
CA1417 Interoperabilität Warnung .NET 5 Verwenden Sie OutAttribute nicht für Zeichenfolgenparameter für P/Invokes.
CA1418 Interoperabilität Warnung .NET 6 Verwenden einer gültigen Plattformzeichenfolge
CA1420 Interoperabilität Warnung .NET 7 Wenn Features, die Runtime-Marshalling erfordern, verwendet werden und das Runtime-Marshalling deaktiviert ist, treten Laufzeitausnahmen auf.
CA1422 Interoperabilität Warnung .NET 7 Plattformkompatibilität überprüfen
CA1831 Leistung Warnung .NET 5 Verwenden Sie für Zeichenfolgen bei Bedarf anstelle von bereichsbasierten Indexern AsSpan.
CA1856 Leistung Fehler .NET 8 Falsche Verwendung des Attributs ConstantExpected
CA1857 Leistung Warnung .NET 8 Für den Parameter wird eine Konstante erwartet.
CA2013 Zuverlässigkeit Warnung .NET 5 Verwenden Sie ReferenceEquals nicht mit Werttypen.
CA2014 Zuverlässigkeit Warnung .NET 5 Verwenden Sie stackalloc nicht in Schleifen.
CA2015 Zuverlässigkeit Warnung .NET 5 Definieren Sie keine Finalizer für Typen, die von MemoryManager<T> abgeleitet sind.
CA2017 Zuverlässigkeit Warnung .NET 6 Konflikt bei der Parameteranzahl
CA2018 Zuverlässigkeit Warnung .NET 6 Das count-Argument für Buffer.BlockCopy sollte die Anzahl der zu kopierenden Bytes angeben
CA2021 Zuverlässigkeit Warnung .NET 8 Rufen Sie Enumerable.Cast<T> oder Enumerable.OfType<T> nicht mit inkompatiblen Typen auf.
CA2200 Verwendung Warnung .NET 5 Erneut ausführen, um Stapeldetails beizubehalten.
CA2247 Verwendung Warnung .NET 5 Argument, das an den TaskCompletionSource-Konstruktor übergeben wird, sollte eine TaskCreationOptions-Enumeration anstatt TaskContinuationOptions sein.
CA2252 Verwendung Fehler .NET 6 Abonnieren von Previewfunktionen
CA2255 Verwendung Warnung .NET 6 Das ModuleInitializer-Attribut sollte nicht in Bibliotheken verwendet werden
CA2256 Verwendung Warnung .NET 6 Alle in übergeordneten Schnittstellen deklarierten Member müssen über eine Implementierung in einer Schnittstelle mit dem Attribut DynamicInterfaceCastableImplementation verfügen
CA2257 Verwendung Warnung .NET 6 Member, die für eine Schnittstelle mit DynamicInterfaceCastableImplementationAttribute definiert sind, sollten static sein
CA2258 Verwendung Warnung .NET 6 Das Bereitstellen einer DynamicInterfaceCastableImplementation-Schnittstelle in Visual Basic wird nicht unterstützt.
CA2259 Verwendung Warnung .NET 7 ThreadStatic wirkt sich nur auf statische Felder aus.
CA2260 Verwendung Warnung .NET 7 Verwenden Sie den richtigen Typparameter.
CA2261 Verwendung Warnung .NET 8 Verwenden Sie ConfigureAwaitOptions.SuppressThrowing nicht mit Task<TResult>

Sie können den Schweregrad dieser Regeln ändern, um sie zu deaktivieren oder zu Fehlern heraufzustufen. Sie können auch weitere Regeln aktivieren.

Aktivieren zusätzlicher Regeln

Der Analysemodus verweist auf eine vordefinierte Codeanalysekonfiguration, bei der keine, einige oder alle Regeln aktiviert sind. Im Standardanalysemodus (Default) wird nur eine kleine Anzahl von Regeln als Buildwarnungen aktiviert. Sie können den Analysemodus für Ihr Projekt ändern, indem Sie die <AnalysisMode>-Eigenschaft in der Projektdatei festlegen. Zulässige Werte sind:

Wert Beschreibung
None Alle Regeln sind deaktiviert. Sie können einzelne Regeln selektiv aktivieren.
Default Dies ist der Standardmodus, in dem bestimmte Regeln als Buildwarnungen bzw. Visual Studio-IDE-Vorschläge aktiviert sind und der Rest deaktiviert ist.
Minimum Aggressiverer Modus als der Modus Default. Bestimmte Vorschläge, die für die Builderzwingung dringend empfohlen werden, werden als Buildwarnungen aktiviert. Um festzustellen, welche Regeln darin enthalten sind, überprüfen Sie die Datei %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig.
Recommended Ein aggressiverer Modus als der Minimum-Modus, in dem mehr Regeln als Buildwarnungen aktiviert sind. Um festzustellen, welche Regeln darin enthalten sind, überprüfen Sie die Datei %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig.
All Alle Regeln sind als Buildwarnungen* aktiviert. Sie können einzelne Regeln deaktivieren.

* Die folgenden Regeln sind nicht durch Festlegen von AnalysisMode auf All oder durch Festlegen von AnalysisLevel auf latest-all aktiviert: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021, und die Codemetrikenanalyseregeln (CA1501, CA1502, CA1505, CA1506, und CA1509). Diese Legacy-Regeln sind möglicherweise in einer zukünftigen Version veraltet. Sie können sie jedoch weiterhin einzeln mithilfe eines dotnet_diagnostic.CAxxxx.severity = <severity>-Eintrags aktivieren.

Ab .NET 6 können Sie <AnalysisMode> zugunsten eines zusammengesetzten Werts für die <AnalysisLevel>-Eigenschaft auslassen. Der folgende Wert aktiviert beispielsweise den empfohlenen Satz von Regeln für das neueste Release: <AnalysisLevel>latest-Recommended</AnalysisLevel>. Weitere Informationen finden Sie unter AnalysisLevel.

Den Standardschweregrad für jede verfügbare Regel und ob die Regel im Analysemodus Default aktiviert ist, erfahren Sie in der vollständigen Liste der Regeln.

Warnungen als Fehler behandeln

Wenn Sie das -warnaserror-Flag verwenden, wenn Sie Projekte erstellen, werden alle Codeanalysewarnungen ebenfalls als Fehler behandelt. Wenn Sie nicht möchten, dass Codequalitätswarnungen (CAxxxx) bei Vorhandensein von -warnaserror als Fehler behandelt werden, können Sie die MSBuild Eigenschaft CodeAnalysisTreatWarningsAsErrors in Ihrer Projektdatei auf false festlegen.

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

Sie werden weiterhin Warnungen der Codeanalyse sehen, aber sie werden Ihren Buildvorgang nicht beeinträchtigen.

Neueste Updates

Standardmäßig erhalten Sie die neuesten Codeanalyseregeln und Standardregelschweregrade, wenn Sie ein Upgrade auf neuere Versionen des .NET SDK durchführen. Wenn Sie dieses Verhalten nicht wünschen (z. B. wenn Sie sicherstellen möchten, dass keine neuen Regeln aktiviert oder deaktiviert sind), können Sie es mit einer der folgenden Methoden außer Kraft setzen:

  • Legen Sie die MSBuild-Eigenschaft AnalysisLevelauf einen bestimmten Wert fest, um die Warnungen für diese Gruppe zu sperren. Wenn Sie ein Upgrade auf ein neueres SDK durchführen, erhalten Sie weiterhin Fehlerbehebungen für diese Warnungen, aber es werden keine neuen Warnungen aktiviert, und vorhandene Warnungen werden nicht deaktiviert. Um den Regelsatz z. B. auf die Regeln zu beschränken, die mit Version 5.0 des .NET SDK ausgeliefert werden, fügen Sie den folgenden Eintrag in Ihre Projektdatei ein.

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

    Tipp

    Der Standardwert für die Eigenschaft AnalysisLevel ist latest, d. h. Sie erhalten immer die neuesten Codeanalyseregeln, wenn Sie zu neueren Versionen des .NET SDK wechseln.

    Weitere Informationen und eine Liste möglicher Werte finden Sie unter AnalysisLevel.

  • Installieren Sie das NuGet-Paket Microsoft.CodeAnalysis.NetAnalyzers, um Regelupdates von .NET SDK-Updates zu entkoppeln. Für Projekte, die auf .NET 5 oder höher abzielen, deaktiviert die Installation des Pakets die integrierten SDK-Analysetools. Sie erhalten eine Buildwarnung, wenn das SDK eine neuere Analysetool-Assemblyversion als die des NuGet-Pakets enthält. Um die Warnung zu deaktivieren, legen Sie die _SkipUpgradeNetAnalyzersNuGetWarning-Eigenschaft auf true fest.

    Hinweis

    Wenn Sie das NuGet-Paket Microsoft.CodeAnalysis.NetAnalyzers installieren, sollten Sie die EnableNETAnalyzers-Eigenschaft weder der Projektdatei noch einer Datei Directory.Build.props hinzufügen. Wenn das NuGet-Paket installiert und die EnableNETAnalyzers-Eigenschaft auf true festgelegt ist, wird eine Buildwarnung generiert.

Analyse des Codeformats

Regeln für Analyse des Codeformats („IDExxxx“) ermöglichen es Ihnen, konsistentes Codeformat in Ihrer Codebasis zu definieren und zu verwalten. Folgende Standardeinstellungen für Aktivierung sind verfügbar:

  • Befehlszeilenbuild: Die Analyse des Codeformats ist standardmäßig für alle .NET-Projekte für Befehlszeilenbuilds deaktiviert.

    Ab .NET 5 können Sie die Analyse des Codeformats für den Build aktivieren, sowohl in der Befehlszeile als auch in Visual Studio. Verstöße gegen das Codeformat werden als Warnungen oder Fehler mit dem Präfix „IDE“ angezeigt. Dies ermöglicht es Ihnen, ein konsistentes Codeformat zum Zeitpunkt der Erstellung zu erzwingen.

  • Visual Studio: Analyse des Codeformats ist standardmäßig für alle .NET-Projekte in Visual Studio als Schnelle Aktionen für Coderefactoring aktiviert.

Eine vollständige Liste der Regeln für die Codeanalyse finden Sie unter Regeln für die Analyse des Codeformats.

Beim Build aktivieren

Mit dem .NET 5 SDK und höheren Versionen können Sie die Analyse des Codeformats beim Buildvorgang über die Befehlszeile und in Visual Studio aktivieren. (Aus Leistungsgründen gelten jedoch einige Regeln für das Codeformat weiterhin nur in der Visual Studio-IDE.)

Führen Sie die folgenden Schritte aus, um Analyse des Codeformats beim Buildvorgang zu aktivieren:

  1. Legen Sie die MSBuild-Eigenschaft EnforceCodeStyleInBuild auf true fest.

  2. Konfigurieren Sie in einer EDITORCONFIG-Datei jede „IDE“-Codeformatregel, die Sie beim Buildvorgang ausführen möchten, als Warnung oder Fehler. Beispiel:

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

    Tipp

    Ab .NET 9 können Sie auch das Optionsformat verwenden, um einen Schweregrad anzugeben, der dann bei der Erstellung berücksichtigt wird. Beispiel:

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

    Alternativ können Sie eine ganze Kategorie standardmäßig als Warnung oder Fehler konfigurieren und dann selektiv Regeln in dieser Kategorie deaktivieren, die Sie nicht beim Buildvorgang ausführen möchten. Beispiel:

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

Unterdrücken einer Warnung

Eine Möglichkeit, eine Regelverletzung zu unterdrücken, besteht darin, die Option für den Schweregrad für die betreffende Regel-ID none in einer EDITORCONFIG-Datei festzulegen. Beispiel:

dotnet_diagnostic.CA1822.severity = none

Weitere Informationen und weitere Möglichkeiten, Warnungen zu unterdrücken, finden Sie unter Unterdrücken von Codeanalysewarnungen.

Ausführen der Codeanalyse als GitHub-Aktion

Mit der GitHub-Aktion dotnet/code-analysis können Sie .NET-Codeanalysetools als Teil von Continuous Integration (CI) in einem Offlinemodus ausführen. Weitere Informationen finden Sie unter GitHub-Aktion für .NET-Codeanalyse.

Analysetools von Drittanbietern

Zusätzlich zu den offiziellen .NET-Analysetools können Sie auch Analysetools von Drittanbieters installieren, z. B. StyleCop, Roslynator, XUnit Analyzers und Sonar Analyzer.

Weitere Informationen