概要

適用対象:yesVisual Studio noVisual Studio for Mac noVisual Studio Code

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

重要度レベルを構成する

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

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

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

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

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

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

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

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

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

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

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

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

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. 電球メニューから、重大度レベルにカーソルを合わせ、変化をプレビューします。その後、重大度を構成するオプションを選択します。

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

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

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

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

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

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

    ルールの重要度を 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" は、重要度[エラー] を示します
  • 三角形の中の "!" は、重要度[警告] を示します
  • 円の中の "i" は、重要度[情報] を示します
  • 白抜きの円の中の "i" は、重要度[非表示] を示します
  • 円の中の下向き矢印は、診断が抑制されていることを示します。

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

既存のルール セット ファイルを 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. 重要度を設定するルールが含まれているアセンブリを展開します。

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

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

    ヒント

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

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

  1. 次のいずれかの方法で、アクティブなルール セット ファイルを開きます。

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

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

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

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

    注意

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

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

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

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

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

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

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

関連項目