.NET Portability Analyzer

ライブラリでマルチプラットフォームをサポートしたい場合や、 .NET Framework アプリケーションを .NET Core で実行するのに必要な作業量を知りたい場合、 .NET Portability Analyzer というツールがアセンブリを分析し、指定された対象の .NET プラットフォームでアプリケーションまたはライブラリを移植するために不足している .NET API の詳細なレポートを提供します。 Portability Analyzer は、指定したファイルまたはディレクトリによってアセンブリを分析する コンソール アプリ です。

.NET Core などの新しいプラットフォームを対象とするようにプロジェクトを変換したら、Roslyn ベースのプラットフォーム互換性アナライザーを使用して、PlatformNotSupportedException の例外とその他の互換性の問題をスローする API を特定することができます。

一般的なターゲット

• .NET: モジュール設計があり、サイド バイ サイド インストールをサポートし、クロスプラットフォーム シナリオを対象としています。 サイド バイ サイド インストールを使用すると、他のアプリを中断することなく、新しい .NET バージョンを採用できます。 目的がアプリを .NET に移植し、複数のプラットフォームをサポートする場合は、これが推奨されるターゲットです。
• .NET Standard: .NET のすべての実装で使用できる .NET Standard API が含まれています。
• ASP.NET Core: .NET 上に構築された最新の Web フレームワーク。 複数のプラットフォームをサポートするために Web アプリを .NET (Core) に移植することが目的の場合は、これが推奨されるターゲットです。
• .NET + プラットフォーム拡張機能: Windows 固有の .NET Framework テクノロジの多くを提供する Windows 互換機能パックに加えて、.NET API が含まれています。
• .NET Standard + プラットフォーム拡張機能: Windows 固有の .NET Framework テクノロジの多くを提供する Windows 互換パックに加えて、.NET Standard API が含まれています。

.NET Portability Analyzer の使用方法

Visual Studio で .NET Portability Analyzer を使用開始するには、まず、dotnet-apiport プロジェクトを複製してビルドする必要があります。 これは、Visual Studio 2017 と Visual Studio 2019 のバージョンで機能します。

ソリューション全体のビュー

多くのプロジェクトでソリューションを分析する際に便利な手順は、依存関係を視覚化して、アセンブリのどのサブセットが何に依存するかを理解することです。 一般的には、依存関係グラフのリーフ ノードで始まるボトムアップ アプローチで分析結果を適用することが推奨されます。

これを取得するには、次のコマンドを実行します。

ApiPort.exe analyze -r DGML -f [directory or file]

この結果を Visual Studio で開くと次のようになります。

移植性を分析する

次のコマンドを入力して、現在のディレクトリを分析します。

ApiPort.exe analyze -f .

.dll ファイルの特定の一覧を分析するには、次のコマンドを入力します。

ApiPort.exe analyze -f first.dll -f second.dll -f third.dll

特定のバージョンをターゲットにするには、-t パラメーターを使用します。

ApiPort.exe analyze -t ".NET, Version=5.0" -f .

詳細なヘルプを表示するには ApiPort.exe -? を実行します。

自分が所有していて移植したいすべての関連する .exe と .dll ファイルを含め、アプリが依存しているけれども自分で所有しているのではなく移植できないファイルを除外することをお勧めします。 これにより、最も関連のある移植性レポートが得られます。

移植性の結果を表示して解釈する

レポートには、ターゲット プラットフォームによってサポートされていない API のみが表示されます。 .NET 移植性レポートは、指定した形式でファイルとして保存されます。 既定では、現在のディレクトリの Excel ファイル ( .xlsx) です。

移植性の概要

レポートの [Portability Summary](移植性の概要) セクションでは、実行に含まれる各アセンブリの移植性の割合が示されます。 前の例では、svcutil アプリで使われている .NET Framework API の 71.24% が、.NET Core とプラットフォーム拡張機能で使用できます。 複数のアセンブリに対して .NET Portability Analyzer ツールを実行した場合、移植性の概要レポートでは各アセンブリが 1 行に表示されます。

説明

レポートの [説明] セクションには、選択したターゲット プラットフォームのいずれからも欠落している API が一覧表示されます。

• ターゲットの種類: 型にターゲット プラットフォームの API がありません。
• ターゲット メンバー: ターゲット プラットフォームにメソッドがありません。
• [Assembly name](アセンブリ名): ない API が存在する .NET Framework アセンブリです。
• 選択されているターゲット プラットフォームごとに 1 つの列 (".NET Core" など): [Not supported](サポートされていません) という値は、その API がこのターゲット プラットフォームでサポートされていないことを意味します。
• [Recommended Changes](推奨される変更): それに変更することが推奨される API またはテクノロジです。 現時点では、このフィールドは空であるか、多くの API に対応しなくなっています。 API の数が多いため、最新の状態に保つことは大きな課題です。

アセンブリが見つかりません

レポートに「見つからないアセンブリ」セクションが表示される場合があります。 このセクションには、分析されたアセンブリによって参照されている、分析されていないアセンブリの一覧が示されます。 自分が所有しているアセンブリの場合は、API Portability Analyzer の実行にそれを含めて、そのアセンブリに関する API レベルの詳細な移植性レポートを取得できます。 それがサードパーティ製のライブラリである場合は、ご自分のターゲット プラットフォームをサポートする新しいバージョンがあるかどうかを確認し、その新しいバージョンに移行することを検討してください。 この一覧には最終的に、アプリが依存し、ターゲット プラットフォームをサポートするバージョンのすべてのサード パーティ アセンブリが含まれるようにします。

関連項目

.NET Portability Analyzer の詳細については、GitHub のドキュメントを参照してください。