.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 套件中使用。 您可能會偏好以套件為基礎的模型進行隨選版本更新。
注意
.NET 分析器與目標架構無關。 也就是說，您的專案不需要以特定的 .NET 實作為目標。 分析器適用于以 .NET 5+ 和舊版 .NET 為目標的專案，例如 .NET Core 3.1 和 .NET Framework 4.7.2。 不過，若要使用 EnableNETAnalyzers 屬性啟用程式碼分析，您的專案必須參考 專案 SDK。
如果分析器發現規則違規，則會根據每個規則的 設定方式，回報為建議、警告或錯誤。 程式碼分析違規會出現前置詞 「CA」 或 「IDE」，以區分它們與編譯器錯誤。
程式碼品質分析
程式碼品質分析 (「CAxxxx」) 規則會檢查您的 C# 或 Visual Basic 程式碼是否有安全性、效能、設計和其他問題。 預設會針對以 .NET 5 或更新版本為目標的專案啟用分析。 您可以將 EnableNETAnalyzers 屬性設定為 true ，在以舊版 .NET 版本為目標的專案上啟用程式碼分析。 您也可以將 設定 EnableNETAnalyzers 為 false 來停用專案的程式碼分析。
提示
如果您使用 Visual Studio，許多分析器規則都有相關聯的程式 代碼修正 ，您可以套用以修正問題。 程式碼修正會顯示在燈泡圖示功能表中。
已啟用的規則
根據預設，在 .NET 7 中會啟用下列規則。
| 診斷識別碼 | 類別 | 嚴重性 | 描述 |
|---|---|---|---|
| CA1416 | 互通性 | 警告 | 驗證平臺相容性 |
| CA1417 | 互通性 | 警告 | 請勿在 OutAttribute P/Invokes 的字串參數上使用 |
| CA1418 | 互通性 | 警告 | 使用有效的平臺字串 |
| CA1420 | 互通性 | 警告 | 當執行時間封送處理停用時，使用需要執行時間封送處理的功能會導致執行時間例外狀況 |
| CA1422 | 互通性 | 警告 | 驗證平臺相容性 |
| CA1831 | 效能 | 警告 | 適當時，請針對字串使用 AsSpan 範圍索引子，而不是以範圍為基礎的索引子 |
| CA2013 | 可靠性 | 警告 | 請勿搭配實數值型別使用 ReferenceEquals |
| CA2014 | 可靠性 | 警告 | 不要在迴圈中使用 stackalloc |
| CA2015 | 可靠性 | 警告 | 請勿為衍生自的類型定義完成項 MemoryManager<T> |
| CA2017 | 可靠性 | 警告 | 參數計數不符 |
| CA2018 | 可靠性 | 警告 | 的 count 引數 Buffer.BlockCopy 應該指定要複製的位元組數目 |
| CA2200 | 使用量 | 警告 | 必須重新擲回以保存堆疊詳細資料 |
| CA2252 | 使用量 | 錯誤 | 加入宣告預覽功能 |
| CA2247 | 使用量 | 警告 | 傳遞至 TaskCompletionSource 建構函式的引數應該是 TaskCreationOptions 列舉，而不是 TaskContinuationOptions |
| CA2255 | 使用量 | 警告 | 屬性 ModuleInitializer 不應該用於程式庫 |
| CA2256 | 使用量 | 警告 | 父介面中宣告的所有成員都必須在 -attributed 介面中 DynamicInterfaceCastableImplementation 具有實作 |
| CA2257 | 使用量 | 警告 | 在介面 DynamicInterfaceCastableImplementationAttribute 上定義的成員應為 static |
| CA2258 | 使用量 | 警告 | DynamicInterfaceCastableImplementation不支援在 Visual Basic 中提供介面 |
| CA2259 | 使用量 | ThreadStatic 只會影響靜態欄位 |
|
| CA2260 | 使用量 | 使用正確的類型參數 |
您可以變更這些規則的嚴重性來停用這些規則，或將其提升為錯誤。 您也可以 啟用更多規則。
啟用其他規則
分析模式 是指預先定義的程式碼分析組態，其中未啟用任何、部分或所有規則。 在預設分析模式中，只有少量的規則 會啟用為建置警告。 您可以在專案檔中設定< AnalysisMode >屬性，以變更專案的分析模式。 允許的值包括：
None
Default
Minimum
Recommended
All
從 .NET 6 開始，您可以省略< AnalysisMode >，以支援 AnalysisLevel > 屬性的 < 複合值。 例如，下列值會啟用最新版本的建議規則集： <AnalysisLevel>latest-Recommended</AnalysisLevel> 。 如需詳細資訊，請參閱 AnalysisLevel。
若要尋找每個可用規則的預設嚴重性，以及規則是否在預設分析模式中啟用，請參閱 規則的完整清單。
將警告視為錯誤
如果您在建置專案時使用 -warnaserror 旗標，則所有程式碼分析警告也會被視為錯誤。 如果您不想讓程式碼品質警告 (CAxxxx) 視為錯誤， -warnaserror 您可以在專案檔中將 MSBuild 屬性設定 CodeAnalysisTreatWarningsAsErrors 為 false 。
<PropertyGroup>
<CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>
您仍然會看到任何程式碼分析警告，但不會中斷您的組建。
最新的更新
根據預設，當您升級至較新版本的 .NET SDK 時，您將取得最新的程式碼分析規則和預設規則嚴重性。 例如，如果您不想要此行為，如果您想要確保未啟用或停用任何新規則，您可以使用下列其中一種方式來覆寫它：
將
AnalysisLevelMSBuild 屬性設定為特定值，以鎖定該集合的警告。 當您升級至較新的 SDK 時，您仍會收到這些警告的錯誤修正，但不會啟用任何新的警告，也不會停用任何現有的警告。 例如，若要將規則集鎖定至隨附于 .NET SDK 5.0 版的規則，請將下列專案新增至您的專案檔。<PropertyGroup> <AnalysisLevel>5.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 專案停用程式碼樣式分析。
從 .NET 5 開始，您可以在命令列和 Visual Studio 內 啟用建置程式碼樣式分析。 程式碼樣式違規會顯示為具有 「IDE」 前置詞的警告或錯誤。 這可讓您在建置階段強制執行一致的程式碼樣式。
Visual Studio：預設會針對 Visual Studio 內的所有 .NET 專案啟用程式碼樣式分析，以 程式碼重構快速動作。
如需程式碼樣式分析規則的完整清單，請參閱 程式碼樣式規則。
在組建上啟用
使用 .NET 5 SDK 和更新版本，您可以從命令列和 Visual Studio 中建置時啟用程式碼樣式分析。 (不過，基於效能考慮， 少數程式碼樣式規則 仍僅適用于 Visual Studio IDE.)
請遵循下列步驟，在建置時啟用程式碼樣式分析：
將 MSBuild 屬性 EnforceCodeStyleInBuild 設定為
true。在 .editorconfig 檔案中， 將 您想要在組建上執行的每個 「IDE」 程式碼樣式規則設定為警告或錯誤。 例如：
[*.{cs,vb}] # IDE0040: Accessibility modifiers required (escalated to a build warning) dotnet_diagnostic.IDE0040.severity = 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
注意
程式碼樣式分析功能是實驗性的，而且可能會在 .NET 5 和 .NET 6 版本之間變更。
隱藏警告
隱藏規則違規的其中一種方式，是在 EditorConfig 檔案中將該規則識別碼的嚴重性選項設定為 none 。 例如：
dotnet_diagnostic.CA1822.severity = none
如需隱藏警告的詳細資訊和其他方式，請參閱 如何隱藏程式碼分析警告。
以 GitHub Action 身分執行程式碼分析
dotnet/code-analysis GitHub Action 可讓您以離線模式執行 .NET 程式碼分析器，作為持續整合 (CI) 的一部分。 如需詳細資訊，請參閱 .NET 程式碼分析 GitHub Action。
第三方分析器
除了官方 .NET 分析器之外，您也可以安裝協力廠商分析器，例如 StyleCop、 Roslynator、 XUnit Analyzers和 Sonar Analyzer。