.NET Portability AnalyzerThe .NET Portability Analyzer

ライブラリでマルチプラットフォームをサポートしたい場合や、Want to make your libraries support multi-platform? .NET Framework アプリケーションを .NET Core で実行するのに必要な作業量を知りたい場合、Want to see how much work is required to make your .NET Framework application run on .NET Core? .NET Portability Analyzer というツールがアセンブリを分析し、指定された対象の .NET プラットフォームでアプリケーションまたはライブラリを移植するために不足している .NET API の詳細なレポートを提供します。The .NET Portability Analyzer is a tool that analyzes assemblies and provides a detailed report on .NET APIs that are missing for the applications or libraries to be portable on your specified targeted .NET platforms. Visual Studio 拡張機能として提供されている Portability Analyzer ではプロジェクトごとにアセンブリが 1 つ分析され、ApiPort コンソール アプリとして提供されている Portability Analyzer では指定したファイルまたはディレクトリごとにアセンブリが分析されます。The Portability Analyzer is offered as a Visual Studio Extension, which analyzes one assembly per project, and as a ApiPort console app, which analyzes assemblies by specified files or directory.

.NET Core などの新しいプラットフォームを対象とするようにプロジェクトを変換したら、Roslyn ベースの API Analyzer ツールを使用して、PlatformNotSupportedException の例外とその他の互換性の問題をスローする API を特定することができます。Once you've converted your project to target the new platform, like .NET Core, you can use the Roslyn-based API Analyzer tool to identify APIs throwing PlatformNotSupportedException exceptions and other compatibility issues.

一般的なターゲットCommon targets

  • .NET Core: モジュール型の設計で、side-by-side を採用しており、クロスプラットフォームのシナリオを対象としています。.NET Core: Has a modular design, employs side-by-side, and targets cross-platform scenarios. side-by-side 機能により、他のアプリに影響を与えることなく新しい .NET Core バージョンを導入することができます。Side-by-side allows you to adopt new .NET Core versions without breaking other apps. クロスプラットフォームをサポートする .NET Core にアプリを移植することが目的である場合は、これが推奨されるターゲットです。If your goal is to port your app to .NET Core supporting cross-platforms, this is the recommended target.
  • .NET Standard: .NET のすべての実装で使用できる .NET Standard API が含まれています。.NET Standard: Includes the .NET Standard APIs available on all .NET implementations. .NET でサポートされるすべてのプラットフォームでライブラリを実行させることが目的である場合は、これが推奨されるターゲットです。If your goal is to make your library to run on all .NET supported platforms, this is recommended target.
  • ASP.NET Core: .NET Core 上に構築された最新の Web フレームワークです。ASP.NET Core: A modern web-framework built on .NET Core. 複数のプラットフォームをサポートするために .NET Core に Web アプリを移植することが目的である場合は、これが推奨されるターゲットです。If your goal is to port your web app to .NET Core to support multiple platforms, this is the recommended target.
  • .NET Core とプラットフォーム拡張機能: Windows 互換機能パックに加えて .NET Core API が含まれます。 .NET Framework で利用可能なテクノロジの多くが提供されます。.NET Core + Platform Extensions: Includes the .NET Core APIs in addition to the Windows Compatibility Pack, which provides many of the .NET Framework available technologies. Windows で .NET Framework から .NET Core にアプリを移植する場合は、これが推奨されるターゲットです。This is a recommended target for porting your app from .NET Framework to .NET Core on Windows.
  • .NET Standard とプラットフォーム拡張機能: Windows 互換機能パックに加えて .NET Standard API が含まれます。 .NET Framework で利用可能なテクノロジの多くが提供されます。.NET Standard + Platform Extensions: Includes the .NET Standard APIs in addition to the Windows Compatibility Pack, which provides many of the .NET Framework available technologies. Windows で .NET Framework から .NET Core にライブラリを移植する場合は、これが推奨されるターゲットです。This is a recommended target for porting your library from .NET Framework to .NET Core on Windows.

.NET Portability Analyzer の使用方法How to use the .NET Portability Analyzer

Visual Studio で .NET Portability Analyzer を使用するには、Visual Studio Marketplace から拡張機能をダウンロードし、インストールする必要があります。To begin using the .NET Portability Analyzer in Visual Studio, you first need to download and install the extension from the Visual Studio Marketplace. Visual Studio 2017 以降のバージョンで機能します。It works on Visual Studio 2017 and later versions. Visual Studio で構成するには、 [Analyze](分析) > [Portability Analyzer Settings](Portability Analyzer の設定) でターゲット プラットフォームを選択します。ターゲット プラットフォームとは、アセンブリが現在ビルドされているプラットフォーム/バージョンと比較をする、移植における違いを評価する .NET プラットフォーム/バージョンです。Configure it in Visual Studio via Analyze > Portability Analyzer Settings and select your Target Platforms, which are the .NET platforms/versions that you want to evaluate the portability gaps comparing with the platform/version that your current assembly is built with.

移植性アナライザーのスクリーンショット。

ApiPort コンソール アプリケーションを使用して、ApiPort リポジトリからダウンロードすることもできます。You can also use the ApiPort console application, download it from ApiPort repository. listTargets コマンド オプションを使って使用可能なターゲットの一覧を表示した後、-t または --target コマンド オプションを指定することによってターゲット プラットフォームを選択できます。You can use listTargets command option to display the available target list, then pick target platforms by specifying -t or --target command option.

移植性を分析するAnalyze portability

Visual Studio でプロジェクト全体を分析するには、ソリューション エクスプローラーでプロジェクトを右クリックし、 [Analyze Assembly Portability](アセンブリの移植性を分析する) を選択します。To analyze your entire project in Visual Studio, right-click on your project in Solution Explorer and select Analyze Assembly Portability. または、 [分析] メニューで [Analyze Assembly Portability] (アセンブリの移植性を分析) を選択します。Otherwise, go to the Analyze menu and select Analyze Assembly Portability. そこから、プロジェクトの実行可能ファイルまたは DLL を選択します。From there, select your project's executable or DLL.

ソリューション エクスプローラーからの移植性アナライザーのスクリーンショット。

ApiPort コンソール アプリを使うこともできます。You can also use the ApiPort console app.

  • 現在のディレクトリを分析するには、次のコマンドを入力します。ApiPort.exe analyze -f .Type the following command to analyze the current directory: ApiPort.exe analyze -f .
  • 特定の .dll ファイルの一覧を分析するには、次のコマンドを入力します。ApiPort.exe analyze -f first.dll -f second.dll -f third.dllTo analyze a specific list of .dll files, type the following command: ApiPort.exe analyze -f first.dll -f second.dll -f third.dll
  • 詳細なヘルプを表示するには ApiPort.exe -? を実行しますRun ApiPort.exe -? to get more help

自分が所有していて移植したいすべての関連する exe と dll ファイルを含め、アプリが依存しているけれども自分で所有しているのではなく移植できないファイルを除外することをお勧めします。It is recommended that you include all the related exe and dll files that you own and want to port, and exclude the files that your app depends on, but you don't own and can't port. これにより、最も関連のある移植性レポートが得られます。This will give you most relevant portability report.

移植性の結果を表示して解釈するView and interpret portability result

レポートには、ターゲット プラットフォームによってサポートされていない API のみが表示されます。Only APIs that are unsupported by a Target Platform appear in the report. Visual Studio で分析を実行すると、.NET 移植性レポート ファイルのリンクがポップアップ表示されます。After running the analysis in Visual Studio, you'll see your .NET Portability report file link pops up. ApiPort コンソール アプリを使った場合は、.NET 移植性レポートは指定した形式のファイルとして保存されます。If you used the ApiPort console app, your .NET Portability report is saved as a file in the format you specified. 既定では、現在のディレクトリの Excel ファイル ( .xlsx) です。The default is in an Excel file (.xlsx) in your current directory.

移植性の概要Portability Summary

移植性の概要のスクリーンショット。

レポートの [Portability Summary](移植性の概要) セクションでは、実行に含まれる各アセンブリの移植性の割合が示されます。The Portability Summary section of the report shows the portability percentage for each assembly included in the run. 前の例では、svcutil アプリで使われている .NET Framework API の 71.24% が、.NET Core とプラットフォーム拡張機能で使用できます。In the previous example, 71.24% of the .NET Framework APIs used in the svcutil app are available in .NET Core + Platform Extensions. 複数のアセンブリに対して .NET Portability Analyzer ツールを実行した場合、移植性の概要レポートでは各アセンブリが 1 行に表示されます。If you run the .NET Portability Analyzer tool against multiple assemblies, each assembly should have a row in the Portability Summary report.

説明Details

移植性の詳細のスクリーンショット。

レポートの [説明] セクションには、選択したターゲット プラットフォームのいずれからも欠落している API が一覧表示されます。The Details section of the report lists the APIs missing from any of the selected Targeted Platforms.

  • [Target type](ターゲットの型): 型にターゲット プラットフォームに存在しない API がありますTarget type: the type has missing API from a Target Platform
  • [Target member](ターゲットのメンバー): メンバーがターゲット プラットフォームにありませんTarget member: the method is missing from a Target Platform
  • [Assembly name](アセンブリ名): ない API が存在する .NET Framework アセンブリです。Assembly name: the .NET Framework assembly that the missing API lives in.
  • 選択されているターゲット プラットフォームごとに 1 つの列 (".NET Core" など): [Not supported](サポートされていません) という値は、その API がこのターゲット プラットフォームでサポートされていないことを意味します。Each of the selected Target Platforms is one column, such as ".NET Core": "Not supported" value means the API is not supported on this Target Platform.
  • [Recommended Changes](推奨される変更): それに変更することが推奨される API またはテクノロジです。Recommended Changes: the recommended API or technology to change to. 現時点では、このフィールドは空であるか、多くの API に対応しなくなっています。Currently, this field is empty or out of date for many APIs. API の数は多く、最新の状態に保つために尽力しているところです。Due to the large number of APIs, we have a significant challenge to keep it up-to-date. お客様に役に立つ情報を提供する代わりの解決策を検討中です。We are looking at alternative solutions to provide helpful information to customers.

足りないアセンブリMissing Assemblies

足りないアセンブリのスクリーンショット。

レポートには [Missing Assemblies](足りないアセンブリ) セクションが含まれる場合があります。You may find a Missing Assemblies section in your report. このセクションには、分析されたアセンブリによって参照されている、分析されていないアセンブリの一覧が示されます。This section contains a list of assemblies that are referenced by your analyzed assemblies and were not analyzed. 自分が所有しているアセンブリの場合は、API Portability Analyzer の実行にそれを含めて、そのアセンブリに関する API レベルの詳細な移植性レポートを取得できます。If it's an assembly that you own, include it in the API portability analyzer run so that you can get a detailed, API-level portability report for it. それがサードパーティ製のライブラリである場合は、ご自分のターゲット プラットフォームをサポートする新しいバージョンがあるかどうかを確認し、その新しいバージョンに移行することを検討してください。If it's a third-party library, check if there is a newer version that supports your target platform, and consider moving to the newer version. この一覧には最終的に、アプリが依存し、ターゲット プラットフォームをサポートするバージョンのすべてのサード パーティ アセンブリが含まれるようにします。Eventually, the list should include all the third-party assemblies that your app depends on that have a version supporting your target platform.

.NET Portability Analyzer の詳細については、GitHub ドキュメントにアクセスし、Channel 9 動画の「A Brief Look at the .NET Portability Analyzer」 (.NET Portability Analyzer の概要) をご覧ください。For more information on the .NET Portability Analyzer, visit the GitHub documentation and A Brief Look at the .NET Portability Analyzer Channel 9 video.