Net中的代碼規範工具及使用
Net中的代碼規範工具及使用
https://www.cnblogs.com/selimsong/p/9209254.html
上一篇文章介紹了編碼標準中一些常用的工具，本篇就具體來介紹如何使用它們來完成代碼管理。
本文主要內容有：
Roslyn簡介
開發基於Roslyn的代碼分析器
常用的基於Roslyn的代碼分析器
在.Net Framework項目中使用代碼分析器
安裝StyleCop Analyser
設置規則
將自定義的規則使用到整個解決方案
修復代碼
使用StyleCop.Json
在.Net Core/.Net Standard項目中使用代碼分析器
跨IDE的代碼規範解決方案
在VS2017中使用EditorConfig
代碼重構&CodeMaid
小結
Roslyn簡介
Roslyn是一個開源的C#、VB編譯器，它提供了豐富的代碼分析API，第三方應用可以基於這些API來開發自己的代碼分析工具。Roslyn應用在VS2015及以上版本。
開發基於Roslyn的代碼分析器
Roslyn提供了相關的SDK，可以通過SDK來開發自己的代碼分析器：
1. 首先需要安裝.Net Compiler Platform SDK：
VS2017 15.5之前的版本可以通過下面連接下載並安裝：
https://marketplace.visualstudio.com/items?itemName=VisualStudioProductTeam.NETCompilerPlatformSDK
2. 創建一個Analyzer with Code Fix的項目：
3. 分析器代碼簡介：
代碼結構：
創建的項目中一共有三個子項目，分別是分析器、分析器測試項目以及vsix安裝包項目如下圖所示：
其中分析器項目中包含了分析器(Analyzer1Analyzer)、代碼修復器(Analyzer1CodeFixProvider)和相關的資源(Resources.resx)。
分析器(Analyzer1Analyzer)：
分析器代碼的核心內容是註冊一個命名符號處理器(用於處理類名、接口名等)，處理器的工作是判斷分析的符合(名稱)中是否包含小寫字符，如果包含那麽給出診斷信息(診斷信息定義包含在資源文件中)。
代碼修復器：
將小寫字符轉換為大寫：
代碼調試：
將vsix項目設為啟動項目，就可以對分析器進行調試，調試時VS會在沙盤中啟動一個新的VS實例，通過這個VS創建一個項目，編寫代碼時即可看到分析器給出的診斷結果和代碼修復：
診斷信息：
修復結果：
查看語法樹：
常用的基於Roslyn的代碼分析器
Microsoft.CodeAnalysis.FxCopAnalyzers：
FxCop是.Net Framework中用來分析托管代碼的應用程序，它主要關註的代碼的設計、國際化、可維護性、性能和安全性等方面，並按照這些類別定義了一個規則集： https://docs.microsoft.com/en-us/visualstudio/code-quality/code-analysis-for-managed-code-warnings
FxCopAnalyzers安裝： https://www.nuget.org/packages/Microsoft.CodeAnalysis.FxCopAnalyzers
StyleCop.Analyzers
StyleCop本身就是一個用於規範代碼格式的工具，所以它的規則也是面向代碼格式的，如註釋、布局、命名、排序、可維護性、可讀性等，StyleCop的規則集參考：https://github.com/DotNetAnalyzers/StyleCopAnalyzers/tree/master/documentation
StyleCop.Analyzers的項目主頁：https://github.com/DotNetAnalyzers/StyleCopAnalyzers
Codecracker.CSharp:
Codecracker.CSharp也是以個開源的代碼分析器，它的規則主要是設計、命名、性能、代碼風格、代碼使用以及重構，具體參見：http://code-cracker.github.io/diagnostics.html
項目主頁：https://github.com/code-cracker/code-cracker
註：Codecracker.CSharp可以通過安裝VS拓展工具的方式實現代碼分析：https://marketplace.visualstudio.com/items?itemName=GiovanniBassi-MVP.CodeCrackerforC，其它大部分Roslyn分析器需要安裝Nuget包。
SonarAnalyzer.CSharp:
SonarAnalyzer.CSharp是一個非常強大的代碼分析器，它現階段一共有343條規範並且主要是面向了代碼的使用，包含了缺陷檢測、性能、約定、錯誤處理、事件、異步、測試等等多類規則，規則參見：https://rules.sonarsource.com/csharp
另外SonarAnalyzer還有針對其它語言的分析器，並且還保持持續更新，項目主頁：https://www.sonarsource.com/products/codeanalyzers/sonarcsharp.html
在.Net Framework項目中使用代碼分析器
本文使用StyleCop.Analyzers為例，對項目添加代碼分析器。
安裝StyleCop Analyzer
在VS中使用Roslyn的代碼分析器時，其中一種方法就是通過Nuget包的方式在每一個項目中添加相應的分析器，下面就以StyleCop Analyzer為例進行介紹：
通過包管理器安裝StyleCop.Analyzers：
當完成安裝後分析器就回對開打的代碼文件進行分析，下圖是StyleCop Analyzer對默認文件的分析結果：
同時在項目的References/Analyzers下能看到剛安裝的分析器：
設置規則
每一個分析器都有自己的規則集，但不是每一項規則都適合自己或團隊，所以需要對相應的規則集的嚴重程度，嚴重程度分別有：None、Hidden、Info、Warning、Error，其中None是忽略規則不檢測，Hidden是檢測但隱藏錯誤。
在VS中對.Net Framework項目的規則設置只需要在Analyzers的右鍵菜單中選擇“Open Active Rule Set”即可：
然後就會打開一個ruleset文件的編輯窗口，窗口中包含了已生效的規則集合：
註：除StyleCop Analyzers外，其它是VS中內置的規則集(最小需求規則集)，VS內置規則集信息可以選中其中一條規則，然後在屬性窗口中查看(包括規則集描述、名稱、資源文件、程序集所在路徑等等)：
通過ruleset編輯窗口可以簡單的通過勾選、設置嚴重程度來編輯規則，當修改完成保存時，會根據項目名稱創建一個ruleset文件：
修改規則嚴重程度後原有代碼會出現一下錯誤信息：
同時生成了一個名稱為App.ruleset的規則集文件：
將自定義的規則使用到整個解決方案
上面的方式需要對每一個項目都進行獨立配置，不但工作量大，而且容易出錯導致不同項目中規則集不一致，為了解決這個問題，需要在一個解決方案中共享同一個規則集文件。
1. 將已編輯好的規則集文件轉移至一個“固定”位置(App.ruleset文件放置在與項目目錄平行的目錄中)：
2. 在項目屬性窗口中的，"Code Analysis"選項卡中設置項目的規則集，使用放在固定位置的規則集：
註：需要重復以上操作，將解決方案內所有項目規則集設置。
3. 開啟或關閉全解決方案的代碼分析功能：
一般情況代碼分析工具僅對已打開的代碼文件，如果需要分析解決方案中的所有代碼文件需要在菜單：Tools->Options->Text Editor->C#->Advanced下勾選“Enable full solution analysis”：
當啟用全解決方案代碼分析時，在不打開任何代碼文件的情況下會自動對所有代碼進行分析，並給出相應結果：
修復代碼
當代碼分析器發現不符合規則時會把相應的信息（包括普通、警告、錯誤3個不同等級）顯示到錯誤列表窗口中，雙擊信息即可到達有問題的代碼處，通過quickly action對代碼進行修復，下圖是將using語句放到命名空間下的代碼修復：
註：在修復代碼時，修復器提供了3種修復的範圍，分別是當前文檔、當前項目和解決方案，如果不符合規則的代碼遍布解決方案中，那麽選擇一次修復解決方案會省下非常多的時間。
修復結果：
如果遇到無法修復、修復後代碼出錯的情況，可以對錯誤進行壓制(suppress)
在源代碼中壓制：
使用全局壓制文件：
註：壓制菜單只會出現在對應代碼行最左邊的快捷活動標簽上：
沒有壓制菜單：
有壓制菜單：
使用StyleCop.Json
StyleCop Analyzers除了支持ruleset文件配置規則外，還支持它自己的StyleCop.Json文件配置，另外StyleCop Analyzers提供的一個自動為代碼添加文件頭的功能(文件頭包含了文件以及修改信息)。
1. 通過SA1633警告，添加一個StyleCop.Json文件：
2. 將“build Action”設置為“AdditionalFiles”(註：.Net Standard或者.Net Core中需要選擇C# analyzer additional file)：
3. 編輯StyleCop.Json:
註：配置文件中的智能提示由"$schema"控制，並且可以在打開文件時通過右鍵菜單重新加載智能提示的schema。
4. 生成文件頭信息：
5. 通過Nuget Package的形式重用ruleset文件和StyleCop.Json，更多信息查看文檔： https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/Configuration.md 的Sharing configuration among solutions小節。
在.Net Core/.Net Standard項目中使用代碼分析器
在.Net Core項目中使用代碼分析器與.Net Framework項目中使用方法相似，但有一些不同的地方。
1. 首先同樣需要對解決方案內的所有項目安裝分析器：
安裝後，出現的警告信息：
2. 修改規則集：
註：.Net Core項目沒有“Open Active Rule Set”菜單，剛開始只能對特定分析器的特定規則設置嚴重性：
與此同時，當前項目生成一個以項目名稱命名的ruleset文件：
雙擊打開該文件時可以使用規則編輯窗口即可對該規則集進行修改：
註：目前為止VS對.Net Core項目的代碼分析支持有些細節尚未完善，本例使用VS17 15.7.3版本進行演示，一些版本相對較老的VS版本可能會出現無法創建ruleset文件(需手動根據項目名稱創建)：
或者編輯ruleset文件時無法顯示規則內容等情況：
同時在編輯ruleset文件時，需要將Project選擇All，才能看到所有的規則集。
3. 解決方案共享一個規則集：
註：VS對於.Net Core類型的項目，在查看其項目屬性時，沒有Code Analysis選項卡，所以如果要共享規則集，除了先將規則集移動到一個固定位置外，還需要手動在每一個項目文件中添加下面XML片段：
復制代碼
復制代碼
為項目指定一個相對路徑的規則集文件。
當配置完規則集後，其它使用方法與.Net framework中使用方法一致。
跨IDE的代碼規範解決方案
EditorConfig是一個用於不同編輯器或IDE之間定義、維護代碼一致性的項目，它由一個代碼定義格式文件和一系列的插件組成，在VS2017中微軟引入對EditorConfig的支持。
在VS2017中使用EditorConfig
為了能夠快速的添加、編輯EditorConfig文件，首先可以安裝一個名為EditorConfig Language Service的拓展工具，它不僅可以快速創建editorConfig文件，還可以在編輯時提供智能提示：
創建一個editorConfig文件：
編輯editorConfig文件：
註：修改editorConfig後，需要重啟VS後才會生效，不確定是否由於個別環境影響。
VS中支持editorConfig標準規則(除每行最大長度外)、C#分析規則與.Net分析規則，標準規則主要是用於統一代碼布局風格，而C#與.Net分析規則則是充分利用C#與.Net的特性給出的一些最佳實踐。相同的內容還可以通過Tools->Options->Text Editor->C#->Code Style中設置：
下圖是字段需要通過this訪問這一規則，檢測出的錯誤信息：
在VS Code中使用代碼規範工具
VS Code是一個輕量級的跨平臺編輯器，使用VS Code開發.Net Core項目是一個非常不錯的選擇，並且隨著時間VS Code對代碼規範工具的支持也在不斷完善。
使用Roslyn代碼分析器
當一個項目通過VS配置好相應的規則集時，使用VS Code打開項目並進行編譯，如果代碼有未修改的代碼將會出現以下提示信息：
相對於VS的主動分析代碼來說，VS Code是被動的，需要在編譯的時候才能知道有哪些代碼有問題，VS Code中對C#開發是由C#組件提供支持的：
同時該組件也在關註實時檢測代碼的功能，更多信息參考：https://github.com/OmniSharp/omnisharp-vscode/issues/43
使用EditorConfig
在VS Code中安裝EditorConfig拓展：
然後就可以在VS中使用EditorConfig規範代碼格式，但要註意的是，VS Code中Editor僅支持EditorConfig的標準規則。
CodeMaid&代碼重構
CodeMaid是一個用於清理、簡化代碼的VS拓展工具，使用CodeMaid可以對代碼風格進行設定(包括空行、空格、訪問器、文件頭，甚至還支持StyleCop的SA1504和SA1502規則)，最重要的是CodeMaid可以在保存代碼時自動格式化代碼：
CodeMaid的配置(部分)：
代碼保存前：
代碼保存後：
CodeMaid除了可以對代碼風格進行自動格式化以外，還對代碼的重構提供了一些有用的功能，如對代碼內容根據類型(如字段、方法等)進行排序(自動或手動拖拽)。另外還對代碼進行了圈復雜度(參考：https://baike.baidu.com/item/%E5%9C%88%E5%A4%8D%E6%9D%82%E5%BA%A6)分析，當圈復雜度越高是，表示代碼越難維護。
註：圈復雜度關註於代碼的可測試性和維護性，與空間/時間復雜度關註性能的復雜度不同。
小結
本文主要介紹了.Net中常用的代碼規範工具，分別是基於Roslyn的代碼分析器、基於VS和EditorConfig的代碼規範工具以及Code Maid一類的VS拓展工具。
其中最強大的工具是基於Roslyn的代碼分析器，這些分析器除了處理代碼風格上的規範還有處理程序性能、安全性等方面的規範，同時如果代碼被檢測出錯誤時，代碼是無法編譯成功的，唯一的缺點是每個項目都要安裝相應的代碼分析器(註：有一些分析器可以通過VS拓展安裝，僅需要安裝一次就可以應用到所有項目)，但不管是VS還是VS Code都可以使用Roslyn的代碼分析器。
EditorConfig是一個輕量級代碼規範工具它除了代碼布局規則外還兼顧了語言本身的一些特性，如果只是對代碼有簡單風格要求，並且使用VS作為開發工具，那麽EditorConfig是一項非常好的選擇。
而CodeMaid是一個不同於前兩者的工具，它更直接一些，可以在保存時就應用相應的規則。
合理的使用代碼規範工具可以大大的提高代碼質量並提高開發效率。
參考：
https://docs.microsoft.com/en-us/visualstudio/code-quality/code-analysis-for-managed-code-warnings
https://docs.microsoft.com/en-us/visualstudio/code-quality/use-roslyn-analyzers
https://codehollow.com/2016/08/use-code-analyzers-csharp-improve-code-quality/
https://github.com/dotnet/roslyn
https://www.c-sharpcorner.com/UploadFile/vendettamit/introducing-stylecop-with-code-analyzer-in-visual-studio-201/
https://github.com/dotnet/roslyn/wiki/Roslyn%20Overview
https://blogs.msdn.microsoft.com/devfish/2017/11/09/rigging-up-roslyn-analyzers-in-net-core/
https://www.guru99.com/cyclomatic-complexity.html
https://docs.microsoft.com/en-us/visualstudio/ide/create-portable-custom-editor-options
https://msdn.microsoft.com/en-us/library/bb429476(v=vs.80).aspx
https://docs.microsoft.com/zh-cn/visualstudio/code-quality/how-to-configure-code-analysis-for-a-managed-code-project
https://msdn.microsoft.com/en-us/library/bb429476(v=vs.80).aspx
https://www.linkedin.com/pulse/stylecop-analyzer-better-code-optimization-arpit-gupta
https://github.com/OmniSharp/omnisharp-vscode/issues/43
本文鏈接：https://www.cnblogs.com/selimsong/p/9209254.html
好代碼是管出來的——淺談.Net Core的代碼管理方法與落地（更新中...）
作者：7m魚
出處：http://www.cnblogs.com/selimsong/
Net中的代碼規範工具及使用