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

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

重大度レベル

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

ルール違反の表示

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

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

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

多くの診断には、規則違反を修正するために適用できる 1 つ以上の コード修正 が関連付けられています。 コード修正は、電球アイコン メニューと他の種類の クイック アクションに表示されます。 コード修正の詳細については、「 一般的なクイック アクション」を参照してください。

重大度レベルを構成する

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

サイレントと無のレベルの重大度

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

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

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

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

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

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

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

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

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 による個々のルールの重大度エントリは、カテゴリの重大度エントリよりも優先されます。
• カテゴリの重大度エントリは、すべてのアナライザー ルールの重大度エントリよりも優先されます。

CA1822 がパフォーマンス規則である EditorConfig の例を次に示します。

[*.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. 違反が発生した後、エディターで違反の波線をポイントし、[ 修正候補の表示 ] を選択して電球メニューを開きます。 または、行にカーソルを置き、+を押します。(ピリオド)。

2. 電球メニューで重要度レベルにカーソルを合わせて変更をプレビューし、次のオプションに従って重要度を設定します。

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

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

   • すべての解析ツールの重大度の設定を行います。 アナライザー ルールのすべてのカテゴリの重大度を設定します。

     次の例では、問題の抑制または構成><します。

     

     次の例では、問題の構成または抑制を選択し>、<します。

     

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

   

   

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

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

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

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

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

2. 重大度を設定する規則を含むアセンブリを展開します。

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

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

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

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

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

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

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

   • x円の中のエラーの重大度を示します
   • !三角形で警告の重大度を示します
   • i実線で囲まれている場合は、提案の重大度を示します。
   • i点線の円は、重大度がサイレントであることを示します。
   • 実円の下向きの矢印は、重大度が None であることを示します

   

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

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

   

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

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

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

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

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

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

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

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

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

   

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

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

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

   元のルール セット ファイルをプロジェクトから削除できます。

   注

   .NET Framework プロジェクトでは、既定のルール セット ファイルをプロジェクトに移行したり、プロジェクトから削除したりすることはできません。

コマンド ラインを使用するには、次の手順に従います。

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 ファイルがまだない場合は、ファイルを 追加します。

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

   [*.MyGenerated.cs]
   generated_code = true
   

違反を抑制する

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

コマンドラインの使用方法

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

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

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

• プロジェクトのコードで 1 つ以上のルールに違反しています。

• 違反したルールの 重大度レベル は 警告に設定されます。この場合、違反によってビルドが失敗しないか、 エラーが発生します。この場合、違反によってビルドが失敗します。

ビルド出力の詳細度は、ルール違反が表示されるかどうかには影響しません。 控えめな冗長性でも、規則違反はビルド出力に表示されます。

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

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

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

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

依存プロジェクト

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

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

関連コンテンツ

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