好代码是管出来的——.Net中的代码规范工具及使用
上一篇文章好代碼是管出來的——C#的代碼規(guī)范介紹了編碼標準中一些常用的工具，本篇就具體來介紹如何使用它們來完成代碼管理。
本文主要內(nèi)容有：
Roslyn簡介
開發(fā)基于Roslyn的代碼分析器
常用的基于Roslyn的代碼分析器
在.Net Framework項目中使用代碼分析器
安裝StyleCop Analyser
設(shè)置規(guī)則
將自定義的規(guī)則使用到整個解決方案
修復(fù)代碼
使用StyleCop.Json
在.Net Core/.Net Standard項目中使用代碼分析器
跨IDE的代碼規(guī)范解決方案
在VS2017中使用EditorConfig
在VS Code中使用代碼規(guī)范工具
代碼重構(gòu)&CodeMaid
小結(jié)
Roslyn簡介
Roslyn是一個開源的C#、VB編譯器，它提供了豐富的代碼分析API，第三方應(yīng)用可以基于這些API來開發(fā)自己的代碼分析工具。Roslyn應(yīng)用在VS2015及以上版本。
開發(fā)基于Roslyn的代碼分析器
Roslyn提供了相關(guān)的SDK，可以通過SDK來開發(fā)自己的代碼分析器：
1. 首先需要安裝.Net Compiler Platform SDK：
VS2017 15.5之前的版本可以通過下面連接下載并安裝：
https://marketplace.visualstudio.com/items?itemName=VisualStudioProductTeam.NETCompilerPlatformSDK
VS2017 15.5之后的版本可以通過Visual Studio Installer進行安裝：
2. 創(chuàng)建一個Analyzer with Code Fix的項目：
3. 分析器代碼簡介：
代碼結(jié)構(gòu)：
創(chuàng)建的項目中一共有三個子項目，分別是分析器、分析器測試項目以及vsix安裝包項目如下圖所示：
其中分析器項目中包含了分析器(Analyzer1Analyzer)、代碼修復(fù)器(Analyzer1CodeFixProvider)和相關(guān)的資源(Resources.resx)。
分析器(Analyzer1Analyzer)：
分析器代碼的核心內(nèi)容是注冊一個命名符號處理器(用于處理類名、接口名等)，處理器的工作是判斷分析的符合(名稱)中是否包含小寫字符，如果包含那么給出診斷信息(診斷信息定義包含在資源文件中)。
代碼修復(fù)器：
將小寫字符轉(zhuǎn)換為大寫：
代碼調(diào)試：
將vsix項目設(shè)為啟動項目，就可以對分析器進行調(diào)試，調(diào)試時VS會在沙盤中啟動一個新的VS實例，通過這個VS創(chuàng)建一個項目，編寫代碼時即可看到分析器給出的診斷結(jié)果和代碼修復(fù)：
診斷信息：
修復(fù)結(jié)果：
查看語法樹：
常用的基于Roslyn的代碼分析器
Microsoft.CodeAnalysis.FxCopAnalyzers：
FxCop是.Net Framework中用來分析托管代碼的應(yīng)用程序，它主要關(guān)注的代碼的設(shè)計、國際化、可維護性、性能和安全性等方面，并按照這些類別定義了一個規(guī)則集： 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本身就是一個用于規(guī)范代碼格式的工具，所以它的規(guī)則也是面向代碼格式的，如注釋、布局、命名、排序、可維護性、可讀性等，StyleCop的規(guī)則集參考：https://github.com/DotNetAnalyzers/StyleCopAnalyzers/tree/master/documentation
StyleCop.Analyzers的項目主頁：https://github.com/DotNetAnalyzers/StyleCopAnalyzers
Codecracker.CSharp:
Codecracker.CSharp也是以個開源的代碼分析器，它的規(guī)則主要是設(shè)計、命名、性能、代碼風(fēng)格、代碼使用以及重構(gòu)，具體參見：http://code-cracker.github.io/diagnostics.html
項目主頁：https://github.com/code-cracker/code-cracker
注：Codecracker.CSharp可以通過安裝VS拓展工具的方式實現(xiàn)代碼分析：https://marketplace.visualstudio.com/items?itemName=GiovanniBassi-MVP.CodeCrackerforC，其它大部分Roslyn分析器需要安裝Nuget包。
SonarAnalyzer.CSharp:
SonarAnalyzer.CSharp是一個非常強大的代碼分析器，它現(xiàn)階段一共有343條規(guī)范并且主要是面向了代碼的使用，包含了缺陷檢測、性能、約定、錯誤處理、事件、異步、測試等等多類規(guī)則，規(guī)則參見：https://rules.sonarsource.com/csharp
另外SonarAnalyzer還有針對其它語言的分析器，并且還保持持續(xù)更新，項目主頁：https://www.sonarsource.com/products/codeanalyzers/sonarcsharp.html
在.Net Framework項目中使用代碼分析器
本文使用StyleCop.Analyzers為例，對項目添加代碼分析器。
安裝StyleCop Analyzer
在VS中使用Roslyn的代碼分析器時，其中一種方法就是通過Nuget包的方式在每一個項目中添加相應(yīng)的分析器，下面就以StyleCop Analyzer為例進行介紹：
通過包管理器安裝StyleCop.Analyzers：
當完成安裝后分析器就回對開打的代碼文件進行分析，下圖是StyleCop Analyzer對默認文件的分析結(jié)果：
同時在項目的References/Analyzers下能看到剛安裝的分析器：
設(shè)置規(guī)則
每一個分析器都有自己的規(guī)則集，但不是每一項規(guī)則都適合自己或團隊，所以需要對相應(yīng)的規(guī)則集的嚴重程度，嚴重程度分別有：None、Hidden、Info、Warning、Error，其中None是忽略規(guī)則不檢測，Hidden是檢測但隱藏錯誤。
在VS中對.Net Framework項目的規(guī)則設(shè)置只需要在Analyzers的右鍵菜單中選擇“Open Active Rule Set”即可：
然后就會打開一個ruleset文件的編輯窗口，窗口中包含了已生效的規(guī)則集合：
注：除StyleCop Analyzers外，其它是VS中內(nèi)置的規(guī)則集(最小需求規(guī)則集)，VS內(nèi)置規(guī)則集信息可以選中其中一條規(guī)則，然后在屬性窗口中查看(包括規(guī)則集描述、名稱、資源文件、程序集所在路徑等等)：
通過ruleset編輯窗口可以簡單的通過勾選、設(shè)置嚴重程度來編輯規(guī)則，當修改完成保存時，會根據(jù)項目名稱創(chuàng)建一個ruleset文件：
修改規(guī)則嚴重程度后原有代碼會出現(xiàn)一下錯誤信息：
同時生成了一個名稱為App.ruleset的規(guī)則集文件：
將自定義的規(guī)則使用到整個解決方案
上面的方式需要對每一個項目都進行獨立配置，不但工作量大，而且容易出錯導(dǎo)致不同項目中規(guī)則集不一致，為了解決這個問題，需要在一個解決方案中共享同一個規(guī)則集文件。
1. 將已編輯好的規(guī)則集文件轉(zhuǎn)移至一個“固定”位置(App.ruleset文件放置在與項目目錄平行的目錄中)：
?
2. 在項目屬性窗口中的，"Code Analysis"選項卡中設(shè)置項目的規(guī)則集，使用放在固定位置的規(guī)則集：
注：需要重復(fù)以上操作，將解決方案內(nèi)所有項目規(guī)則集設(shè)置。
3. 開啟或關(guān)閉全解決方案的代碼分析功能：
一般情況代碼分析工具僅對已打開的代碼文件，如果需要分析解決方案中的所有代碼文件需要在菜單：Tools->Options->Text Editor->C#->Advanced下勾選“Enable full solution analysis”：
?
當啟用全解決方案代碼分析時，在不打開任何代碼文件的情況下會自動對所有代碼進行分析，并給出相應(yīng)結(jié)果：
修復(fù)代碼
當代碼分析器發(fā)現(xiàn)不符合規(guī)則時會把相應(yīng)的信息（包括普通、警告、錯誤3個不同等級）顯示到錯誤列表窗口中，雙擊信息即可到達有問題的代碼處，通過quickly action對代碼進行修復(fù)，下圖是將using語句放到命名空間下的代碼修復(fù)：
注：在修復(fù)代碼時，修復(fù)器提供了3種修復(fù)的范圍，分別是當前文檔、當前項目和解決方案，如果不符合規(guī)則的代碼遍布解決方案中，那么選擇一次修復(fù)解決方案會省下非常多的時間。
修復(fù)結(jié)果：
如果遇到無法修復(fù)、修復(fù)后代碼出錯的情況，可以對錯誤進行壓制(suppress)
在源代碼中壓制：
使用全局壓制文件：
注：壓制菜單只會出現(xiàn)在對應(yīng)代碼行最左邊的快捷活動標簽上：
沒有壓制菜單：
?
有壓制菜單：
使用StyleCop.Json
StyleCop Analyzers除了支持ruleset文件配置規(guī)則外，還支持它自己的StyleCop.Json文件配置，另外StyleCop Analyzers提供的一個自動為代碼添加文件頭的功能(文件頭包含了文件以及修改信息)。
1. 通過SA1633警告，添加一個StyleCop.Json文件：
?
2. 將“build Action”設(shè)置為“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小節(jié)。
在.Net Core/.Net Standard項目中使用代碼分析器
在.Net Core項目中使用代碼分析器與.Net Framework項目中使用方法相似，但有一些不同的地方。
1. 首先同樣需要對解決方案內(nèi)的所有項目安裝分析器：
安裝后，出現(xiàn)的警告信息：
2. 修改規(guī)則集：
注：.Net Core項目沒有“Open Active Rule Set”菜單，剛開始只能對特定分析器的特定規(guī)則設(shè)置嚴重性：
?
與此同時，當前項目生成一個以項目名稱命名的ruleset文件：
雙擊打開該文件時可以使用規(guī)則編輯窗口即可對該規(guī)則集進行修改：
注：目前為止VS對.Net Core項目的代碼分析支持有些細節(jié)尚未完善，本例使用VS17 15.7.3版本進行演示，一些版本相對較老的VS版本可能會出現(xiàn)無法創(chuàng)建ruleset文件(需手動根據(jù)項目名稱創(chuàng)建)：
或者編輯ruleset文件時無法顯示規(guī)則內(nèi)容等情況：
同時在編輯ruleset文件時，需要將Project選擇All，才能看到所有的規(guī)則集。
3. 解決方案共享一個規(guī)則集：
注：VS對于.Net Core類型的項目，在查看其項目屬性時，沒有Code Analysis選項卡，所以如果要共享規(guī)則集，除了先將規(guī)則集移動到一個固定位置外，還需要手動在每一個項目文件中添加下面XML片段：
為項目指定一個相對路徑的規(guī)則集文件。
當配置完規(guī)則集后，其它使用方法與.Net framework中使用方法一致。
跨IDE的代碼規(guī)范解決方案
EditorConfig是一個用于不同編輯器或IDE之間定義、維護代碼一致性的項目，它由一個代碼定義格式文件和一系列的插件組成，在VS2017中微軟引入對EditorConfig的支持。
在VS2017中使用EditorConfig
為了能夠快速的添加、編輯EditorConfig文件，首先可以安裝一個名為EditorConfig Language Service的拓展工具，它不僅可以快速創(chuàng)建editorConfig文件，還可以在編輯時提供智能提示：
創(chuàng)建一個editorConfig文件：
編輯editorConfig文件：
注：修改editorConfig后，需要重啟VS后才會生效，不確定是否由于個別環(huán)境影響。
VS中支持editorConfig標準規(guī)則(除每行最大長度外)、C#分析規(guī)則與.Net分析規(guī)則，標準規(guī)則主要是用于統(tǒng)一代碼布局風(fēng)格，而C#與.Net分析規(guī)則則是充分利用C#與.Net的特性給出的一些最佳實踐。相同的內(nèi)容還可以通過Tools->Options->Text Editor->C#->Code Style中設(shè)置：
下圖是字段需要通過this訪問這一規(guī)則，檢測出的錯誤信息：
在VS Code中使用代碼規(guī)范工具
VS Code是一個輕量級的跨平臺編輯器，使用VS Code開發(fā).Net Core項目是一個非常不錯的選擇，并且隨著時間VS Code對代碼規(guī)范工具的支持也在不斷完善。
使用Roslyn代碼分析器
當一個項目通過VS配置好相應(yīng)的規(guī)則集時，使用VS Code打開項目并進行編譯，如果代碼有未修改的代碼將會出現(xiàn)以下提示信息：
相對于VS的主動分析代碼來說，VS Code是被動的，需要在編譯的時候才能知道有哪些代碼有問題，VS Code中對C#開發(fā)是由C#組件提供支持的：
同時該組件也在關(guān)注實時檢測代碼的功能，更多信息參考：https://github.com/OmniSharp/omnisharp-vscode/issues/43
使用EditorConfig
在VS Code中安裝EditorConfig拓展：
然后就可以在VS中使用EditorConfig規(guī)范代碼格式，但要注意的是，VS Code中Editor僅支持EditorConfig的標準規(guī)則。
CodeMaid&代碼重構(gòu)
CodeMaid是一個用于清理、簡化代碼的VS拓展工具，使用CodeMaid可以對代碼風(fēng)格進行設(shè)定(包括空行、空格、訪問器、文件頭，甚至還支持StyleCop的SA1504和SA1502規(guī)則)，最重要的是CodeMaid可以在保存代碼時自動格式化代碼：
? CodeMaid的配置(部分)：
代碼保存前：
代碼保存后：
CodeMaid除了可以對代碼風(fēng)格進行自動格式化以外，還對代碼的重構(gòu)提供了一些有用的功能，如對代碼內(nèi)容根據(jù)類型(如字段、方法等)進行排序(自動或手動拖拽)。另外還對代碼進行了圈復(fù)雜度(參考：https://baike.baidu.com/item/%E5%9C%88%E5%A4%8D%E6%9D%82%E5%BA%A6)分析，當圈復(fù)雜度越高是，表示代碼越難維護。
?
注：圈復(fù)雜度關(guān)注于代碼的可測試性和維護性，與空間/時間復(fù)雜度關(guān)注性能的復(fù)雜度不同。
小結(jié)
本文主要介紹了.Net中常用的代碼規(guī)范工具，分別是基于Roslyn的代碼分析器、基于VS和EditorConfig的代碼規(guī)范工具以及Code Maid一類的VS拓展工具。
其中最強大的工具是基于Roslyn的代碼分析器，這些分析器除了處理代碼風(fēng)格上的規(guī)范還有處理程序性能、安全性等方面的規(guī)范，同時如果代碼被檢測出錯誤時，代碼是無法編譯成功的，唯一的缺點是每個項目都要安裝相應(yīng)的代碼分析器(注：有一些分析器可以通過VS拓展安裝，僅需要安裝一次就可以應(yīng)用到所有項目)，但不管是VS還是VS Code都可以使用Roslyn的代碼分析器。
EditorConfig是一個輕量級代碼規(guī)范工具它除了代碼布局規(guī)則外還兼顧了語言本身的一些特性，如果只是對代碼有簡單風(fēng)格要求，并且使用VS作為開發(fā)工具，那么EditorConfig是一項非常好的選擇。
而CodeMaid是一個不同于前兩者的工具，它更直接一些，可以在保存時就應(yīng)用相應(yīng)的規(guī)則。
合理的使用代碼規(guī)范工具可以大大的提高代碼質(zhì)量并提高開發(fā)效率。?
參考：
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
相關(guān)文章：
好代碼是管出來的——使用Git來管理源代碼
好代碼是管出來的——Git的分支工作流與Pull Request
好代碼是管出來的——使用GitHub
好代碼是管出來的——C#的代碼規(guī)范
原文地址：https://www.cnblogs.com/selimsong/p/9209254.html
.NET社區(qū)新聞，深度好文，歡迎訪問公眾號文章匯總 http://www.csharpkit.com
總結(jié)
以上是生活随笔為你收集整理的好代码是管出来的——.Net中的代码规范工具及使用的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： ASP.NET Core 2.1 : 十
- 下一篇： asp.net ajax控件工具集 Au