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

[アーティクル]
06/11/2024

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

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

ヒント

プロジェクトファイルでコード分析構成プロパティを設定することもできます。これらのプロパティによって、コード分析が完全にオンまたはオフからカテゴリレベルの規則構成まで、バルクレベルで構成されます。詳細については、「EnableNETAnalyzers」、「AnalysisLevel」、「AnalysisLevel<カテゴリ>」、「AnalysisMode」を参照してください。

EditorConfig

EditorConfig ファイルは、特定のソースファイルまたはフォルダーに適用されるオプションを提供するために使用されます。オプションは、該当するファイルとフォルダーを識別するためにセクションヘッダーの下に配置されます。構成するルールごとのエントリを追加し、対応するファイル拡張子セクションの下に配置します (たとえば [*.cs])。

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

上の例では、[*.cs] は、サブフォルダーを含む現在のフォルダー内にある .cs ファイル拡張子を持つすべての C# ファイルを選択するための editorconfig セクションヘッダーです。後続のエントリ <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

グローバル 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 またはこれに類似した名前を付ける必要があります。

Note

ファイル名が .globalconfig の場合、トップレベルのエントリ is_global = true は要件ではありませんが、わかりやすくするために推奨されます。

条件付きの包含

グローバル構成ファイルを使用して、さまざまな環境で特定のコード分析ルールを無効または有効にすることができます。たとえば、単体テストプロジェクトの一部のコード分析ルールを無効にしたい場合があります。これを行うには、構成ファイルで適用されるルールの重大度を none に設定できます。次に例を示します。

# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none

そうすると、ビルドに固有の条件に基づいて、テストプロジェクトに構成ファイルのみを含むようにビルドをカスタマイズできます。次に例を示します。

<ItemGroup Condition="'$(IsShipping)' == 'false'">
  <!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
  <GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>

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

次の方法で共有