.NET Portability AnalyzerThe .NET Portability Analyzer

ライブラリでマルチプラットフォームをサポートしたい場合や、Want to make your libraries support multi-platform? アプリケーションで他の .NET の実装とプロファイル (.NET Core、.NET Standard、UWP、Xamarin for iOS/Android/Mac など) との互換性を確保するのに必要な作業量を知りたい場合は、Want to see how much work is required to make your application compatible with other .NET implementations and profiles, including .NET Core, .NET Standard, UWP, and Xamarin for iOS, Android, and Mac? .NET Portability Analyzer が役立ちます。このツールを使用すると、アセンブリを分析して、プログラムが .NET 実装全体でどの程度柔軟な構造になっているかについて詳細なレポートを生成することができます。The .NET Portability Analyzer is a tool that provides you with a detailed report on how flexible your program is across .NET implementations by analyzing assemblies. Visual Studio 拡張機能として提供されている Portability Analyzer ではプロジェクトに従ってアセンブリが分析され、ApiPort コンソール アプリとして提供されている Portability Analyzer では指定したファイルまたはディレクトリでアセンブリが分析されます。The Portability Analyzer is offered as a Visual Studio Extension, which analyzes assembly per project, and as a ApiPort console app, which analyzes assemblies by specified files or directory.

一般的なターゲット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 プラットフォーム/バージョンです。You can configure it in Visual Studio via Analyze > Portability Analyzer Settings and select your Target Platforms, which is the .NET platforms/versions that you want to evaluate the portability gaps comparing with the platform/version that your current assembly is built with.

Portability のスクリーンショット

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.

ソリューション エクスプローラーからの Portability Analyzer

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

移植性の詳細

レポートの [Details](詳細) セクションには、ターゲット プラットフォームのいずれかにない API が一覧表示されます。The Details section of the report lists the APIs missing from one of the Target 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: recommended API or technology to change to. 現時点では、このフィールドは、多くの API で空または期限切れです。Currently, this field is empty or out of date for a lot of APIs. API の数が多いので、最新の状態に保つのは大変な作業です。Due to the large number of APIs, we have big challenge to keep it up. お客様に役に立つ情報を提供する代わりのソリューションを探しています。We are looking at alternate solutions to provide helpful information to customers.

足りないアセンブリMissing Assemblies

移植性の詳細

レポートには [Missing Assemblies](足りないアセンブリ) セクションが含まれる場合があります。You may find a Missing Assemblies section in your report. そこに示されているアセンブリの一覧は、分析されたアセンブリによって参照されていますが、分析されませんでした。It tells you that this list of assemblies 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 API level detailed portability report for it. サード パーティのライブラリである場合は、ターゲット プラットフォームをサポートしている新しいバージョンがあるかどうかを調べます。If it's third party library, looks for if they have newer version supporting your target platform. ある場合は、新しいバージョンへの移行を検討します。If so, consider moving to the newer version. 最終的に、この一覧には、アプリが依存していて、ターゲット プラットフォームをサポートするバージョンがあることが確認された、すべてのサード パーティ アセンブリが含まれることが期待されます。Eventually, you would expect this list includes all the third party assemblies that your app depends on and confirmed that they 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.