好代碼是管出來的——.Net中的代碼規範工具及使用

時間 2019-11-08

標籤代碼出來規範工具使用简体版

原文原文鏈接

　　上一篇文章介紹了編碼標準中一些經常使用的工具，本篇就具體來介紹如何使用它們來完成代碼管理。
　　本文主要內容有：html

Roslyn簡介

　　Roslyn是一個開源的C#、VB編譯器，它提供了豐富的代碼分析API，第三方應用能夠基於這些API來開發本身的代碼分析工具。Roslyn應用在VS2015及以上版本。git

開發基於Roslyn的代碼分析器

　　Roslyn提供了相關的SDK，能夠經過SDK來開發本身的代碼分析器：
　　1. 首先須要安裝.Net Compiler Platform SDK：
　　VS2017 15.5以前的版本能夠經過下面鏈接下載並安裝：
　　https://marketplace.visualstudio.com/items?itemName=VisualStudioProductTeam.NETCompilerPlatformSDK
　　VS2017 15.5以後的版本能夠經過Visual Studio Installer進行安裝：github

　　2. 建立一個Analyzer with Code Fix的項目：xcode

　　3. 分析器代碼簡介：安全

代碼結構：

　　建立的項目中一共有三個子項目，分別是分析器、分析器測試項目以及vsix安裝包項目以下圖所示：異步

　　其中分析器項目中包含了分析器(Analyzer1Analyzer)、代碼修復器(Analyzer1CodeFixProvider)和相關的資源(Resources.resx)。編輯器

分析器(Analyzer1Analyzer)：

　　分析器代碼的核心內容是註冊一個命名符號處理器(用於處理類名、接口名等)，處理器的工做是判斷分析的符合(名稱)中是否包含小寫字符，若是包含那麼給出診斷信息(診斷信息定義包含在資源文件中)。ide

代碼修復器：

　　將小寫字符轉換爲大寫：工具

代碼調試：

　　將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片斷：

 <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <CodeAnalysisRuleSet>..\RuleSets\My.ruleset</CodeAnalysisRuleSet>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <CodeAnalysisRuleSet>..\RuleSets\My.ruleset</CodeAnalysisRuleSet>
  </PropertyGroup>

　　爲項目指定一個相對路徑的規則集文件。
　　當配置完規則集後，其它使用方法與.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