自訂 Roslyn 分析器規則

發行項
04/11/2024

每個 Roslyn 分析器規則或診斷都有預設嚴重性和隱藏狀態，可針對專案自訂。本文涵蓋設定分析器嚴重性及隱藏分析器違規。

嚴重性層級

在 Visual Studio 2019 16.3 版或更高版本，可以從 [燈泡功能表] 與 [錯誤清單] 視窗，在 EditorConfig 檔案中設定分析器規則的嚴重性。

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

嚴重性 (方案總管)	嚴重性 (EditorConfig 檔案)	建置時間行為	編輯器行為
錯誤	`error`	違規會顯示在 [錯誤清單] 視窗的 [錯誤] 狀態標籤與命令列組建輸出中，並導致組建失敗。	違規程式碼會以紅色波形曲線加上底線，同時以捲軸的紅色小方塊標示。
警告	`warning`	違規會顯示在 [錯誤清單] 視窗的 [警告] 索引標籤與命令列組建輸出中，但不會導致組建失敗。	違規程式碼會以綠色波形曲線加上底線，同時以捲軸的綠色小方塊標示。
建議	`suggestion`	違規會顯示在 [錯誤清單] 視窗的 [訊息] 索引標籤中，但不會顯示在命令列組建輸出中。	受影響的程式碼會以灰色波形曲線加上底線，同時以捲軸的灰色小方塊標示。
無訊息	`silent`	使用者不可見。	使用者不可見，但診斷會回報給整合式開發環境 (IDE) 診斷引擎。
無	`none`	已完全隱藏。	已完全隱藏。
預設	`default`	對應至規則的預設嚴重性。若要判定規則的預設值為何，請檢視其 [屬性視窗]。	對應至規則的預設嚴重性。

檢視規則違規

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

下列螢幕擷取畫面顯示了 [錯誤清單] 視窗中回報的規則違規。錯誤清單中回報的分析器違規符合規則的嚴重性等級設定：

分析器規則違規也會在程式碼編輯器中以波形曲線形式顯示在違規程式碼下方。例如，以下螢幕擷取畫面顯示三個違規：一個錯誤 (紅色波形曲線)、一個警告 (綠色波形曲線) 和一條建議 (三個灰色點)：

螢幕擷取畫面顯示程式碼編輯器中錯誤、警告和建議標記。

許多診斷都有一或多個相關聯的程式碼修正，可套用來修正規則違規。程式碼修正會顯示在燈泡圖示功能表中，並顯示其他類型的快速動作。如需程式碼修正的詳細資訊，請參閱<一般的快速動作>(英文)。

設定嚴重性等級

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

EditorConfig
燈泡功能表
錯誤清單視窗
方案總管

EditorConfig
燈泡功能表
錯誤清單視窗
方案總管
規則集檔案

無訊息與無嚴重性

依預設啟用的 Silent 嚴重性規則與停用或 None 嚴重性規則不同：

如果已針對 Silent 嚴重性規則註冊程式碼修正，則即使使用者無法看到隱藏的診斷，Visual Studio 仍會提供程式碼修正做為燈泡程式碼重構動作。如果嚴重性規則作為 None 停用，則不會提供程式碼修正。
若項目在 EditorConfig 檔案一次設定多個分析器規則的嚴重性，則可大量設定 Silent 嚴重性規則。 None 嚴重性規則無法以此方式設定。相反地，這些規則必須透過在 EditorConfig 檔案中針對每個規則 ID 設定嚴重性的項目來設定。

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

Visual Studio 2019 16.3 版與更高版本提供 EditorConfig 檔案。

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

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

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

將 EditorConfig 檔案新增至專案 (如尚未新增)。
在對應的副檔名下，針對您想要設定的每個規則新增項目。

例如，若要針對 C# 檔案將 CA1822 的嚴重性設定為 error，項目看起來會如下所示：
```
[*.cs]
dotnet_diagnostic.CA1822.severity = error
```
可以使用下列語法，針對 EditorConfig 檔案中的每個診斷規則 ID 設定規則嚴重性：

dotnet_diagnostic.<rule ID>.severity = <severity>
針對整合式開發環境 (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 的項目，則適用項目的優先順序如下所示：

依 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 可讓您從 [快速動作] 燈泡功能表設定規則的嚴重性。執行下列步驟:

發生違規之後，將滑鼠停留在編輯器中的違規波形曲線上方，然後選擇 [顯示可能的修正] 來開啟燈泡功能表。或是將游標放在線上，並按下 Ctrl+. (句點)。
從燈泡功能表中，將滑鼠停留在嚴重性等級上，以便取得變更預覽，然後按照以下選項設定嚴重性：
- 設定 <規則 ID> 嚴重性。 針對特定規則設定嚴重性。
- 針對所有<樣式>分析器設定嚴重性。 針對特定規則類別中的所有規則設定嚴重性。
- 設定所有分析器的嚴重性。 針對所有分析器規則類別設定嚴重性。
  
  在下列範例，選取 [隱藏或設定問題]>[設定<規則 ID> 嚴重性]。
  
  在下列範例，選取 [設定或隱藏問題]>[設定<規則 ID> 嚴重性]。
選擇其中一個嚴重性選項。

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

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

從 [錯誤清單] 視窗設定規則嚴重性

Visual Studio 也提供便利的方式，讓您從錯誤清單內容功能表設定規則的嚴重性。執行下列步驟:

發生違規之後，以滑鼠右鍵按一下錯誤清單中的診斷項目。
從特色選單選取 [設定嚴重性]，然後選取其中一個嚴重性選項。

Visual Studio 會將項目新增至 EditorConfig 檔案，以將規則設定為要求層級。

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

從方案總管設定規則嚴重性

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

在 [方案總管] 中，展開 [參考]>[分析器] (或針對 .NET Core 專案展開 [相依性]>[分析器])。
展開包含要設定嚴重性的規則組件。
以滑鼠右鍵按一下規則，然後選取 [設定嚴重性]。在操作功能表中，選擇其中一個嚴重性選項。

Visual Studio 會將項目新增至 EditorConfig 檔案，以將規則設定為要求層級。如果專案使用規則集檔案，而不是 EditorConfig 檔案，則會將嚴重性項目新增至規則集檔案。

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

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

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

以下列其中一種方式開啟使用中的規則集檔案：
- 在 [方案總管] 中，展開檔案，然後展開 [參考]。以滑鼠右鍵按一下 [分析器]，然後選取 [開啟作用中規則集]。
- 在專案的 [程式碼分析] 屬性頁面上，選取 [開啟] 。
如果是第一次編輯規則集，則 Visual Studio 會建立預設規則集檔案的複本，將複本命名為 <projectname>.ruleset，然後將其新增至專案。此自訂規則集也會成為您專案的使用中規則集。

注意

.NET Core 和 .NET Standard 專案不支援 [方案總管] 中規則集的功能表命令，例如，[開啟作用中規則集]。若要為 .NET Core 或 .NET Standard 專案指定非預設規則集，請手動將 CodeAnalysisRuleSet 屬性新增至專案檔。您仍然可以在規則集編輯器中設定規則集內的規則。
展開包含規則的組件，以便瀏覽至規則，然後加以選取。
在所選規則的 [動作] 資料行，選取要開啟下拉式清單的值，然後從清單選擇嚴重性等級。

從 [方案總管] 檢視分析器與診斷

您可以從 [方案總管] 執行大部分的分析器診斷自訂。如果將分析器安裝為 NuGet 套件，則 [分析器] 節點會出現在 [方案總管] 的 [參考] 節點 (或若為 .Net Core 專案，則出現在[相依性] 節點) 下。請遵循下列步驟來檢視分析器與診斷：

在 [方案總管] 中，展開專案、展開 [參考] 或 [相依性]，然後展開 [分析器]。展開其中一個分析器組件，查看組件診斷。

每個診斷旁邊的圖示表示其嚴重性等級：
- 圓形中的 x 表示嚴重性為錯誤
- 三角形中的 ! 表示嚴重性為警告
- 實心圓形中的 i 表示嚴重性為建議
- 虛線圓形中的 i 表示嚴重性為無訊息
- 實心圓形中的向下箭號表示嚴重性為無
若要檢視診斷屬性 (包括其描述與預設嚴重性)，以滑鼠右鍵按一下診斷，然後選取 [屬性]。或者，選取診斷，然後按Alt+Enter。

[屬性] 視窗隨即出現。
若要在 [屬性] 視窗中檢視程式碼樣式規則的屬性 (整合式開發環境 (IDE) 前置詞)，例如預設嚴重性，請將 EnforceCodeStyleInBuild 屬性設定為 true。
如需診斷的線上文件，請以滑鼠右鍵按一下診斷，然後選取 [檢視輔助說明]。

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

在 Visual Studio 2019 16.5 版或更高版本，規則集檔案已被取代為受控程式碼分析器組態的 EditorConfig 檔案。 EditorConfig 檔案更具彈性且可讓您設定分析器規則嚴重性和分析器選項，包括 Visual Studio 整合式開發環境 (IDE) 程式碼樣式選項。因為適用於分析器規則嚴重性設定的 Visual Studio Tools 現在已最佳化為使用 EditorConfig 檔案，而非規則集檔案，因此建議轉換仍使用規則集檔案的任何現有專案。

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

可以使用規則集編輯器或命令列，轉換現有規則集檔案為 EditorConfig 檔案。

注意

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

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

按兩下 [方案總管] 中的規則集檔案。

規則集檔案會在規則集編輯器中開啟，頂端有可點按的 [資訊列]。
選取 [資訊列] 連結以便移轉規則集編輯器檔案。
從 [另存新檔] 對話方塊中，選取要產生 EditorConfig 檔案的目錄，然後選取 [儲存]。

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

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

安裝 NuGet 套件 Microsoft.CodeAnalysis.RulesetToEditorconfigConverter。
從已安裝的套件執行 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 檔案中產生的程式碼。

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

如果您還沒有專案的 EditorConfig 檔案，請新增檔案。
新增特定檔案與資料夾的 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

下列螢幕擷取畫面顯示命令列建置輸出，其中所建置的專案包含了分析器違規：

螢幕擷取畫面顯示在開發人員命令提示字元違反規則的 MSBuild 輸出。

相依專案

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

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

自訂 Roslyn 分析器規則

嚴重性層級

檢視規則違規

設定嚴重性等級

無訊息與無嚴重性

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

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

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

從燈泡功能表設定規則嚴重性

從 [錯誤清單] 視窗設定規則嚴重性

從方案總管設定規則嚴重性

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

從 [方案總管] 檢視分析器與診斷

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

設定產生的程式碼

隱藏違規

命令列用法

相依專案

意見反應

意見反應

其他資源

自訂 Roslyn 分析器規則

嚴重性層級

檢視規則違規

設定嚴重性等級

無訊息與無嚴重性

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

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

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

從燈泡功能表設定規則嚴重性

從 [錯誤清單] 視窗設定規則嚴重性

從方案總管設定規則嚴重性

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

從 [方案總管] 檢視分析器與診斷

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

設定產生的程式碼

隱藏違規

命令列用法

相依專案

相關內容

意見反應

意見反應

其他資源