.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 9 中的錯誤或警告。 其他規則會啟用為建議。
| 診斷識別碼 | 類別 | 嚴重性 | 新增的版本 | 描述 |
|---|---|---|---|---|
| CA1416 | 互通性 | 警告 | .NET 5 | 驗證平台相容性 |
| CA1417 | 互通性 | 警告 | .NET 5 | 請勿對 P/Invokes 的字串參數使用 OutAttribute |
| CA1418 | 互通性 | 警告 | .NET 6 | 請使用有效的平台字串 |
| CA1420 | 互通性 | 警告 | .NET 7 | 在需要執行階段封送處理的功能停用時加以使用，將會導致執行階段例外狀況 |
| CA1422 | 互通性 | 警告 | .NET 7 | 驗證平台相容性 |
| CA1831 | 效能 | 警告 | .NET 5 | 在適用情況下，請使用 AsSpan 作為字串，不要使用範圍型索引子 |
| CA1856 | 效能 | 錯誤 | .NET 8 | ConstantExpected 屬性的使用方式不正確 |
| CA1857 | 效能 | 警告 | .NET 8 | 預期參數為常數 |
| CA2013 | 可靠性 | 警告 | .NET 5 | 請勿將 ReferenceEquals 與實值型別搭配使用 |
| CA2014 | 可靠性 | 警告 | .NET 5 | 請勿在迴圈中使用 stackalloc |
| CA2015 | 可靠性 | 警告 | .NET 5 | 請勿為衍生自 MemoryManager<T> 的型別定義完成項 |
| CA2017 | 可靠性 | 警告 | .NET 6 | 參數計數不符 |
| CA2018 | 可靠性 | 警告 | .NET 6 | Buffer.BlockCopy 的引數 count 應指定要複製的位元組數目 |
| CA2021 | 可靠性 | 警告 | .NET 8 | 請勿使用不相容的型別呼叫 Enumerable.Cast<T> 或 Enumerable.OfType<T> |
| CA2022 | 可靠性 | 警告 | .NET 9 | 避免使用 不切實際讀取 Stream.Read |
| CA2200 | 使用方式 | 警告 | .NET 5 | 必須重新擲回以保存堆疊詳細資料 |
| CA2247 | 使用方式 | 警告 | .NET 5 | 傳至 TaskCompletionSource 建構函式的引數應為 TaskCreationOptions 列舉而非 TaskContinuationOptions |
| CA2252 | 使用方式 | 錯誤 | .NET 6 | 選擇加入預覽功能 |
| CA2255 | 使用方式 | 警告 | .NET 6 | ModuleInitializer 屬性不應該用於程式庫中 |
| CA2256 | 使用方式 | 警告 | .NET 6 | 在父介面中宣告的所有成員，在 DynamicInterfaceCastableImplementation 屬性介面中都必須有實作 |
| CA2257 | 使用方式 | 警告 | .NET 6 | 在具有 DynamicInterfaceCastableImplementationAttribute 的介面上定義的成員應為 static |
| CA2258 | 使用方式 | 警告 | .NET 6 | 不支援在 Visual Basic 中提供 DynamicInterfaceCastableImplementation 介面 |
| CA2259 | 使用方式 | 警告 | .NET 7 | ThreadStatic 只會影響靜態欄位 |
| CA2260 | 使用方式 | 警告 | .NET 7 | 使用正確的型別參數 |
| CA2261 | 使用方式 | 警告 | .NET 8 | 請勿使用 ConfigureAwaitOptions.SuppressThrowing 搭配 Task<TResult> |
| CA2264 | 使用方式 | 警告 | .NET 9 | 請勿將不可為 Null 的值傳遞至 ArgumentNullException.ThrowIfNull |
| CA2265 | 使用方式 | 警告 | .NET 9 | 不要與 或比較Span<T> nulldefault |
您可以變更這些規則的嚴重性以停用規則，或將其提升為錯誤。 您也可以啟用更多規則。
啟用其他規則
分析模式是指未啟用任何規則、啟用了部分或所有規則的預先定義程式碼分析組態。 在預設分析模式 (Default) 中，只有少數規則會啟用為建置警告。 您可以設定專案檔中的 <AnalysisMode> 屬性，以變更專案的分析模式。 允許的值包括：
| 值 | Description |
|---|---|
None |
所有規則都會停用。 您可以選擇加入 個別規則來啟用這些規則。 |
Default |
預設模式，其中某些規則會啟用為建置警告，而某些規則會啟用為 Visual Studio IDE 建議，而其餘規則會停用。 |
Minimum |
比 Default 模式更積極的模式。 強烈建議進行建置強制執行的某些建議會啟用為建置警告。 若要查看其中包含哪些規則，請檢查 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig 檔案。 |
Recommended |
比 Minimum 模式更積極的模式，其中會將更多規則啟用為建置警告。 若要查看其中包含哪些規則，請檢查 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig 檔案。 |
All |
所有規則都會啟用為建置警告*。 您可以選擇退出個別規則來停用這些規則。 * 如果將 AnalysisMode 設定為 All，或將 AnalysisLevel 設定為 latest-all，以下規則將不會啟用：CA1017、CA1045、CA1005、CA1014、CA1060、CA1021 和程式碼度量分析器規則 (CA1501、CA1502、CA1505、CA1506 和 CA1509)。 這些舊版規則可能會在未來版本中淘汰。 不過，您仍然可以使用 dotnet_diagnostic.CAxxxx.severity = <severity> 項目來個別啟用這些規則。 |
您也可以省略 <AnalysisMode> 屬性的 <AnalysisLevel> 複合值。 例如，下列值會為最新版本啟用建議的規則集：<AnalysisLevel>latest-Recommended</AnalysisLevel>。 如需詳細資訊，請參閱AnalysisLevel。
若要尋找每個可用規則的預設嚴重性，以及規則是否在 Default 分析模式中啟用，請參閱規則的完整清單。
將警告視為錯誤
如果您在建置專案時使用 -warnaserror 旗標，則所有程式碼分析警告也都會被視為錯誤。 在使用 -warnaserror 時，若不想讓程式碼品質警告 (CAxxxx) 被視為錯誤，您可以在專案檔中將 CodeAnalysisTreatWarningsAsErrors MSBuild 屬性設定為 false。
<PropertyGroup>
<CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>
您仍然會看到程式碼分析警告，但這並不會中斷您的建置。
最新的更新
根據預設，在升級至較新版的 .NET SDK 時，您將取得最新的程式碼分析規則和預設規則嚴重性。 例如，如果您不想要此行為，例如，您想要確保不會啟用或停用任何新規則，可以使用下列其中一種方式加以覆寫：
將
AnalysisLevelMSBuild 屬性設定為特定值，將警告鎖定於該規則集。 當您升級至較新的 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。)
請依照下列步驟，在建置時啟用程式碼樣式分析：
將 MSBuild 屬性 EnforceCodeStyleInBuild 設定為
true。在 .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。
