使用Visual Studio的擴充套件StyleCop撰寫風格一致的C#程式碼
主題 |
使用Visual Studio的擴充套件StyleCop撰寫風格一致的C#程式碼 |
文章簡介 |
介紹如何使用StyleCop自動檢查C#程式碼的撰寫風格，從StyleCop安裝、規則調整到自訂規則。透過工具讓團隊開發出來的程式碼風格統一。 |
作者 |
廖汶彬 |
版本 |
1.0 |
產出日期 |
2016.08.25 |
1. 目的
每個開發團隊裡都會有不同的Coding標準，來確保程式碼具有基本的可讀性與可維護性。但面對大量的程式碼，人工審核並不符合經濟效益不僅需要花費大量時間也可能會有遺漏，因此利用StyleCop來幫助我們做程式碼的檢查，快速又正確。 透過設定讓每次程式在編譯時，也同時檢查程式碼符合團隊定義的Coding標準。幫助團隊進行Code Review的工作。
2. StyleCop介紹
是Visual Studio擴充套件，是一個程式碼規範檢查工具，可掃描C#程式碼是否符合規範，例如命名規則、是否有註解…等等。可依據需要調整檢查的規則，甚至可以增加自行定義的規則。透過設定可以讓Visual Studio每次程式在編譯時，也同時檢查程式碼是否符合規範。
3. StyleCop安裝/簡易使用說明
開啟Visual Studio工具擴充功能和更新
選擇「線上」分類並搜尋「StyleCop」安裝「Visual StyleCop」套件
安裝完成重新啟動Visual Studio就可開始使用StyleCop進行程式碼檢查
執行Run StyleCop後，未通過規則的項目預設會出現在「錯誤清單」視窗中的「警告」分類
在項目上按右鍵選擇「顯示錯誤說明」會以網頁開啟該項目規則說明。
連點兩下會於Visual Studio編輯區域開啟程式碼並且遊標會移至該行。
依據規則說明調整程式碼。
規則代碼詳細說明網頁
透過下列網址可快速查閱規則代碼詳細說明
https://github.com/Visual-Stylecop/Visual-StyleCop/wiki/SA1600
修改網址最後標示為紅色的規則代碼進行瀏覽即可查閱規則代碼詳細說明
4. 制定符合開發團隊的StyleCop規則
StyleCop定義了非常多C#程式碼規範，預設所有規範都是開啟需要檢查，我們如何針對開發團隊的需要來進行調整。我的做法是拿以前開發的專案來做StyleCop掃描再逐條檢視不符合規則的項目，來決定是否需要保留該項規則，把不需保留的規則項目取消。全部調整完畢後可將設定檔案保存妥當，以利後續專案可以套用此設定不需再重新設定。並且後續專案若有調整都應該持續更新此設定檔案。
開啟「方案總管」在欲修改設定的專案上按下右鍵開啟StyleCop Settings。
StyleCop相關設定畫面如下，可利用視窗右上方的Find快速尋找特定規則進行開啟與關閉的設定，請注意需要輸入完整的規則代碼(例如SA1600)即可快速找到該項規則。
設定檔案位置預設在專案根目錄(與Web.Config或App.Config同一層)下。
設定檔案的檔名為「Settings.StyleCop」。
預設所有規範都需要檢查的狀態下不會有設定檔案存在，當調整過設定後會自動產生設定檔案並放置於預設的目錄。
新專案需要套用此設定時，只需要將先前留存的Settings.StyleCop檔案複製到新專案的根目錄(與Web.Config或App.Config同一層)下即可套用。
5. 建立自訂規則
因為習慣private field命名為底線+小寫字母開頭
(例：private string _document;)
預設的StyleCop的private field規則為小寫字母開頭
以下範例為新增一個private field命名需為底線+小寫字母開頭的規則
建立類別庫專案(目標Framework：.Net Framework 4.6.1)
將「StyleCop.dll」與「StyleCop.CSharp.dll」加入參考(在安裝的StyleCop資料夾中可以找到，如果是Visual Studio擴充套件，先找到安裝Visual Studio資料夾，進入\Common7\IDE\Extensions，裡面會有已安裝的套件但套件的資料夾會是隨機產生的文字，可以找到資料夾內有StyleCop.dll與StyleCop.CSharp.dll)
建立自訂規則類別
繼承「SourceAnalyzer」類別
掛載SourceAnalyzer(typeof(CsParser))屬性
覆寫AnalyzeDocument方法，撰寫規則檢查的程式碼
加入XML規則定義檔案
檔案名稱應與上一步驟的類別名稱相同並且建置動作需改為「內嵌資源」
XML設定內容
完成後建置專案取得dll檔，將dll檔案複製到StyleCop套件安裝資料夾內
完成後重新啟動Visual Studio並開啟專案
進入StyleCop Settings即可找到自訂規則的項目
表示此規則已可是否要套用在StyleCop中，可以設定是否開啟
6. 如何讓專案在編譯(執行)也進行StyleCop Scan，並且讓不符合StyleCop規則項目視為錯誤
至CodePlex下載StyleCop檔案(https://stylecop.codeplex.com/ )並安裝
此安裝是為了提供給MSBuild，在專案建置執行時使用
開啟安裝的資料夾(預設為C:\Program Files (x86)\StyleCop 4.7\)
若有自訂規則的dll也複製到此資料夾內
使用Visual Studio開啟方案
於方案總管視窗，在專案上按下滑鼠右鍵，選擇「卸載專案」
再於專案上按下滑鼠右鍵
選擇「編輯[專案名稱]」
在設定檔中增加下列設定
<StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings>
讓未通過規則的項目出現在「錯誤清單」視窗中的「錯誤」分類
加入位置參考下列圖片
在設定檔中<Project></Project>增加下列設定
<Import Project="$(ProgramFiles)\MSBuild\StyleCop\v4.7\StyleCop.targets" />
指定專案在建置(執行)時會
存檔完成後再重新載入專案即完成設定
此時執行或建置專案，若有未通過StyleCop規則的項目會出現在「錯誤清單」視窗中的「錯誤」分類，輔助我們確保程式碼能夠符合StyleCop規則
7. 如何忽略特定錯誤訊息
在專案開發的過程中，很可能會遇到很特別的狀況，專案需要套用某個規則，但在專案中因為某種需要，導致程式碼會違反此規則，所以需要忽略此錯誤訊息。
開啟要忽略的規則代碼詳細說明，網址如下：
https://github.com/Visual-Stylecop/Visual-StyleCop/wiki/SA1600
修改網址最後標示為紅色的規則代碼進行瀏覽即可查閱規則代碼詳細說明
說明中會有一個區塊是告訴你如何忽略此錯誤訊息
只要將該行程式碼貼到產生錯誤訊息的程式碼上方，即可忽略此錯誤/警告
8. 參考資料
昏睡領域 - [Tool] 使用 StyleCop 驗證命名規則
