.NET 原始程式碼分析概觀

.NET 編譯器平台 (Roslyn) 分析器會檢查 C# 或 Visual Basic 程式碼，以找出程式碼品質與樣式問題。 從 .NET 5 開始，這些分析器會隨附於 .NET SDK 中，無須由您個別安裝。 如果您的專案以 .NET 5 或更新版本為目標，依預設會啟用程式碼分析。 如果您的專案以不同的 .NET 實作為目標，例如 .NET Core、.NET Standard 或 .NET Framework，則必須將 EnableNETAnalyzers 屬性設定為 true 以手動啟用程式碼分析。

如果您不想移轉至 .NET 5+ SDK、您具有非 SDK 樣式的 .NET Framework 專案，或偏好使用以 NuGet 套件為基礎的模型，您也可以從 Microsoft.CodeAnalysis.NetAnalyzers NuGet 套件中取得分析器。 您可能偏好使用以套件為基礎的模型，以進行隨選版本更新。

如果分析器發現違規，則會根據每個規則的設定方式，將違規回報為建議、警告或錯誤。 程式碼分析違規顯示時會附有前置詞 "CA" 或 "IDE"，以便與編譯器錯誤區分。

程式碼品質分析

程式碼品質分析 ("CAxxxx") 規則會檢查 C# 或 Visual Basic 程式碼中是否有安全性、效能、設計和其他問題。 根據預設，以 .NET 5 或更新版本為目標的專案會啟用分析器。 您可將 EnableNETAnalyzers 屬性設為 true 來啟用以舊版 .NET 版本為目標的專案上程式碼分析。 您也可將 EnableNETAnalyzers 設定為 false，以停用專案的程式碼分析。

已啟用的規則

您可以變更這些規則的嚴重性以停用規則，或將其提升為錯誤。 您也可以啟用更多規則。

• 如需每個 .NET SDK 版本隨附的規則清單，請參閱分析器版本。
• 如需所有程式碼品質規則的清單，請參閱程式碼品質規則。

啟用其他規則

分析模式是指未啟用任何規則、啟用了部分或所有規則的預先定義程式碼分析組態。 在預設分析模式 (Default) 中，只有少數規則會啟用為建置警告。 您可以設定專案檔中的 <AnalysisMode> 屬性，以變更專案的分析模式。 允許的值包括：

您也可以省略 <AnalysisMode> 屬性的 <AnalysisLevel> 複合值。 例如，下列值會為最新版本啟用建議的規則集：<AnalysisLevel>latest-Recommended</AnalysisLevel>。 如需詳細資訊，請參閱AnalysisLevel。

若要尋找每個可用規則的預設嚴重性，以及規則是否在 Default 分析模式中啟用，請參閱規則的完整清單。

將警告視為錯誤

如果您在建置專案時使用 -warnaserror 旗標，則所有程式碼分析警告也都會被視為錯誤。 在使用 -warnaserror 時，若不想讓程式碼品質警告 (CAxxxx) 被視為錯誤，您可以在專案檔中將 CodeAnalysisTreatWarningsAsErrors MSBuild 屬性設定為 false。

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

您仍然會看到程式碼分析警告，但這並不會中斷您的建置。

最新的更新

根據預設，在升級至較新版的 .NET SDK 時，您將取得最新的程式碼分析規則和預設規則嚴重性。 例如，如果您不想要此行為，例如，您想要確保不會啟用或停用任何新規則，可以使用下列其中一種方式加以覆寫：

• 將 AnalysisLevel MSBuild 屬性設定為特定值，將警告鎖定於該規則集。 當您升級至較新的 SDK 時，仍會收到這些警告的錯誤修正，但不會啟用任何新的警告，也不會停用任何現有的警告。 例如，若要將規則集鎖定至隨附於 .NET SDK 8.0 版的規則，請將下列專案新增至您的項目檔。

  <PropertyGroup>
    <AnalysisLevel>8.0</AnalysisLevel>
  </PropertyGroup>
  

  提示

  AnalysisLevel 屬性的預設值為 latest，這表示當您移轉至較新版的 .NET SDK 時，一律會取得最新的程式碼分析規則。

  如需詳細資訊以及查看可能值的清單，請參閱 AnalysisLevel。

• 安裝 Microsoft.CodeAnalysis.NetAnalyzers NuGet 套件，將規則更新與 .NET SDK 更新分離。 對於以 .NET 5+ 為目標的專案，安裝該套件將會關閉內建 SDK 分析器。 如果 SDK 包含比 NuGet 套件還要新的分析器組件版本，您將會收到建置警告。 若要停用警告，請將 _SkipUpgradeNetAnalyzersNuGetWarning 屬性設定為 true。

  注意

  如果您安裝 Microsoft.CodeAnalysis.NetAnalyzers NuGet 套件，就不應將 EnableNETAnalyzers 屬性新增至專案檔或 Directory.Build.props 檔案。 若已安裝 NuGet 套件，且 EnableNETAnalyzers 屬性設定為 true，則會產生建置警告。

程式碼樣式分析

程式碼樣式分析 ("IDExxxx") 規則可讓您在程式碼基底中定義及維護一致的程式碼樣式。 預設啟用設定如下：

• 命令行建置：命令行組建上所有 .NET 項目預設會停用程式代碼樣式分析。

  您可以在 命令行和 Visual Studio 內，在建置時啟用程式代碼樣式分析。 程式碼樣式違規會顯示為附有 "IDE" 前置詞的警告或錯誤。 這可讓您在建置期間強制執行一致的程式碼樣式。

• Visual Studio：預設會針對 Visual Studio 內的所有 .NET 專案啟用程式代碼樣式分析，以程式代碼重構快速動作。

如需程式碼樣式分析規則的完整清單，請參閱程式碼樣式規則。

在建置時啟用

您可以從命令列和 Visual Studio 中建置時啟用程式代碼樣式分析。 (但基於效能考量，少數程式碼樣式規則仍僅適用於 Visual Studio IDE。)

請依照下列步驟，在建置時啟用程式碼樣式分析：

1. 將 MSBuild 屬性 EnforceCodeStyleInBuild 設定為 true。

2. 在 .editorconfig 檔案中，將您想要對建置執行的每個 "IDE" 程式碼樣式規則設定為警告或錯誤。 例如：

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

   提示

   從 .NET 9 開始，您也可以使用選項格式來指定嚴重性，並在建置階段加以遵守。 例如：

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

   或者，您可以將整個類別預設為警告或錯誤，然後再選擇性地關閉您在該類別中不想對建置執行的規則。 例如：

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

隱藏警告

隱藏違規的方式之一，是在 EditorConfig 檔案中將該規則識別碼的嚴重性選項設定為 none。 例如：

dotnet_diagnostic.CA1822.severity = none

如需隱藏警告的詳細資訊和其他方式，請參閱如何隱藏程式碼分析警告。

第三方分析器

除了官方 .NET 分析器以外，您也可以安裝第三方分析器，例如 StyleCop、Roslynator、XUnit Analyzers 和 Sonar Analyzer。

另請參閱

• 程式碼品質分析規則參考
• 程式碼樣式分析規則參考
• Visual Studio 中的程式碼分析
• .NET Compiler Platform SDK
• 教學課程：撰寫您的第一個分析器和程式碼修正
• ASP.NET Core 應用程式中的程式碼分析