.Net Core API

.NetCore 使用StyleCop.Analyzers管理程式碼

【Jimmy Lin】林昱成 (昕力 DTD) 2023/07/31 14:47:03
1867

前言

    Visual Studio 已經提供 .NET Compiler Platform (Roslyn) Analyzers 會檢查 C# 或 Visual Basic 程式碼的樣式、品質、可維護性、設計和其他問題。 此檢查或分析會在所有開啟的檔案的設計階段進行,但因微軟預定的規則比較屬於執行面居多,因此才有第三方分析器產生,為原分析器進行規則擴充,本篇將使用StyleCop.Analyzers套件進行原碼分析。

 

StyleCop.Analyzers 撰寫風格及規範

    StyleCop.Analyzers是一套第三方程式風格撰寫分析器,可以用來分析developer開發程式時透過規則來統一控管程式撰寫風格並使用九種分類規則來進行分析,例如特殊、間距、可讀性、訂購、命名、可維護性、佈局、文檔、替代。若於C# 撰寫的Code與任一分類規則內之項目符合時,將呈現違反規則代碼之警告或提醒字樣,藉此提高專案開發可讀性

九種分類規則說明

  1. 特殊規則:定義特殊功能,如配置錯誤等…。
  2. 間距規則:定義強制代碼中的關鍵字和符號周圍間距,如分號必須正確間隔等…。
  3. 可讀性規則:定義代碼格式與可讀性,如查詢子句等…。
  4. 訂購規則:定義代碼內容標準排序,如使用指令必續正確放置等…。
  5. 命名規則:定義成員、類型即變數命名方式,如元素必須大寫字母開頭等…。
  6. 可維護性規則:定義撰寫代碼可維護性,如代碼內出現部必要的括號等…。
  7. 佈局規則:定義代碼佈局及行間距,如大括號不得省略等…。
  8. 文檔規則:定義代碼內榮及格式,如代碼必須記錄等…。
  9. 替代規則:定義StyleCop非標準擴充套件規則與原有的標準規則有所差異,可能會引起衝突,讓 StyleCop 檢查出現錯誤,如定義靜態屬性名稱出現_底線等…。

 

相關分類細項規則可參考套件官方GitHub文件

以下讓我們來實作如何導入及使用此套件

建立專案及類別庫

安裝StyleCop.Analyzers

 1. 於專案->管理方案的NuGet套件->瀏覽->輸入StyleCop.Analyzers->查詢。
 2. 勾選安裝專案與類別庫並安裝目前最穩定版1.1.118版。

主專案即出現相關綠色小蚯蚓提醒

類別庫即出現相關綠色小蚯蚓提醒

 

有綠色蚯蚓呈現表示已經套用套件內的撰寫規範。

EditorConfig

若多個專案或類別想要使用一套StyleCop規則時,可建立新增EditorConfig 檔案來控管規則檔
方案總管->加入->新增項目->輸入.editorconfig

建立成功後會出現空白畫面

此時重新建置專案,將該檔案關閉,重新再打開即可出現內容,如使用Visual Studio 2019 16.5 版含以上版本開啟 EditorConfig,則會透過IDE方式呈現,可透過介面方式調整StyleCop.Analyzers各項規則嚴重性(已停用、建議、警告、錯誤)。

※若使用Visual Studio Code 也可進行編輯,詳情可參考Code-style rule options

目前案例是使用Visual Studio 2022版本, 從Visual Studio 2019 16.5 版開始,規則集檔案已被取代,大部分適用于分析器規則的 Visual Studio 工具嚴重性設定都會更新,以在 EditorConfig 檔案上運作
另外要注意 EditorConfig的檔案要放在根目錄,如果其他Class內已存在EditorConfig則為以最內層為主,外層就會失效無法達到全域控制的效果

 

開發最常使用的規則

SA1000
原因:C# 關鍵字周圍的間距不正確;以下 C#關鍵字後應始終跟一個空格:and, await, case, catch, fixed, for, foreach, from, group, if, in, is, into, join, let, lock, not, orderby, or, out, ref, return, select, switch, using, var, 。wherewhileyield

 
 留言

 

以下關鍵字後面不應跟任何空格:checked, default, nameof, sizeof, typeof, unchecked。

和關鍵字new後面stackalloc應始終跟一個空格,但以下情況除外:

  • or new關鍵字stackalloc用於創建新的隱式類型數組。在這種情況下,關鍵字和起始數組括號之間不應有空格。
  • 該 new關鍵字是隱式對象創建(目標類型的 new)的一部分。在這種情況下,關鍵字和左括號之間不應有空格。
  • 關鍵字new是泛型類型約束的一部分。new 在這種情況下,關鍵字和左括號之間不應有空格。

例如:

 

於此案例的if 關鍵字右邊新增空白即可解除違規,例如:

 

SA1001
原因:C# 代碼文件中,逗號周圍的間距不正確。例如:

將宣告方法中的傳入間隔參數逗號後方新增空白即可解除違規,例如:

【Jimmy Lin】林昱成 (昕力 DTD)