程式碼分析的組態選項

  • 發行項

程式碼分析規則具有各種組態選項。 其中一些選項會使用語法 <option key> = <option value>，在分析器組態檔中以索引鍵/值組形式指定。 其他選項由於會設定整個程式碼分析，因此會以專案檔中的 MSBuild 屬性形式提供。

您最常設定的選項是規則的嚴重性。 您可以設定任何規則的嚴重性等級，包括程式碼品質規則和程式碼樣式規則。 例如，若要啟用規則作為警告，請將下列索引鍵/值組新增至分析器組態檔：

dotnet_diagnostic.<rule ID>.severity = warning

您也可以設定其他選項來自訂規則行為：

  • 程式碼品質規則具有行為選項，例如規則應套用於哪些方法名稱。
  • 程式碼樣式規則具有樣式喜好設定選項，例如需要新行的位置。
  • 第三方分析器規則可能會使用自訂索引鍵名稱和值格式來定義自己的組態選項。

一般選項

這些選項會套用至整個程式碼分析。 不能只套用至特定規則。

如需其他選項，請參閱程式碼分析屬性。

分析模式

雖然 .NET SDK 包含所有程式碼分析規則，但預設只會啟用其中一些規則。 「分析模式」會決定要啟用哪一組規則 (如果有的話)。 您可以選擇啟用大多數或所有規則的更積極的分析模式。 或者，您可以選擇更保守的分析模式，其中大多數或所有規則都已停用，然後您可以根據需要選擇加入特定規則。 將 <AnalysisMode> MSBuild 屬性新增至您的專案檔，以設定您的分析模式。

<PropertyGroup>
  <AnalysisMode>Recommended</AnalysisMode>
</PropertyGroup>

從 .NET 6 開始，您也可以使用 <AnalysisMode<Category>> MSBuild 屬性來大量啟用規則類別。

注意

如果您使用 MSBuild 屬性 (例如 AnalysisMode) 來設定程式碼分析，則在您的組態檔中設定的任何大量設定選項都將被忽略。 例如，如果您已在 .editorconfig 檔案中大量啟用了所有規則或一類規則，則該組態將被忽略。

啟用程式碼分析

根據預設，以 .NET 5 和更新版本為目標的專案會啟用程式碼分析。 如果您有 .NET 5+ SDK，但您的專案以不同的 .NET 實作為目標，您可以將專案檔中的 EnableNETAnalyzers 屬性設定為 true 來手動啟用程式碼分析。

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

排除產生的程式碼

.NET 程式碼分析器警告不適用於產生的程式碼檔案 (例如設計工具產生的檔案)，因為使用者無法編輯以修正任何違規。 在大部分情況下，程式碼分析器會略過產生的程式碼檔案，而且不會回報這些檔案的違規。

根據預設，具有特定副檔名或自動產生之檔案標頭的檔案會被視為產生的程式碼檔案。 例如，以 .designer.cs 或 .generated.cs 結尾的檔案名稱會被視為產生的程式碼。 此組態選項可讓您指定要視為產生程式碼的其他命名模式。 您可以將 generated_code = true | false 項目新增至組態檔來設定其他檔案和資料夾。 例如，若要將所有名稱結尾為 .MyGenerated.cs 的檔案視為產生的程式碼，請新增下列項目：

[*.MyGenerated.cs]
generated_code = true

規則特定選項

規則特定選項可以套用至單一規則、一組規則或所有規則。 規則特定選項包括：

嚴重性等級

下表顯示您可以針對所有分析器規則設定的不同規則嚴重性，包括程式碼品質和程式碼樣式規則。

嚴重性組態值 編譯時間行為
error 違規會顯示為建置「錯誤」，並導致建置失敗。
warning 違規會顯示為建置「警告」，但不會導致建置失敗 (除非有選項可讓您將警告視為錯誤)。
suggestion 違規會顯示為建置「訊息」，並作為 Visual Studio IDE 中的建議。 (在 Visual Studio 中，建議會顯示為前兩個字元下的三個灰點。)
silent 使用者看不到違規。

不過，針對程式碼樣式規則，Visual Studio 程式碼產生功能仍會產生此樣式的程式碼。 這些規則也會參與清除，並出現在 Visual Studio 中 [快速動作和重構] 功能表中。
none 規則已完全隱藏。

不過，針對程式碼樣式規則，Visual Studio 程式碼產生功能仍會產生此樣式的程式碼。
default 使用規則的預設嚴重性。 roslyn-analyzers 存放庫 (英文) 中會列出每個 .NET 版本的預設嚴重性。 在該表格中，"Disabled" 會對應至 none，"Hidden" 會對應至 silent，而 "Info" 會對應至 suggestion。

範圍

  • 單一規則

    若要設定單一規則的規則嚴重性，請使用下列語法。

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

  • 某個類別的規則

    若要設定某個類別規則的預設規則嚴重性，請使用下列語法。 不過，此嚴重性設定只會影響該類別中預設啟用的規則。

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

    規則類別中會列出並描述不同的類別。 此外，您可以在其參考頁面上找到特定規則的類別，例如 CA1000。

  • 所有規則

    若要設定所有分析器規則的預設規則嚴重性，請使用下列語法。 不過，此嚴重性設定只會影響預設啟用的規則。

    dotnet_analyzer_diagnostic.severity = <severity value>

重要

當您使用單一項目設定多項規則的嚴重性等級時，無論是針對某個「類別」的規則的還是「所有」規則，嚴重性都只會套用至預設啟用的規則。 而如果您使用 MSBuild 屬性 <AnalysisMode> 或 <AnalysisLevel> 來啟用所有規則，則任何大量 dotnet_analyzer_diagnostic 選項都會被忽略。 基於這個理由，最好將 <AnalysisMode<Category>> 設定為 All 以啟用一類規則。

注意

設定單一規則嚴重性的前置詞 dotnet_diagnostic，與透過類別設定嚴重性或設定所有規則嚴重性的前置詞 dotnet_analyzer_diagnostic 稍有不同。

優先順序

如果您有多個可套用至相同規則識別碼的嚴重性組態項目，則會依下列順序選擇優先順序：

  • 某個類別的項目會優先於所有分析器規則的項目。
  • 依識別碼的個別規則項目會優先於某個類別的項目。

請考慮下列範例，其中 CA1822 具有「效能」類別：

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

在上述範例中，所有三個嚴重性項目都適用於 CA1822。 不過，使用指定的優先順序規則時，第一個規則識別碼項目會優先於後續項目。 在此範例中，CA1822 的有效嚴重性為 error。 「效能」類別內所有其他規則的嚴重性為 warning。

如需如何決定檔案間優先順序的資訊，請參閱＜組態檔＞一文的＜優先順序＞一節。