自定義 Roslyn 分析器規則

每個 Roslyn 分析器規則或 診斷都有預設嚴重性和隱藏狀態，您可以為您的專案自定義。 本文涵蓋設定分析器嚴重性及抑制分析器違規。

嚴重性層級

您可以在 EditorConfig 檔案 和 燈泡菜單中設定分析器規則的嚴重性。

下表顯示您可以為診斷設定的不同嚴重性選項：

嚴重性 （方案總管）	嚴重性 （EditorConfig 檔案）	構建時行為	編輯器 行為
錯誤	error	違規會出現在 [錯誤清單] 視窗和命令行建置輸出的 [錯誤] 索引標籤中，並導致組建失敗。	有問題的程式碼會被紅色波浪線標示底下，並且在捲動條中以小紅色方塊標示出來。
警告	warning	違規會出現在 [錯誤清單] 視窗和命令行建置輸出的 [警告] 索引標籤中，但不會導致組建失敗。	出現問題的程式代碼會以綠色波浪線標示，而滾動條上則有小綠色方塊。
建議	suggestion	違規會出現在 [錯誤清單] 視窗中的 [訊息] 索引標籤中，但不出現在命令行建置輸出中。	受影響的程式代碼會以灰色波浪線底線顯示，並在滾動條中以小灰色方塊標示。
無訊息	silent	使用者看不見。	使用者看不見，但診斷會回報給 IDE 診斷引擎。
沒有	none	完全壓制。	完全壓制。
預設	default	對應至規則的預設嚴重性。 若要判斷規則的預設值，請檢視其 [屬性] 視窗。	對應至規則的預設嚴重性。

查看規則違規

如果分析器發現任何分析器規則違規，它會在 [ 錯誤清單 ] 視窗和程式代碼編輯器中報告它們。

下列螢幕快照顯示 錯誤清單 視窗中報告的規則違規。 錯誤清單中回報的分析器違規符合規則的 嚴重性層級設定 ：

分析器規則違規也會在程式碼編輯器中，以波浪線顯示在有問題的程式碼底下。 例如，下列螢幕快照顯示三個違規：一個錯誤（紅色波浪線）、一個警告（綠色波浪線），另一個建議（三個灰色點）：

許多診斷都有一或多個相關聯的 代碼修正 ，您可以套用以修正違規。 在燈泡圖示功能表中顯示程式碼修正，以及其他類型的 快速動作。 如需程式代碼修正的詳細資訊，請參閱 常見快速動作。

設定嚴重性層級

您可以使用下列任何方法來設定規則嚴重性：

• EditorConfig
• 燈泡菜單
• 方案總管

靜默與無嚴重性

Silent 默認啟用的嚴重性規則與停用或 None 嚴重性規則不同：

• 如果已為 Silent 嚴重性規則註冊了代碼修正，Visual Studio 會將其作為燈泡提示的程式碼重構動作提供，即使該隱藏的診斷對使用者不可見。 如果嚴重性規則被停用為 None，則不會提供程式碼修正建議。
• 在 EditorConfig 檔案中一次設定多個分析器規則嚴重性的專案可以大量設定Silent嚴重性規則。 None 無法以這種方式設定嚴重性規則。 相反地，它們必須透過設定 每個規則標識碼之 EditorConfig 檔案中嚴重性的項目來設定。

在 EditorConfig 檔案中設定規則嚴重性

Visual Studio 2019 16.3 版和更新版本提供 EditorConfig 檔案。

在EditorConfig檔案中設定規則的嚴重性優先於規則集或方案總管中設定的任何嚴重性。 您可以在 EditorConfig 檔案中 手動 設定嚴重性，或透過出現在違規旁邊的燈泡 自動 設定嚴重性。

在EditorConfig檔案中手動設定規則嚴重性

若要設定規則嚴重性，請遵循下列步驟：

1. 如果您還沒有 EditorConfig 檔案，請將 EditorConfig 檔案新增至您的專案。

2. 在對應的檔案副檔名下，為您想要配置的每個規則項目添加一個條目。

   例如，將 CA1822 的嚴重性級別設置為 error 的輸入條目（適用於 C# 檔案）如下所示：

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. 您可以使用下列語法，為 EditorConfig 檔案中的每個診斷規則識別碼設定規則嚴重性：

   dotnet_diagnostic.<rule ID>.severity = <severity>

4. 針對 IDE 程式代碼樣式分析器，您也可以使用不同的語法，在 EditorConfig 檔案中設定它們。

   例如： dotnet_style_qualification_for_field = false:suggestion 。 不過，如果您使用dotnet_diagnostic語法來設定嚴重性，它會優先被採用。 如需詳細資訊，請參閱 EditorConfig的語言慣例。

在 EditorConfig 檔案中一次設定多個分析器規則的嚴重性

Visual Studio 2019 16.5 版和更新版本中提供一次在EditorConfig 檔案中設定多個分析器規則的功能。

您可以在 EditorConfig 檔案中透過單一項目，設定特定分析器規則類別或所有分析器規則的嚴重性。

• 設定分析器規則類別的規則嚴重性：

  dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity>

• 設定所有分析器規則的規則嚴重性：

  dotnet_analyzer_diagnostic.severity = <severity>

一次設定多個分析器規則的專案僅適用於 預設啟用的規則。 分析器套件中預設標示為停用的分析器規則必須透過明確 dotnet_diagnostic.<rule ID>.severity = <severity> 項目來啟用。

如果您有多個適用於特定規則識別碼的項目，適用專案的優先順序如下所示：

• 依ID辨識的個別規則之嚴重性項目優先於類別的嚴重性項目。
• 類別的嚴重性條目比所有分析規則的嚴重性條目更優先。

請考慮下列EditorConfig範例，其中 CA1822 是效能規則：

[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion

在此範例中，這三個項目都會套用至效能規則 CA1822。 不過，使用指定的優先順序規則時，第一個以規則 ID 為基礎的嚴重性條目將優先於後續條目。 在這裡範例中，CA1822 的有效嚴重性為 error。 其餘效能規則的嚴重性為 warning。 分析規則中不是效能規則的規則，其嚴重性為 suggestion。

在燈泡選單中設定規則嚴重程度

Visual Studio 提供方便的方式，從 [ 快速動作 ] 燈泡菜單設定規則的嚴重性。 請遵循下列步驟：

1. 發生違規之後，將滑鼠停留在編輯器中的違規波浪線上方，然後選擇 [ 顯示可能修正 ] 以開啟燈泡菜單。 或者，將游標放在行上，然後按 Ctrl+。 （句號）。

2. 從燈泡菜單中，將滑鼠移動至一個嚴重性層級以查看變更的預覽，然後根據下列選項設定嚴重性的級別：

   • 設定 <規則 ID> 嚴重性。 設定特定規則的 嚴重性 。

   • 設定所有 <樣式> 分析器的嚴重性。 設定特定 規則類別中所有規則的嚴重性。

   • 設定所有分析器的嚴重性。 設定所有分析器規則類別的嚴重性。

     在下列範例中，選取 [ 隱藏或設定問題>設定 <規則標識符> 嚴重性]。

     

3. 選擇其中一個嚴重性選項。

   

   Visual Studio 會將項目新增至 EditorConfig 檔案，以將規則設定為要求的嚴重等級，如預覽視窗中所示。

   如果您專案中還沒有EditorConfig檔案，Visual Studio 會為您建立一個檔案。

在方案總管中設定規則嚴重性

若要從 [方案總管] 中設定規則的嚴重性，請遵循下列步驟：

1. 在 [方案總管] 中，展開 [參考>分析器] （或針對 .NET Core 專案，展開 [相依性>分析器]）。

2. 展開包含您要設定嚴重性之規則的組件。

3. 以滑鼠右鍵按下規則，然後選取 [ 設定嚴重性]。 在內容功能表中，選擇一個嚴重性選項。

   Visual Studio 會將一個項目新增至 EditorConfig 檔案，以設定規則至指定等級。 如果您的專案使用規則集檔案，而不是 EditorConfig 檔案，則會將嚴重性條目新增至規則集檔案。

   如果您專案中還沒有EditorConfig檔案或規則集檔案，Visual Studio 會為您建立新的EditorConfig 檔案。

從方案總管中檢視分析器和診斷

您可以從 [方案總管] 執行分析器診斷的大部分自定義。 如果您將分析器安裝為 NuGet 套件，[方案總管] 中的 [參考] 節點下方（或 .NET Core 專案的 [相依性] 節點下方）將會出現分析器節點。 請遵循下列步驟來檢視分析器和診斷：

1. 在 [方案總管] 中，展開您的專案、展開 [參考 ] 或 [ 相依性]，然後展開 [ 分析器]。 展開一個分析工具的程式集，以查看程式集中的診斷資訊。

   每個診斷旁邊的圖示會指出其 嚴重性層級：

   • x在圓形中表示錯誤狀態的嚴重性
   • !在三角形中表示警告的嚴重性
   • i在實心圓圈中表示的是建議的嚴重性等級。
   • i在虛線圓圈中表示靜默的嚴重性
   • 實心圓形中的向下指箭號表示嚴重程度為None

   

2. 若要檢視診斷的屬性，包括其描述和默認嚴重性，請以滑鼠右鍵按兩下診斷，然後選取 [ 屬性]。 或者，選取診斷，然後按 Alt+Enter。

   [屬性] 視窗隨即出現。

   

3. 若要在 [ 屬性 ] 視窗中檢視程式代碼樣式規則的屬性（IDE 前置詞），例如預設嚴重性，請將 EnforceCodeStyleInBuild 屬性設定為 true。

4. 針對診斷的線上文件，以滑鼠右鍵點擊診斷，然後選取檢視說明。

將現有的規則集檔案轉換為EditorConfig檔案

在 Visual Studio 2019 16.5 版及更新版本中，規則集檔案已被棄用，轉而使用 EditorConfig 檔案進行受控代碼的分析器組態。 EditorConfig 檔案更具彈性，可讓您設定分析器規則嚴重性和分析器選項，包括 Visual Studio IDE 程式代碼樣式選項。 因為適用於分析器規則嚴重性設定的 Visual Studio 工具現在已優化為使用 EditorConfig 檔案，而不是規則集檔案，因此建議您轉換仍使用規則集檔案的任何現有專案。

當您將現有的規則集檔案轉換成 EditorConfig 檔案時，請將它儲存在存放庫的根目錄或方案資料夾中。 如此可確保此檔案中的嚴重性設定會自動套用至整個存放庫或解決方案。

您可以使用規則集編輯器或命令行，將現有的規則集檔案轉換成 EditorConfig 檔案。

備註

.NET Core 和 .NET 5+ 專案不支援方案總管中規則集的功能表命令，例如 開啟使用中規則集。 若要指定 .NET Core 或 .NET 5+ 專案的非預設規則集，請手動 將 CodeAnalysisRuleSet 屬性新增 至項目檔。 您仍然可以在規則集編輯器中設定規則集內的規則。

若要使用規則集編輯器，請遵循下列步驟。 如果您的項目已經針對其 CodeAnalysisRuleSet 屬性值使用特定的規則集檔案，您可以從規則集編輯器將它轉換成對等的 EditorConfig 檔案：

1. 請在方案總管中雙擊規則集檔案。

   規則集檔案會在規則集編輯器中開啟，頂端有可點選 的資訊列 。

   

2. 選取 資訊列 連結以移轉規則集編輯器檔案。

3. 從 [ 另存新檔] 對話框中，選取您要產生EditorConfig 檔案的目錄，然後選取 [ 儲存]。

   產生的EditorConfig會在編輯器中開啟。 此外，MSBuild 屬性 CodeAnalysisRuleSet 會在項目檔中更新，使其不再參考原始規則集檔案。

   原始規則集檔案可以從專案中移除。

   備註

   在 .NET Framework 專案中，無法從專案移轉或移除默認規則集檔案。

若要使用命令行，請遵循下列步驟：

1. 安裝 NuGet 套件 Microsoft.CodeAnalysis.RulesetToEditorconfigConverter。

2. 從已安裝的套件執行 RulesetToEditorconfigConverter.exe ，並將規則集檔案的路徑和EditorConfig檔案當做命令行自變數。

   例如：

   Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
   

下列範例顯示要轉換成 EditorConfig 檔案的規則集檔案：

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

下列範例顯示轉換之後產生的EditorConfig 檔案：

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning
dotnet_diagnostic.CA1821.severity = warning
dotnet_diagnostic.CA2213.severity = warning
dotnet_diagnostic.CA2231.severity = warning

設定產生的程式碼

分析器會在專案中的來源檔案上執行，並報告他們發現的任何違規。 不過，這些違規不適用於系統產生的檔案。 範例會產生程式代碼檔案，例如設計工具產生的程式代碼檔案、建置系統所產生的暫存原始程序檔等等。 針對這些類型的檔案，用戶無法手動編輯檔案，且不關心修正任何違規。

因此，根據預設，分析器驅動程式只會檢查具有特定名稱、副檔名或自動生成的檔案標頭的檔案，視為生成的代碼檔案。 例如，以 .designer.cs 或 .generated.cs 結尾的檔名會被視為產生的程序代碼。 不過，這些啟發法可能無法識別使用者原始程式碼中所有自訂生成的程式碼檔案。

在 Visual Studio 2019 16.5 版和更新版本中，使用者可以將特定檔案和資料夾設定為在 EditorConfig 檔案中視為產生的程式代碼。

若要新增這類設定，請遵循下列步驟：

1. 如果您還沒有專案的EditorConfig檔案， 請新增一個檔案。

2. 在特定檔案和資料夾中新增generated_code = true | false項目。 例如，若要將所有名稱結尾為 .MyGenerated.cs 的檔案視為產生的程式代碼，請使用這個條目：

   [*.MyGenerated.cs]
   generated_code = true
   

抑制違規

您可以使用各種方法來隱藏規則違規。 如需詳細資訊，請參閱 抑制程式代碼分析違規。

命令行使用方式

當您在命令行建置專案時，如果符合下列條件，規則違規會出現在組建輸出中：

• 分析器會安裝為 .NET SDK 或 NuGet 套件的一部分，而不是作為 .vsix 擴充功能。

  針對使用 .NET SDK 安裝的分析器，您可能需要 啟用分析器。 針對程式代碼樣式，您也可以藉由設定 MSBuild 屬性， 在組建上強制執行程式代碼樣式 。

• 專案程式代碼中違反一或多個規則。

• 違反規則的 嚴重性層級 會設定 為警告，在此情況下，違規不會造成組建失敗，或 發生錯誤，在此情況下，違規會導致組建失敗。

組建輸出中的冗長程度不會影響是否顯示規則違反。 即使使用靜默詳細模式，規則違規仍會出現在建置輸出中。

如果您習慣從命令行執行舊版分析，無論是使用 FxCopCmd.exe ，還是透過具有 旗標的 msbuild RunCodeAnalysis ，您可以改用程式代碼分析器來執行。

若要在使用 msbuild 建置專案時，在命令行看到分析器違規，請執行類似下列命令：

msbuild myproject.csproj /target:rebuild /verbosity:minimal

下列螢幕快照顯示建置包含分析器規則違規之專案的命令行建置輸出：

相依專案

在 .NET Core 專案中，如果您新增具有 NuGet 分析器之項目的參考，Visual Studio 會自動將這些分析器新增至相依專案。 若要停用此行為（例如，如果相依專案是單元測試專案），請在所參考專案的 PrivateAssets 或 .vbproj 檔案中設定 屬性，將 NuGet 套件標示為私用：

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />

相關內容

• Visual Studio 中的程式碼分析器概觀
• 提交程式代碼分析器錯誤
• 使用規則集
• 隱藏程式代碼分析違規
• 程序代碼分析的組態選項