Übersicht über die Analyse von .NET-Quellcode

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.

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.

Aktivieren von Regeln

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

• Eine Liste der Regeln, die in jeder .NET SDK-Version enthalten sind, finden Sie unter Analysetoolreleases.
• Eine Liste aller Codequalitätsregeln finden Sie unter Codequalitätsregeln.

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:

Sie können auch zugunsten eines zusammengesetzten Werts für die <AnalysisLevel> Eigenschaft weglassen<AnalysisMode>. 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. Wenn Sie beispielsweise die Regelsätze für die Regeln sperren möchten, die mit Version 8.0 des .NET SDK ausgeliefert werden, fügen Sie der Projektdatei den folgenden Eintrag hinzu.

  <PropertyGroup>
    <AnalysisLevel>8.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 Codeformatanalyse ist standardmäßig für alle .NET-Projekte in Befehlszeilenbuilds deaktiviert.

  Sie können die Codeformatanalyse beim Build sowohl in der Befehlszeile als auch in Visual Studio aktivieren. 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: Die Codeformatanalyse ist standardmäßig für alle .NET-Projekte in Visual Studio als codeumgestaltende schnelle Aktionen aktiviert.

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

Beim Build aktivieren

Sie können die Codeformatanalyse beim Erstellen ü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.

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

• Referenz zu Regeln für die Codequalitätsanalyse
• Referenz zu Regeln für die Analyse des Codeformats
• Codeanalyse in Visual Studio
• .NET Compiler Platform SDK
• Tutorial: Schreiben Ihres ersten Analysetools und Codefixes
• Code analysis in ASP.NET Core apps (Codeanalyse in ASP.NET Core-Apps)