コード分析ルールの構成ファイル

  • [アーティクル]

コード分析ルールには、さまざまな構成オプションが用意されています。 これらのオプションは、次のいずれかのアナライザー構成ファイルのキーと値のペアとして指定します。

  • EditorConfig ファイル: ファイルベースまたはフォルダーベースの構成オプション。
  • Global AnalyzerConfig ファイル: プロジェクトレベルの構成オプション。 一部のプロジェクト ファイルがプロジェクト フォルダーの外部にある場合に便利です。

ヒント

プロジェクト ファイルでコード分析構成プロパティを設定することもできます。 これらのプロパティによって、コード分析が完全にオンまたはオフからカテゴリレベルの構成まで、バルク レベルで構成されます。 詳細については、「EnableNETAnalyzers」、「AnalysisLevel」、「AnalysisLevel<カテゴリ>」、「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 には、これらのファイルの 1 つをプロジェクトに簡単に追加できるようにする、.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 ファイルにはセクション ヘッダーがありません。 代わりに、これらは通常の EditorConfig ファイルと区別するために、is_global = true という形式の最上位レベルのエントリが必要です。 これは、ファイル内のすべてのオプションがプロジェクト全体に適用されることを示します。 次に例を示します。

is_global = true
<option_name> = <option_value>

名前を付ける

EditorConfig ファイルでは .editorconfig という名前を付ける必要がありますが、これとは異なりグローバル構成ファイルには特定の名前や拡張子を付ける必要はありません。 ただし、これらのファイルに .globalconfig という名前を付けた場合、これらはサブフォルダーを含む現在のフォルダー内のすべての C# および Visual Basic プロジェクトに暗黙的に適用されます。 それ以外の場合、MSBuild プロジェクト ファイルに GlobalAnalyzerConfigFiles 項目を明示的に追加する必要があります。

<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 ファイルはどちらも各オプションのキーと値のペアを指定します。 キーが同じで値が異なる複数のエントリが存在すると、競合が発生します。 オプション間で競合が発生した場合は、競合を解決するために次の優先順位の規則が使用されます。

エントリの場所が競合しています 優先順位の規則
同じ構成ファイル内 ファイル内で後の方に現れるエントリが優先されます。 これは 1 つの EditorConfig ファイル内のエントリの競合に当てはまり、さらに 1 つのグローバル AnalyzerConfig ファイル内でも同じです。
2 つの EditorConfig ファイル内 EditorConfig ファイル内のエントリのうち、ファイル システム内で階層が深い方、つまり、ファイルのパスが長い方が優先されます。
2 つのグローバル 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 ファイルに変換することをお勧めします。

  • 1 つのルールおよびそのルールが属するカテゴリに対して異なる重大度が指定されている場合など、異なるキーの関連する重要度オプションの優先順位ルールについては、「コード分析の構成オプション」を参照してください。

関連項目