.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 8 中的錯誤或警告。 其他規則會啟用為建議。
診斷識別碼 | 類別 | 嚴重性 | 新增的版本 | 描述 |
---|---|---|---|---|
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> |
您可以變更這些規則的嚴重性以停用規則,或將其提升為錯誤。 您也可以啟用更多規則。
啟用其他規則
分析模式是指未啟用任何規則、啟用了部分或所有規則的預先定義程式碼分析組態。 在預設分析模式 (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> 項目來個別啟用這些規則。 |
從 .NET 6 開始,您可以省略 <AnalysisMode>
以改用複合的 <AnalysisLevel>
屬性值。 例如,下列值會為最新版本啟用建議的規則集:<AnalysisLevel>latest-Recommended</AnalysisLevel>
。 如需詳細資訊,請參閱AnalysisLevel
。
若要尋找每個可用規則的預設嚴重性,以及規則是否在 Default
分析模式中啟用,請參閱規則的完整清單。
將警告視為錯誤
如果您在建置專案時使用 -warnaserror
旗標,則所有程式碼分析警告也都會被視為錯誤。 在使用 -warnaserror
時,若不想讓程式碼品質警告 (CAxxxx) 被視為錯誤,您可以在專案檔中將 CodeAnalysisTreatWarningsAsErrors
MSBuild 屬性設定為 false
。
<PropertyGroup>
<CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>
您仍然會看到程式碼分析警告,但這並不會中斷您的建置。
最新的更新
根據預設,在升級至較新版的 .NET SDK 時,您將取得最新的程式碼分析規則和預設規則嚴重性。 例如,如果您不想要此行為,例如,您想要確保不會啟用或停用任何新規則,可以使用下列其中一種方式加以覆寫:
將
AnalysisLevel
MSBuild 屬性設定為特定值,將警告鎖定於該規則集。 當您升級至較新的 SDK 時,仍會收到這些警告的錯誤修正,但不會啟用任何新的警告,也不會停用任何現有的警告。 例如,若要鎖定於 5.0 版的 .NET SDK 隨附的將規則集,請將下列項目新增至您的專案檔。<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
提示
從 .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。