如何在 Visual Studio 2017 對 .NET Core 專案啟用分析器功能

在 Visual Studio 2017 裡面，有個好用的「分析器」功能，可以幫助開發人員寫好程式。他的作法是在背景執行一連串的程式碼分析，透過一組規則集 (RuleSet) 對專案中的程式碼進行剖析與檢查，如果有發現任何問題，就會在「錯誤清單」中呈現資訊、警告或錯誤，並且提供部分規則的自動修復功能。不過，在 Visual Studio 2017 對 .NET Core 專案的支援度並沒有太多文件著墨，我花了好多時間才研究出背後的差異之處。我打算透過本篇文章分享如何在 Visual Studio 2017 啟用與設定 .NET Core 專案的程式碼分析器功能。

基本上，目前在 Microsoft Docs 上關於 Visual Studio 2017 分析器的文件，所有的「操作步驟」大多都只適用於 .NET Framework 專案類型。到了 .NET Core 之後，雖然分析器的觀念都完全一樣，但是分析器的設定方式已經有點不一樣，這點真的困擾我一些時間。

以下我列出幾個重要的文件入口頁，先建立一些基本觀念再開始使用還是比較好：

• 開始使用 Roslyn 分析器
• .NET Compiler Platform 分析器的概觀
• 安裝.NET Compiler Platform 分析器

早在十多年前，最知名的 FxCop 套件，就是用來分析 .NET Framework 專案原始碼，自動檢測潛在的程式碼問題。爾後被整併到 Visual Studio 之中，變成內建的程式分析器，雖然 FxCop 這個名詞變得少見，但內部還是一直使用這個名字。

直到 .NET Compiler Platform ("Roslyn") 出現之後，這一切都改變了。因為 Roslyn 將 NET 程式語言的編譯器全部開放原始碼，而且公開許多 C#/VB 程式碼剖析的 APIs，所以 Visual Studio 也開始進一步改用 Roslyn 改寫所有分析器。

簡單來說： 目前 Visual Studio 2017 的分析器已經全數改用 Roslyn 進行程式碼分析。

在 .NET Framework 專案啟用分析器的步驟

在 Visual Studio 2017 建立任何一個 .NET Framework 專案範本，預設就會啟用內建的分析器。預設選取的規則集為 適用於 Managed 程式碼的 Managed 建議規則規則集 (Managed Recommended Rules rule set for managed code)，這些規則的重點在於程式碼中最關鍵的問題，包括潛在的安全性漏洞、應用程式損毀，以及其他重要的邏輯和設計錯誤。

這份 適用於 Managed 程式碼的 Managed 建議規則規則集 文件的翻譯，在 Visual Studio 2017 中操作介面翻譯為 Microsoft 受控建議規則 ，有一點不太一樣。你可以從「專案屬性」的「程式碼分析」頁籤中看見。規則集檔案的路徑為 C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Team Tools\Static Analysis Tools\Rule Sets\MinimumRecommendedRules.ruleset 。

這些規則集都是可以調整的，在 Visual Studio 2017 中完整的規則集文件，可以參考 程式碼分析規則集參考 文件。

在 Visual Studio 2017 的 .NET Framework 專案中開啟規則集，有兩種方法：

1. 從 方案總管 的 任意專案 下，找到 [參考] / [分析器] 按滑鼠右鍵，點擊 [ 開啟使用中的規則集合 ]
2. 從 方案總管 的 任意專案 按滑鼠右鍵，選擇「屬性」，切換到「程式碼分析」頁籤，點擊「開啟」按鈕。

請注意：在 .NET Core 專案中，從 VS2017 的 方案總管 中，會完全找不到可以 開啟程式碼分析器規則集 的功能，從 專案屬性 中也會找不到 程式碼分析 頁籤，這點是有點不便！

最後提醒：透過 程式碼分析規則編輯器 對規則集檔案所做的修改，在 .NET Core 的專案中，完全無法產生效果！

在 .NET Core 專案啟用分析器的步驟

我之前就是一直被 .NET Framework 專案的分析器設定步驟卡住，怎樣設定都無效，甚至設定到有點怒氣 XD

在 Visual Studio 2017 中對 .NET Core 專案設定分析器的完整設定步驟如下：

1. 開啟 NuGet 套件管理員
2. 點擊「瀏覽」頁籤並勾選「包括搶鮮版」
3. 搜尋 fxcopanalyzers 關鍵字，並安裝 Microsoft.CodeAnalysis.FxCopAnalyzers 套件。
   

或直接透過 套件管理器主控台 輸入以下命令：( 2018/09/24: 請記得安裝最新 Beta 版本。 )

Install-Package Microsoft.CodeAnalysis.FxCopAnalyzers -IncludePrerelease

安裝好必要的分析器套件後，接下來就簡單測試一下。

你先隨便建立一個類別檔，並輸入以下內容，然後 [建置] 專案：

using System;
using System.IO;
...
...
public class NoDisposeMethod
{
    FileStream newFile;

    public NoDisposeMethod()
    {
        newFile = new FileStream(@"c:\temp.txt", FileMode.Open);
    }
}

上述程式碼會引發 CA1001：具有可處置欄位的類型應該是可處置的 警告，你可以從 錯誤清單 中發現這些訊息。

啟用完整解決方案分析

Visual Studio 2017 預設只會分析目前開啟過的檔案，如果要預設分析方案中所有專案的所有程式碼，可以參考以下設定：

1. 打開選單 [工具] / [選項] / [文字編輯器] / [C#] / [進階]
2. 勾選【 啟用完整解決方案分析 】( Enable full solution analysis )
3. 啟用之後，必須做一次 建置 動作，分析器才會生效。

如何調整分析器規則集

在 .NET Framework 可以透過建立 *.ruleset 檔案，你可以透過 [ 新增項目 ] 精靈，搜尋 [ 程式碼分析規則集 ] 項目範本，即可建立一個自訂規則集。在 Visual Studio 2017 中有個 程式碼分析規則編輯器 可用，不過這套編輯器完全不適用於 .NET Core 專案，千萬不要透過這套來編輯規則集內容。

在 .NET Core 專案中，調整規則集的方式，已經整合進 方案總管 ，你只要從 [專案] / [相依性] / [分析器] 去挑選適合的規則，直接按滑鼠右鍵，就可以切換該條規則的嚴重性。

只要你第一次切換任何一條規則的嚴重性設定，該專案就會自動建立 規則集設定檔 ( *.ruleset )，並且全自動設定相容於 .NET Framework 的規則集。意思也就是說，只要你的方案中有 .NET Core 專案的存在，你就應該用 .NET Core 的規則集設定方法，而這些自動產生的規則集設定檔，也同時可以套用到 .NET Framework 專案中！

.NET Core 預設專案範本內建的分析器套件

• 主控台應用程式 (.NET Core)& 類別庫 (.NET Core)

  • 這兩個專案範本預設沒有內建任何分析器 (Analyzer)。

  • 如果想要安裝額外的分析器，以下介紹的每個分析器套件，只要用 NuGet 安裝好就能直接使用。

  • 只有在 主控台應用程式 (.NET Core) 與 類別庫 (.NET Core) 專案範本中，才看的見 程式碼分析規則集 (Code Analysis Rule Set) 這個「項目範本」(Item Template)。如果你在 ASP.NET Core Web 應用程式的專案中新增項目時，就會搜尋不到這個項目範本，要特別注意！

• ASP.NET Core Web 應用程式

  • 預設內建 3 個 NuGet 套件 (包含 4 個分析器)
  1. Microsoft.CodeAnalysis.Analyzers
     • 套件說明： 提供使用 .NET Compiler Platform (Roslyn) APIs 的相關導引。
     • 專案位址：https://github.com/dotnet/roslyn-analyzers
     • 更多資訊： Microsoft.CodeAnalysis.Analyzers.md
     • Microsoft.CodeAnalysis.Analyzers
     • Microsoft.CodeAnalysis.CSharp.Analyzers
  2. Microsoft.AspNetCore.Mvc.Analyzers
     • 套件說明： 專門針對 ASP.NET Core MVC 的 C# 分析器。
     • 專案位址：https://github.com/aspnet/Mvc/tree/master/src/Microsoft.AspNetCore.Mvc.Analyzers
     • Microsoft.AspNetCore.Mvc.Analyzers
  3. Microsoft.EntityFrameworkCore.Analyzers
     • 套件說明： 專門針對 Entity Framework Core 提供的 C# 分析器。
     • 專案位址：https://github.com/aspnet/EntityFrameworkCore/tree/release/2.2/src/EFCore.Analyzers
     • Microsoft.EntityFrameworkCore.Analyzers

  

詳細介紹Microsoft.CodeAnalysis.FxCopAnalyzers分析器

這個 Microsoft.CodeAnalysis.FxCopAnalyzers 分析器，原始碼位於 dotnet/roslyn-analyzers 專案。主要的目的在於幫助開發人員更正確的使用 Roslyn 靜態分析的 APIs，我認為一般人不太需要啟用所有的規則集，畢竟不是所有人都需要如此嚴謹的撰寫 C# 程式碼。

要使用 Microsoft.CodeAnalysis.FxCopAnalyzers 可以直接透過 NuGet 安裝 Microsoft.CodeAnalysis.FxCopAnalyzers 即可。

安裝過程除了會安裝 Microsoft.CodeAnalysis.FxCopAnalyzers 之外，也會連同安裝以下 4 個分析器。

1. Microsoft.CodeQuality.Analyzers
   • 套件說明： Provides common code quality guidelines.
   • 更多資訊： Microsoft.CodeQuality.Analyzers.md
2. Microsoft.NetFramework.Analyzers
   • 套件說明： Analyzers for APIs specific to the desktop .NET Framework.
   • 更多資訊： Microsoft.NetFramework.Analyzers.md
3. Microsoft.NetCore.Analyzers
   • 套件資訊： Analyzers for APIs specific to .NET Core.
   • 更多資訊： Microsoft.NetCore.Analyzers.md
4. Text.Analyzers
   • 套件資訊： Contains analyzers for text included in code, such as comments.

安裝之後，會有以下分析器：

相關連結

• Managed 程式碼的程式碼分析警告 - 全中文化的規則集解說！
  • Code Analysis for Managed Code Warnings - 最新版的規則集英文說明文件
• 使用規則集分組程式碼分析規則
• Visual Studio 程式碼分析規則集參考 - Visual Studio | Microsoft Docs
• How to configure Code Analysis in .NET Core
• Rigging up Roslyn Analyzers in .NET Core – DevFish on MSDN …>««(o>…
  • https://github.com/jhealy/RoslynAnalyzerProofs
• Quick Actions, light bulbs, and screwdrivers - Visual Studio | Microsoft Docs
  • 快速動作、燈泡及螺絲起子 - Visual Studio | Microsoft Docs
• 我自訂的 .NET Core 專用規則集檔案： MinimumRecommendedRules.ruleset