.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 版本為目標的專案上啟用程式碼分析。 您也可以將 設定 EnableNETAnalyzersfalse 來停用專案的程式碼分析。

提示

如果您使用 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 屬性設定 CodeAnalysisTreatWarningsAsErrorsfalse

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

您仍然會看到任何程式碼分析警告,但不會中斷您的組建。

最新的更新

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

  • AnalysisLevel MSBuild 屬性設定為特定值,以鎖定該集合的警告。 當您升級至較新的 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.)

請遵循下列步驟,在建置時啟用程式碼樣式分析:

  1. 將 MSBuild 屬性 EnforceCodeStyleInBuild 設定為 true

  2. .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 分析器之外,您也可以安裝協力廠商分析器,例如 StyleCopRoslynatorXUnit AnalyzersSonar Analyzer

另請參閱