.NET API アナライザー.NET API analyzer

.NET API アナライザーは、さまざまなプラットフォームでの C# API の互換性リスクの可能性および非推奨の API の呼び出しを検出する Roslyn アナライザーです。The .NET API Analyzer is a Roslyn analyzer that discovers potential compatibility risks for C# APIs on different platforms and detects calls to deprecated APIs. 開発のすべての段階ですべての C# 開発者に役立ちます。It can be useful for all C# developers at any stage of development.

API アナライザーは、NuGet パッケージ Microsoft.DotNet.Analyzers.Compatibility として提供されています。API Analyzer comes as a NuGet package Microsoft.DotNet.Analyzers.Compatibility. プロジェクトでこれを参照すると、コードが自動的に監視されて、問題のある API 使用が示されます。After you reference it in a project, it automatically monitors the code and indicates problematic API usage. また、電球アイコンをクリックすると、考えられる修正方法の提案を得ることもできます。You can also get suggestions on possible fixes by clicking on the light bulb. ドロップダウン メニューには、警告を抑制するオプションが含まれます。The drop-down menu includes an option to suppress the warnings.

注意

.NET API アナライザーは、まだプレリリース バージョンです。The .NET API analyzer is still a pre-release version.

必須コンポーネントPrerequisites

  • Visual Studio 2017 または Visual Studio for Mac (すべてのバージョン)。Visual Studio 2017 or Visual Studio for Mac (all versions).

非推奨の API の検出Discovering deprecated APIs

非推奨の API とはWhat are deprecated APIs?

.NET ファミリは大規模な製品のセットであり、より適切に顧客のニーズに対応するため頻繁にアップグレードされています。The .NET family is a set of large products that are constantly upgraded to better serve customer needs. 当然、API が廃止されたり新しいものに置き換えられたりすることがあります。It's natural to deprecate some APIs and replace them with new ones. より優れた代替 API が存在する API は、非推奨と見なされます。An API is considered deprecated when a better alternative exists. API が非推奨であり使ってはならないことを通知する手段の 1 つは、ObsoleteAttribute 属性で API をマークすることです。One way to inform that an API is deprecated and shouldn't be used is to mark it with the ObsoleteAttribute attribute. この方法の欠点は、すべての非推奨 API に対して診断 ID が 1 つしかないことです (C# の場合、CS0612)。The disadvantage of this approach is that there is only one diagnostic ID for all obsolete APIs (for C#, CS0612). これによって、次のことが起こります。This means that:

  • ケースごとに専用のドキュメントを作成できません。It's impossible to have dedicated documents for each case.
  • 特定のカテゴリの警告を抑制できません。It's impossible to suppress certain category of warnings. すべてを抑制するか、まったく抑制しないかです。You can suppress either all or none of them.
  • 新しい非推奨 API をユーザーに通知するには、参照されているアセンブリまたは対象のパッケージを更新する必要があります。To inform users of a new deprecation, a referenced assembly or targeting package has to be updated.

API アナライザーは、DE (Deprecation Error の略) で始まる API 固有のエラー コードを使うので、個々の警告の表示を制御できます。The API Analyzer uses API-specific error codes that begin with DE (which stands for Deprecation Error), which allows control over the display of individual warnings. アナライザーによって識別された非推奨の API は、dotnet/platform-compat リポジトリで定義されています。The deprecated APIs identified by the analyzer are defined in the dotnet/platform-compat repo.

API アナライザーの使用Using the API Analyzer

非推奨の API (WebClient など) がコードで使われていると、API アナライザーは緑の波線でそれを強調します。When a deprecated API, such as WebClient, is used in a code, API Analyzer highlights it with a green squiggly line. API 呼び出しをポイントすると、次の例のように、電球アイコンと API の非推奨に関する情報が表示されます。When you hover over the API call, a light bulb is displayed with information about the API deprecation, as in the following example:

"緑の波線が表示された WebClient API と左側の電球アイコンのスクリーンショット"

[エラー一覧] ウィンドウには、非推奨の API ごとに一意の ID を含む警告が表示されます。次に示すのは DE004 の例です。The Error List window contains warnings with a unique ID per deprecated API, as shown in the following example (DE004):

"警告の ID と説明が表示されている [エラー一覧] ウィンドウのスクリーンショット""Screenshot of the Error List window showing warning's ID and description"

ID をクリックすると、API が非推奨になった理由に関する詳細情報と、使用できる代替 API に関する提案が表示される Web ページに移動します。By clicking on the ID, you go to a webpage with detailed information about why the API was deprecated and suggestions regarding alternative APIs that can be used.

強調表示されたメンバーを右クリックして [<診断 ID> の非表示] を選ぶと、警告を抑制できます。Any warnings can be suppressed by right-clicking on the highlighted member and selecting Suppress <diagnostic ID>. 警告を抑制するには 2 つの方法があります。There are two ways to suppress warnings:

警告をローカルに抑制するSuppressing warnings locally

警告をローカルに抑制するには、警告を抑制するメンバーを右クリックして、[クイック アクションとリファクタリング] > [<診断 ID> の非表示] > [ソース内] の順に選びます。To suppress warnings locally, right-click on the member you want to suppress warnings for and then select Quick Actions and Refactorings > Suppress diagnostic ID<diagnostic ID> > in Source. #pragma 警告プリプロセッサ ディレクティブが、定義されているスコープ内のソース コードに追加されます。"#pragma warning disable で囲まれたコードのスクリーンショット"The #pragma warning preprocessor directive is added to your source code in the scope defined: "Screenshot of code framed with #pragma warning disable"

警告をグローバルに抑制するSuppressing warnings globally

警告をグローバルに抑制するには、警告を抑制するメンバーを右クリックして、[クイック アクションとリファクタリング] > [<診断 ID> の非表示] > [抑制ファイル内] の順に選びます。To suppress warnings globally, right-click on the member you want to suppress warnings for and then select Quick Actions and Refactorings > Suppress diagnostic ID<diagnostic ID> > in Suppression File.

"緑の波線が表示された WebClient API と左側の電球アイコンのスクリーンショット"

最初の抑制後に、GlobalSuppressions.cs ファイルがプロジェクトに追加されます。A GlobalSuppressions.cs file is added to your project after the first suppression. 新しいグローバル抑制は、このファイルに追加されます。New global suppressions are appended to this file.

"緑の波線が表示された WebClient API と左側の電球アイコンのスクリーンショット"

グローバル抑制は、プロジェクト間で API 使用の一貫性を確保するのに推奨される方法です。Global suppression is the recommended way to ensure consistency of API usage across projects.

クロスプラットフォームの問題の検出Discovering cross-platform issues

非推奨の API と同様に、アナライザーはクロスプラットフォームではないすべての API を識別します。Similar to deprecated APIs, the analyzer identifies all APIs that are not cross-platform. たとえば、Console.WindowWidth は Windows では動作しますが、Linux や macOS では動作しません。For example, Console.WindowWidth works on Windows but not on Linux and macOS. 診断 ID は、[エラー一覧] ウィンドウに表示されます。The diagnostic ID is shown in the Error List window. 右クリックして [クイック アクションとリファクタリング] を選ぶことで、その警告を抑制することができます。You can suppress that warning by right-clicking and selecting Quick Actions and Refactorings. 2 つのオプション (非推奨のメンバーを使い続けて警告を抑制するか、まったく使わない) がある非推奨の場合とは異なり、特定のプラットフォーム用にのみコードを開発している場合は、コードを実行する予定のない他のすべてのプラットフォームですべての警告を抑制できます。Unlike deprecation cases where you have two options (either keep using the deprecated member and suppress warnings or not use it at all), here if you're developing your code only for certain platforms, you can suppress all warnings for all other platforms you don't plan to run your code on. そのために必要なことは、プロジェクト ファイルを編集し、無視するすべてのプラットフォームを列記した PlatformCompatIgnore プロパティを追加するだけです。To do so, you just need to edit your project file and add the PlatformCompatIgnore property that lists all platforms to be ignored. 指定できる値は、LinuxmacOSWindows です。The accepted values are: Linux, macOS, and Windows.

<PropertyGroup>
    <PlatformCompatIgnore>Linux;macOS</PlatformCompatIgnore>
</PropertyGroup>

コードが複数のプラットフォームを対象にしていて、一部のプラットフォームでサポートされていない API を利用したい場合は、if ステートメントを使ってコードのその部分を保護できます。If your code targets multiple platforms and you want to take advantage of an API not supported on some of them, you can guard that part of the code with an if statement:

if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
{
     var w = Console.WindowWidth;
     // More code
}

また、対象のフレームワーク/オペレーティング システムごとに条件付きでコンパイルすることもできますが、現在は手動で行う必要があります。You can also conditionally compile per target framework/operating system, but you currently need to do that manually.

サポートされている診断Supported diagnostics

現時点では、アナライザーは次のケースを処理します。Currently, the analyzer handles the following cases:

  • PlatformNotSupportedException (PC001) をスローする .NET Standard API の使用。Usage of a .NET Standard API that throws PlatformNotSupportedException (PC001).
  • .NET Framework 4.6.1 (PC002) では利用できない .NET Standard API の使用。Usage of a .NET Standard API that isn't available on the .NET Framework 4.6.1 (PC002).
  • UWP (PC003) に存在しないネイティブ API の使用。Usage of a native API that doesn’t exist in UWP (PC003).
  • 非推奨 (DEXXXX) としてマークされている API の使用。Usage of an API that is marked as deprecated (DEXXXX).

CI マシンCI machine

これらの診断はすべて、IDE で利用できるだけでなく、プロジェクトのビルドの一部としてコマンド ラインでも利用でき、これには CI サーバーが含まれます。All these diagnostics are available not only in the IDE, but also on the command line as part of building your project, which includes the CI server.

構成Configuration

ユーザーは、診断の処理方法を決定します (警告、エラー、提案、オフ)。The user decides how the diagnostics should be treated: as warnings, errors, suggestions, or to be turned off. たとえば、設計者は、互換性の問題をエラーとして扱い、一部の非推奨の API の呼び出しでは警告を生成し、それ以外については提案を生成するだけにする、といったことを決定できます。For example, as an architect, you can decide that compatibility issues should be treated as errors, calls to some deprecated APIs generate warnings, while others only generate suggestions. これを、診断 ID 別およびプロジェクト別に構成できます。You can configure this separately by diagnostic ID and by project. そのためには、ソリューション エクスプローラーで、プロジェクトの [依存関係] ノードに移動します。To do so in Solution Explorer, navigate to the Dependencies node under your project. ノード [依存関係] > [アナライザー] > [Microsoft.DotNet.Analyzers.Compatibility] を展開します。Expand the nodes Dependencies > Analyzers > Microsoft.DotNet.Analyzers.Compatibility. 診断 ID を右クリックし、[ルール セットの重要度を設定] を選んで、目的のオプションを選びます。Right click on the diagnostic ID, select Set Rule Set Severity and pick the desired option.

"診断とルール セットの重要度のポップアップ ダイアログが表示されているソリューション エクスプローラーのスクリーンショット"

関連項目See also