程式碼分析規則的組態檔

發行項
03/13/2024

程式碼分析規則具有各種組態選項。您可以在下列其中一個分析器組態檔中，將這些選項指定為機碼值組：

EditorConfig 檔案：檔案型或資料夾型組態選項。
Global AnalyzerConfig 檔案：專案層級組態選項。當某些專案檔位於專案資料夾外部時很有用。

提示

您也可以在專案檔中設定程式碼分析組態屬性。這些屬性會在大量層級設定程式碼分析，從完全開啟或關閉程式碼到類別層級設定。如需詳細資訊，請參閱 EnableNETAnalyzers、AnalysisLevel、AnalysisLevel<Category> 和 AnalysisMode。

EditorConfig

EditorConfig 檔案可用來提供套用至特定原始程式檔或資料夾的選項。選項會放在區段標頭下，以識別適用的檔案和資料夾。針對您想要設定的每個規則新增項目，並將它放在對應的副檔名區段下，例如 [*.cs]。

[*.cs]
<option_name> = <option_value>

在上述範例中，[*.cs] 是 editorconfig 區段標頭，可選取目前資料夾 (包括子資料夾) 內副檔名為 .cs 的所有 C# 檔案。後續項目 <option_name> = <option_value> 是一個分析器選項，將套用至所有 C# 檔案。

您可以將 EditorConfig 檔案慣例套用至資料夾、專案或整個存放庫，方法是將檔案放在對應的目錄中。這些選項會在建置時間執行分析時，以及您在 Visual Studio 中編輯程式碼時套用。

注意

EditorConfig 選項僅適用於專案或目錄中的來源檔案。專案中包含的檔案，因為 AdditionalFiles 不會被視為來源檔案，而且 EditorConfig 選項不會套用至這些檔案。若要將規則選項套用至非來源檔案，請在全域組態檔中指定選項。

如果您有編輯器設定的現有 .editorconfig 檔案，例如縮排大小，或是否修剪尾端空白字元，您可以將程式碼分析組態選項放在相同的檔案中。

提示

Visual Studio 提供 .editorconfig 項目範本，可讓您輕鬆地將其中一個檔案新增至您的專案。如需詳細資訊，請參閱將 EditorConfig 檔案新增至專案。

範例

以下是組態選項和規則嚴重性的範例 EditorConfig 檔案：

# Remove the line below if you want to inherit .editorconfig settings from higher directories
root = true

# C# files
[*.cs]

#### Core EditorConfig Options ####

# Indentation and spacing
indent_size = 4
indent_style = space
tab_width = 4

#### .NET Coding Conventions ####

# this. and Me. preferences
dotnet_style_qualification_for_method = true

#### Diagnostic configuration ####

# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning

全域 AnalyzerConfig

從 .NET 5 SDK (Visual Studio 2019 與更新版本支援) 開始，您也可以使用全域 AnalyzerConfig 檔案來設定分析器選項。這些檔案可用來提供套用至專案中所有來源檔案的選項，不論其檔案名稱或檔案路徑為何。

不同於 EditorConfig 檔案，全域組態檔無法用來設定 IDE 的編輯器樣式設定，例如縮排大小，或是否修剪尾端空白字元。相反地，它們只是為了指定專案層級分析器組態選項而設計。

格式

不同於必須有區段標頭、以識別適用的檔案和資料夾的 EditorConfig 檔案 (例如 [*.cs])，全域 AnalyzerConfig 檔案沒有區段標頭。相反地，它們需要表單 is_global = true 的最上層項目，才能區分它們與一般 EditorConfig 檔案。這表示檔案中的所有選項，都會套用至整個專案。例如：

is_global = true
<option_name> = <option_value>

命名

不同於必須命名為 .editorconfig 的 EditorConfig 檔案，全域組態檔不需要具有特定名稱或副檔名。不過，如果您將這些檔案命名為 .globalconfig，則這些檔案會隱含地套用至目前資料夾 (包括子資料夾) 中的所有 C# 和 Visual Basic 專案。否則，您必須明確地將 GlobalAnalyzerConfigFiles 項目新增至 MSBuild 專案檔：

<ItemGroup>
  <GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>

請考量下列命名建議事項：

終端使用者應該將其全域組態檔命名為 .globalconfig。
NuGet 套件建立者應該將其全域組態檔命名為 <%Package_Name%>.globalconfig。
MSBuild 工具產生的全域組態檔應該命名為 <%Target_Name%>_Generated.globalconfig 或類似的名稱。

注意

當檔案命名為 .globalconfig 時，不需要最上層項目 is_global = true，但為了清楚起見，建議您這麼做。

NuGet 套件中的發行版本

全域 AnalyzerConfig 檔案可以透過 NuGet 套件散發。若要這樣做，請將 .props 檔案新增至 NuGet 套件。在 .props 檔案中，在 Project 節點底下新增 GlobalAnalyzerConfigFiles 項目：

<Project>
  <ItemGroup>
    <GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
  </ItemGroup>
</Project>

範例

以下是全域 AnalyzerConfig 檔案範例，可在專案層級設定選項和規則嚴重性：

# Top level entry required to mark this as a global AnalyzerConfig file
is_global = true

# NOTE: No section headers for configuration entries

#### .NET Coding Conventions ####

# this. and Me. preferences
dotnet_style_qualification_for_method = true:warning

#### Diagnostic configuration ####

# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning

優先順序

EditorConfig 檔案和全域 AnalyzerConfig 檔案都會為每個選項指定機碼值組。當有多個項目具有相同索引鍵但不同的值時，就會發生衝突。下列優先順序規則可用來解決衝突。

衝突的項目位置	優先順序規則
在相同的組態檔中	檔案中稍後出現的項目會勝出。這適用於在單一 EditorConfig 檔案內以及單一全域 AnalyzerConfig 檔案內的衝突項目。
在兩個 EditorConfig 檔案中	在檔案系統深層 EditorConfig 檔案中、因此具有較長檔案路徑的項目會勝出。
在兩個全域 AnalyzerConfig 檔案中	.NET 5：報告編譯器警告，並忽略這兩個項目。 .NET 6 和更新版本：具有 `global_level` 較高值之檔案的項目優先。如果未明確定義 `global_level`，且檔案名為 .globalconfig，則 `global_level` 值預設為 `100`；針對所有其他全域 AnalyzerConfig 檔案，`global_level` 預設為 `0`。如果具有衝突項目的組態檔 `global_level` 值相等，則會報告編譯器警告，並忽略這兩個項目。
在 EditorConfig 檔案和全域 AnalyzerConfig 檔案中	EditorConfig 檔案中的項目會勝出。

嚴重性選項

針對嚴重性設定選項，適用下列其他優先順序規則：

在命令列指定為編譯器選項 (-nowarn 或 -warnaserror) 的嚴重性選項，一律會覆寫 EditorConfig 和全域 AnalyzerConfig 檔案中指定的嚴重性設定選項。
規則集檔案和 EditorConfig 或全域 AnalyzerConfig 檔案中，適用於衝突嚴重性項目的優先順序規則未定義。

規則集檔案已被取代為 EditorConfig 和全域 AnalyzerConfig 檔案。我們建議您將規則集檔案轉換成對等 EditorConfig 檔案。
如需具有不同索引鍵之相關嚴重性選項的優先順序規則相關資訊，例如，針對單一規則指定不同的嚴重性，以及針對規則適用的類別時，請參閱程式碼分析的組態選項。

另請參閱

EditorConfig 與全域 AnalyzerConfig 設計問題