概要

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

重要度レベルを構成する

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

NuGet パッケージとして アナライザーをインストールした場合は、アナライザーのルールすなわち "診断" の重要度を構成できます。 ルールの重要度は、ソリューション エクスプローラーまたはルール セット ファイル内で変更できます。

注意

エラーが発生すると、Visual Studio ではビルドが失敗しますが、dotnet build を失敗させるには、プロジェクトのプロパティ ページenforcecodestyleinbuildtrue に設定する必要があります。

次の表は、さまざまな重要度のオプションを示しています。

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

アナライザーでルール違反が見つかった場合は、コード エディター (問題のあるコードの下の "波線" として) および [エラー一覧] ウィンドウで報告されます。

エラー一覧に報告されるアナライザーの違反は、ルールの重要度レベルの設定と一致します。 また、アナライザーの違反は、コード エディター内の問題を起こしているコードの下に波線で示されます。 次の図は、3 つの違反 — 1 つのエラー (赤色の波線)、1 つの警告 (緑色の波線)、1 つの候補 (灰色の 3 つの点) を示しています。

Visual Studio でのコード エディターの波線

次のスクリーンショットには、エラー一覧に表示されるのと同じ 3 つの違反が示されています。

エラー一覧のエラー、警告、および情報の違反

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

アナライザーの違反とクイック アクションのコード修正

'Hidden' 重要度および 'None' 重要度

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

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

(Visual Studio 2019 バージョン 16.3 以降)

次の構文を使用して、EditorConfig ファイルでコンパイラの警告またはアナライザーのルールの重要度を設定できます。

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

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" になります。

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

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

  2. 対応するファイル拡張子の下に、構成するルールごとにエントリを追加します。 たとえば、CA1822 の重要度を C# ファイルについて error と設定する場合、エントリは次のようになります。

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

注意

IDE コードスタイルのアナライザーでは、別の構文を使用して、EditorConfig ファイルに構成することもできます (例: dotnet_style_qualification_for_field = false:suggestion)。 ただし、dotnet_diagnostic 構文を使用して重要度を設定した場合は、そちらが優先されます。 詳細については、EditorConfig の言語規則に関するページを参照してください。

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

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

  1. 違反が発生した後、エディターで違反の波線をポイントし、電球メニューを開きます。 または、その行にカーソルを置き、Ctrl+ . (ピリオド) を押します。

  2. 電球メニューで、 [問題の構成または抑制] > [構成] <rule ID> [重要度] を選択します。

    Visual Studio の電球メニューでルールの重要度を構成する

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

    ルールの重要度を Suggestion として構成する

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

    ヒント

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

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

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

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

  2. コンテキスト メニューで、 [重要度の設定] を選択します。

    Visual Studio の [エラー一覧] でルールの重要度を構成する

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

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

    ヒント

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

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

ソリューション エクスプローラー で、アナライザー診断のカスタマイズの多くを行うことができます。 NuGet パッケージとして アナライザーをインストールすると、ソリューション エクスプローラー[参照] または [依存関係] ノードの下に [アナライザー] ノードが表示されます。 [アナライザー] を展開してから、アナライザー アセンブリの 1 つを展開すると、そのアセンブリ内のすべての診断が表示されます。

ソリューション エクスプローラーの [アナライザー] ノード

[プロパティ] ウィンドウに、説明や既定の重要度など、診断のプロパティが表示されます。 プロパティを表示するには、ルールを右クリックして [プロパティ] を選択するか、ルールを選択してから Alt+Enter キーを押します。

[プロパティ] ウィンドウの [診断のプロパティ]

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

ソリューション エクスプローラー の各診断の横にあるアイコンは、エディターで開いたときにルール セットに表示されるアイコンと対応しています。

  • 円の中の "x" は、重要度 Error を示します。
  • 三角形の中の "!" は、重要度 Warning を示します。
  • 円の中の "i" は、重要度 Info を示します。
  • 白抜きの円の中の "i" は、重要度 Hidden を示します。
  • 円の中の下向き矢印は、診断が抑制されていることを示します。

ソリューション エクスプローラーの診断アイコン

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

Visual Studio 2019 バージョン 16.5 以降では、ルール セット ファイルは非推奨になり、マネージド コードのアナライザー構成で EditorConfig ファイルが優先されます。 アナライザーのルールの重要度を構成するための Visual Studio ツールのほとんどが、ルール セット ファイルではなく EditorConfig ファイルで動作するように更新されました。 EditorConfig ファイルを使用すると、Visual Studio IDE のコード スタイル オプションを含め、アナライザーのルールの重要度とアナライザーのオプションの両方を構成できます。 既存のルール セット ファイルを EditorConfig ファイルに変換することを強くお勧めします。 また、EditorConfig ファイルは、リポジトリのルートまたはソリューション フォルダーに保存することをお勧めします。 リポジトリのルートまたはソリューション フォルダーを使用すると、このファイルの重要度設定が、それぞれリポジトリ全体またはソリューション全体に自動的に適用されるようになります。

既存のルール セット ファイルを EditorConfig ファイルに変換するには、いくつかの方法があります。

  • Visual Studio のルール セット エディターで (Visual Studio 2019 16.5 以降が必要)。 特定のルール セット ファイルが CodeAnalysisRuleSet としてプロジェクトで既に使用されている場合、Visual Studio 内のルール セット エディターで同等の EditorConfig ファイルに変換できます。

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

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

      ルール セット エディターでルール セットを EditorConfig ファイルに変換する

    2. 情報バー のリンクを選択します。

      これで、 [名前を付けて保存] ダイアログ ボックスが開くので、ここで EditorConfig ファイルを生成するディレクトリを選択します。

    3. [保存] ボタンを選択して、EditorConfig ファイルを生成します。

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

  • コマンドラインから:

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

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

    Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_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

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

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

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

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

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

    ヒント

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

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

    ルールの重要度が、アクティブなルール セット ファイルに保存されます。

ルール セット ファイルでルールの重要度を設定する

ソリューション エクスプローラーのルール セット ファイル

  1. 次のいずれかの方法で、アクティブなルール セット ファイルを開きます。
  • ソリューション エクスプローラー で、ファイルをダブルクリックし、 [参照] > [アナライザー] ノードを右クリックして、 [アクティブなルール セットを開く] を選択します。

  • プロジェクトの [コード分析] プロパティ ページで、 [開く] を選択します。

    このとき初めてルール セットを編集する場合は、Visual Studio によって既定のルール セット ファイルのコピーが作成され、 <projectname>.ruleset という名前が付けられてプロジェクトに追加されます。 このカスタム ルール セットが、プロジェクトのアクティブなルール セットにもなります。

    注意

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

  1. 含まれているアセンブリを展開して、ルールを参照します。

  2. [アクション] 列で、値を選択してドロップダウン リストを開き、目的の重要度を一覧から選択します。

    エディターに開かれたルール セット ファイル

生成されたコードを構成する

アナライザーは、プロジェクト内のすべてのソース ファイルに対して実行され、それらについて違反を報告します。 ただし、これらの違反は、生成されたコード ファイル (デザイナーで生成されたコード ファイルやビルド システムによって生成された一時ソース ファイルなど) に対しては役に立ちません。ユーザーは、これらのファイルを手動で編集できず、ツールで生成されたこのようなファイルでの違反の修正には関係ありません。

既定では、アナライザーを実行するアナライザー ドライバーによって、特定の名前、ファイル拡張子、または自動生成されたファイル ヘッダーを持つファイルが生成されたコード ファイルとして扱われます。 たとえば、.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

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

ルール違反を示す MSBuild 出力

依存プロジェクト

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

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

こちらもご覧ください