Roslyn アナライザーのルールをカスタマイズする

各 Roslyn アナライザー ルールまたは診断には、プロジェクトに合わせてカスタマイズできる規定の重大度と抑制の状態があります。 この記事では、アナライザーの重要度の設定と、アナライザーの違反の抑制について説明します。

セキュリティ レベル

Visual Studio 2019 バージョン 16.3 以降では、アナライザーのルールの重要度を、EditorConfig ファイル、電球メニュー、およびエラー一覧ウィンドウで構成できます。

次の表に、診断用に構成できるさまざまな重要度オプションを示します。

重要度 (ソリューション エクスプローラー)	重要度 (EditorConfig ファイル)	ビルド時の動作	エディターの動作
エラー	error	違反は、[エラー一覧] ウィンドウの [エラー] タブとコマンドラインのビルド出力に表示され、ビルドが失敗します。	問題を起こしているコードには赤色の波線が引かれ、スクロール バーに小さい赤色のボックスが示されます。
警告	warning	違反は、[エラー一覧] ウィンドウの [警告] タブに表示されますが、ビルドが失敗することはありません。	問題を起こしているコードには緑色の波線が引かれ、スクロール バーに小さい緑色のボックスが示されます。
推奨事項	suggestion	違反は、[エラー一覧] ウィンドウの [メッセージ] タブに表示され、コマンドラインのビルド出力には表示されません。	影響を受けたコードには灰色の波線が引かれ、スクロール バーに小さい灰色のボックスが示されます。
サイレント	silent	ユーザーには表示されません。	ユーザーには表示されませんが、診断は IDE 診断エンジンに報告されます。
なし	none	完全に抑制されます。	完全に抑制されます。
Default	default	ルールの既定の重要度に対応します。 ルールの既定値を確認するには、プロパティ ウィンドウを表示します。	ルールの既定の重要度に対応します。

ルール違反を表示する

アナライザーは、アナライザー ルール違反を検出した場合、[エラー一覧] ウィンドウとコード エディターで報告します。

次のスクリーンショットは、[エラー一覧] ウィンドウで報告されたルール違反を示しています。 エラー一覧に報告されるアナライザーの違反は、ルールの重要度レベルの設定と一致します。

また、アナライザーのルール違反は、コード エディターで問題を起こしているコードの下に波線として表示されます。 たとえば、次のスクリーンショットは 3 つの違反 (1 つのエラー (赤い波線)、1 つの警告 (緑の波線)、および 1 つの候補 (3 つの灰色の点) を示しています。

多くの診断には、1 つ以上のコード修正が関連付けられており、これを適用してルール違反を修正できます。 コード修正は、電球アイコン メニューに、他の種類のクイック アクションと共に示されます。 これらのコード修正についての詳細は、「共通のクイック アクション」を参照してください。

重要度レベルを構成する

ルールの重大度は、次のいずれかの方法で設定できます。

• EditorConfig
• 電球メニュー
• [エラー一覧] ウィンドウ
• ソリューション エクスプローラー

サイレントとなしの重大度

既定で有効になっている Silent 重要度ルールは、無効すなわち None 重要度ルールとは異なります。

• Silent 重要度ルールのコード修正が登録されている場合は、非表示の診断がユーザーに表示されない場合でも、Visual Studio からは電球コード リファクタリング アクションとしてコード修正プログラムが提供されます。 重要度ルールが None として無効にされている場合、このコード修正は提供されません。
• Silent 重要度ルールは、EditorConfig ファイル内で一度に複数のアナライザー ルールの重要度を設定するエントリによって一括構成できます。 None 重要度ルールをこのように構成することはできません。 代わりに、ルール ID ごとに EditorConfig ファイルで重要度を設定するエントリを使用して構成する必要があります。

EditorConfig ファイルでルールの重要度を設定する

EditorConfig ファイルは、Visual Studio 2019 バージョン 16.3 以降で使用できます。

EditorConfig ファイルでのルールの重要度の設定は、ルール セットまたはソリューション エクスプローラーで設定される重要度よりも優先されます。 EditorConfig ファイルで重要度を手動で構成することも、違反の横に表示される電球を使用して自動的に構成することもできます。

EditorConfig ファイルでルール重要度を手動で構成する

ルールの重大度を構成するには、次の手順に従います。

1. EditorConfig ファイルがまだない場合は、プロジェクトに 1 つ追加します。

2. 対応するファイル拡張子の下に、構成するルールごとにエントリを追加します。

   たとえば、CA1822 の重要度を C# ファイルについて error に設定するためのエントリは、次のようになります。

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. EditorConfig ファイル内の各診断ルール ID のルールの重要度は、次の構文で設定できます。

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

4. IDE コードスタイルのアナライザーでは、別の構文を使用して、EditorConfig ファイルに構成することもできます。

   たとえば、dotnet_style_qualification_for_field = false:suggestion のようにします。 ただし、dotnet_diagnostic 構文を使用して重要度を設定した場合は、そちらが優先されます。 詳細については、EditorConfig の言語規則に関するページを参照してください。

EditorConfig ファイルで一度に複数のアナライザー ルールの重要度を設定する

EditorConfig ファイルで一度に複数のアナライザー ルールを設定する機能は、Visual Studio 2019 バージョン 16.5 以降で使用できます。

次の EditorConfig ファイルの 1 つのエントリで、特定のカテゴリのアナライザー ルールの重要度を設定することも、すべてのアナライザー ルールの重要度を設定することもできます。

• あるカテゴリのアナライザー ルールのルール重要度を設定します。

  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

この例では、3 つのエントリすべてがパフォーマンス ルール CA1822 に適用されます。 ただし、指定した優先順位ルールを使用すると、最初のルール ID ベースの重要度エントリが次のエントリに優先されます。 この例の場合、CA1822 の有効な重要度は error です。 残りのパフォーマンス ルールの重大度は warning です。 パフォーマンス ルールではないアナライザー ルールの重要度 は suggestion です。

電球メニューでルールの重要度を設定する

Visual Studio には、クイック アクションの電球メニューからルールの重要度を構成する便利な方法が用意されています。 次のステップを実行します。

1. 違反が発生した後、エディターで違反の波線をポイントし、[考えられる修正内容の表示] を選択して電球メニューを開きます。 または、その行にカーソルを置き、Ctrl+. (ピリオド) キーを押します。

2. 電球メニューから、重大度レベルにマウスを移動して変更のプレビューを表示し、次のオプションに従って重大度を構成します。

   • <ルール ID> の重要度を構成します。 特定のルールの重要度を設定します。

   • すべての<スタイル>アナライザーの重要度を構成します。 特定のルール カテゴリのすべてのルールの重要度を設定します。

   • すべてのアナライザーの重要度を構成します。 すべてのカテゴリのアナライザー ルールの重要度を設定します。

     次の例では、[問題の抑制または構成]>[<ルール ID> 重要度の構成] を選択します。

     

3. 重要度オプションのいずれかを選択します。

   

   Visual Studio によって EditorConfig ファイルにエントリが追加され、プレビュー ボックスに示されているように、要求された重要度レベルのルールが構成されます。

   プロジェクトに EditorConfig ファイルがまだない場合、Visual Studio によって作成されます。

[エラー一覧] ウィンドウでルールの重要度を設定する

また、Visual Studio では、[エラー一覧] のコンテキスト メニューからルールの重要度を構成する便利な方法も提供されています。 次のステップを実行します。

1. 違反が発生した後で、[エラー一覧] の診断エントリを右クリックします。

2. コンテキスト メニューから [重要度の設定] を選択し、重要度オプションのいずれかを選択します。

   

   Visual Studio によって EditorConfig ファイルにエントリが追加され、要求されたレベルのルールが構成されます。

   プロジェクトに EditorConfig ファイルがまだない場合、Visual Studio によって作成されます。

ルールの重要度をソリューション エクスプローラーで設定する

ソリューション エクスプローラーからルールの重大度を設定するには、次の手順に従います。

1. ソリューション エクスプローラーで、[参照]>[アナライザー] (または .NET Core プロジェクトでは [依存関係]>[アナライザー]) を展開します。

2. 重要度を設定するルールが含まれているアセンブリを展開します。

3. 右クリックし、[重要度の設定] を選択します。 コンテキスト メニューで、重要度オプションの 1 つを選択します。

   Visual Studio によって EditorConfig ファイルにエントリが追加され、要求されたレベルのルールが構成されます。 プロジェクトで EditorConfig ファイルではなくルール セット ファイルが使用されている場合、重要度エントリがルール セット ファイルに追加されます。

   プロジェクトに EditorConfig ファイルまたはルール セット ファイルがまだない場合は、Visual Studio によって新しい EditorConfig ファイルが作成されます。

ソリューション エクスプローラーからアナライザーと診断を表示する

ソリューション エクスプローラーで、アナライザー診断のカスタマイズの多くを行うことができます。 NuGet パッケージとしてアナライザーをインストールすると、ソリューション エクスプローラーで [参照] ノード (または .NET Core プロジェクトの [依存関係] ノード) の下に [アナライザー] ノードが表示されます。 アナライザーと診断を表示するには、次の手順に従います。

1. ソリューション エクスプローラーで、プロジェクトを展開し、[参照] または [依存関係] を展開して、[アナライザー] を展開します。 いずれかのアナライザー アセンブリを展開して、アセンブリ内の診断を表示します。

   各診断の横にあるアイコンは、その 重大度レベルを示します。

   • 円の中の x は、重要度 [エラー] を示します
   • 三角形の中の ! は、重要度 [警告] を示します
   • 塗りつぶされた円の中の i は、重要度 [提案] を示します
   • 点線の円の中の i は、重要度 [サイレント] を示します
   • 塗りつぶされた円の中の下向き矢印は、重要度 [なし] を示します

   

2. 説明や既定の重要度など、診断のプロパティを表示するには、診断を右クリックし、[プロパティ] を選択します。 または、診断を選択し、Alt+Enter キーを押します。

   [プロパティ] ウィンドウが表示されます。

   

3. 既定の重要度など、[プロパティ] ウィンドウ内のコード スタイル ルール (IDE プレフィックス) のプロパティを表示するには、EnforceCodeStyleInBuild プロパティを true に設定します。

4. 診断のオンラインドキュメントについては、診断を右クリックし、[ヘルプの表示] を選択します。

既存のルール セット ファイルを EditorConfig ファイルに変換する

Visual Studio 2019 バージョン 16.5 以降では、ルール セット ファイルは非推奨になり、マネージド コードのアナライザー構成で EditorConfig ファイルが優先されます。 EditorConfig ファイルはより柔軟であり、これを使用すると、Visual Studio IDE のコード スタイル オプションを含め、アナライザーのルールの重要度とアナライザーのオプションの両方を構成できます。 アナライザー ルールの重要度構成用の Visual Studio ツールは、ルール セット ファイルではなく EditorConfig ファイルを操作できるように最適化されているため、ルール セット ファイルを引き続き使用する既存のプロジェクトを変換することをお勧めします。

既存のルール セット ファイルを EditorConfig ファイルに変換する場合は、リポジトリのルートまたはソリューション フォルダーに保存します。 これにより、このファイルの重要度設定がリポジトリ全体またはソリューションに、それぞれ自動的に適用されます。

ルール セット エディターまたはコマンド ラインを使用して、既存のルール セット ファイルを EditorConfig ファイルに変換できます。

Note

.NET Core および .NET Standard のプロジェクトは、ソリューション エクスプローラーのルール セットのメニュー コマンド ([アクティブなルール セットを開く] など) に対応していません。 .NET Core または .NET Standard pプロジェクトに対して既定以外のルール セットを指定するには、プロジェクト ファイルに手動で CodeAnalysisRuleSet プロパティを追加します。 ルール セット エディターでルール セット内のルールを構成することはできます。

ルール セット エディターを使用するには、次の手順に従います。 特定のルール セット ファイルが CodeAnalysisRuleSet プロパティ値用にプロジェクトで既に使用されている場合、ルール セット エディターで同等の EditorConfig ファイルに変換できます。

1. ソリューション エクスプローラーでルール セット ファイルをダブルクリックします。

   ルール セット ファイルがルール セット エディターで開き、上部にクリック可能な [情報バー] が表示されます。

   

2. 情報バーのリンクを選択して、ルール セット エディター ファイルを移行します。

3. [名前を付けて保存] ダイアログで、EditorConfig ファイルを生成するディレクトリを選択し、[保存] を選択します。

   生成された EditorConfig がエディターで開きます。 また、MSBuild プロパティ CodeAnalysisRuleSet がプロジェクト ファイルで更新され、元のルール セット ファイルが参照されなくなります。

このコマンド ラインを使用する手順は次のとおりです。

1. NuGet パッケージ Microsoft CodeAnalysis. RulesetToEditorconfigConverter をインストールします。

2. ルール セット ファイルと EditorConfig ファイルへのパスをコマンドライン引数として、インストールしたパッケージの RulesetToEditorconfigConverter.exe を実行します。

   次に例を示します。

   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 ファイルで構成できます。

このような構成を追加するには、次の手順に従います。

1. プロジェクトの EditorConfig ファイルがまだない場合は、1 つ追加します。

2. 特定のファイルおよびフォルダーに対する generated_code = true | false エントリを追加します。 たとえば、名前が .MyGenerated.cs で終わるすべてのファイルを生成されたコードとして扱うには、このエントリを使用します。

   [*.MyGenerated.cs]
   generated_code = true
   

違反を抑制する

さまざまな手法を利用し、ルール違反を抑制できます。 詳細については、「コード分析の違反を抑制する」を参照してください。

コマンド ラインの使用

コマンドラインでプロジェクトをビルドするとき、次の条件が満たされた場合に、ルール違反がビルドの出力に表示されます。

• アナライザーが、.vsix 拡張機能としてではなく、.NET SDK を使用するか NuGet パッケージとしてインストールされています。

  .NET SDK を使用してインストールされたアナライザーでは、アナライザーの有効化が必要になることがあります。 コード スタイルでは、MSBuild プロパティを設定して、ビルドにコード スタイルを適用することもできます。

• プロジェクトのコードで 1 つ以上のルールの違反があります。

• 違反しているルールの重要度レベルが、warning (違反のためにビルドが失敗しない) または error (違反のためにビルドが失敗する) に設定されています。

ビルド出力の詳細度は、ルール違反が表示されるかどうかには影響しません。 詳細度が quiet でも、ルール違反はビルド出力に表示されます。

FxCopCmd.exe を使用したり、msbuild を RunCodeAnalysis フラグと一緒に使用したりして、コマンド ラインからレガシ分析を実行することに慣れている場合、代わりにコード アナライザーでこれを行うことができます。

msbuild を使用してプロジェクトをビルドするときにコマンド ラインでアナライザーの違反を表示するには、次のようなコマンドを実行します。

msbuild myproject.csproj /target:rebuild /verbosity:minimal

次のスクリーンショットは、アナライザー ルール違反を含むプロジェクトのビルドからのコマンドライン ビルド出力を示しています。

依存プロジェクト

.NET Core プロジェクトでは、NuGet アナライザーを含むプロジェクトに参照を追加すると、Visual Studio はそれらのアナライザーを依存プロジェクトに自動的に追加します。 この動作を無効にするには、たとえば依存プロジェクトが単体テスト プロジェクトの場合、参照されるプロジェクトの .csproj または .vbproj ファイルで PrivateAssets 属性を設定して、NuGet パッケージをプライベートとマークします。

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

関連するコンテンツ

• Visual Studio のコード アナライザーの概要
• コード アナライザーのバグを送信する
• ルール セットを使用する
• コード分析の違反を抑制する
• コード分析の構成オプション