The goal of these tools is to help identify possible problem areas in an assembly and help direct targeted testing. You can click on the following link to view chinese instrucions to [api protability tool ] https://www.cnblogs.com/heyuquan/p/dotnet-migration-to-dotnetcore.html
The repository contains the source code for .NET Portability Analyzer tools and dependencies：https://github.com/Microsoft/dotnet-apiport
For example, you may analyze some dll, you can input [apiport analyze -f Microsoft.Exchange.AirSync.dll ]. Then you can get a report.
Backgroud
Migraing existing .netfx project to .netcore version is very complex task, especially since some APIs are not yet supported on both platforms. The difference between the two class libraries is difficult to identify by human beings. Microsoft designed a tool for us ahead of time: .NET Portability Analytics. With this tool we can quickly determine the matching of the API used by the .net framework program to the .net core, and give detailed differentiated reports, which do not give detailed upgrade recommendations when the United States and China are inadequate. During the upgrade process, if you want to learn more about API differences and details, you can refer to:
There are two ways to install this tool, one is an extension in Visual Studio (this tool only supports Visual Studio 2017 and 2019 as of 2021.29, the latest 2022 RC version does not), and the other is the CMD tool (CLI version)
Visual Studio Extensions
- Open Visual Studio>Tools>Extension and update.
- Search .NET Portability Analyzer and install.Of course, you can also download extensions directly to the github repository.（https://github.com/Microsoft/dotnet-apiport/tree/dev/docs/VSExtension）Click How to obtain-Visual Studio extension gallery。
Usage-Analyze solution or project
You can run the Portability Analyzer over a Visaul Studio solution or project by performing the following:
- Open a project or solution in Visual Studio
- Open Solution Explorer
- Right-click on the project or solution you want to analyze
- Select "Analyze Assembly Portability"
After the analysis complete, if there are any APIs that are not supported on the selected platforms, check the "Output" window. There should be some information messages containing the API that is not supported and the line mapping in source code. If you double-click on that message, it will take you to that location in source.
Usage-Analyze a compiled binary
You can perform a portability analysis over compiled binaries (.dll or .exe) files.
- Click the "Analyze" menu item in the main toolbar
- Select "Analyze Assembly Portability"
- Choose binaries to analyze
View/Save generated reports
You can view or save previously generated reports in your Visual Studio session by performing the following:
- Click the "Analyze" menu item in the main toolbar
- Select "View analysis reports"
- A tool window should pop up with all your reports
Configuration
The .NET Portability Analyzer can be configured through the Options window. Here, you can choose what .NET platforms to perform your analysis against, and the file name, location and formats of the analysis report.
You can access the settings page via one of three methods:
- In Solution Explorer
- Right-click on a project or solution
- Select "Portability Analyzer Settings"
- Under "Analyze" in main toolbar
- Select "Portability Analyzer Settings"
- Under "Tools" in main toolbar
- Select "Options..."
- Go to the ".NET Portability Analyzer" node
Console Application Version(The version used by author）
You must download Apiport CLI(https://github.com/Microsoft/dotnet-apiport)
If you input apiprot --helper, you can see the following context:
The console tool helps you determine how flexible your application is. The tool understands the following commands:
| Command | Description | Example |
|---|---|---|
| analyze | Analyzes the portability of an application | Examples |
| listTargets | Lists .NET platforms available for analysis | ApiPort.exe listTargets |
| listOutputFormats | Lists available report output formats | ApiPort.exe listOutputFormats |
| docId | Searches for matching docIds | ApiPort.exe docId |
| dump | Outputs the analysis request that will be sent to the service | Example |
For examples, you can analyze a *.dll, you can get api analysis report.
ApiPort.exe analyze Scenarios
Arguably the most important function of the tool is its ability to analyze an assembly. This can take in a file, collection of files, or a directory of assemblies.
Analyzing a file against specific targets and outputting an HTML report
ApiPort.exe analyze -f Foo.dll -t ".NET Framework, Version=4.6.2" -t ".NET Standard, Version=1.6" -r HTML -o AnalysisReport.html
The -f flag followed by a path represents the file or directory that the analysis should be performed on; in this case, it is Foo.dll. The multiple uses of -t followed by target names tells the tool what .NET platforms we want to analyze the input assembly(ies) against. -r is the output format of the report. -o is the output name for that report.
So, our analysis will be performed on Foo.dll against .NET Framework, Version=4.6.2 and .NET Standard, Version=1.6 and output as an HTML file, AnalysisReport.html.
Analyzing a directory against the default targets and outputting default report format
ApiPort.exe analyze -f C:\git\Application\bin\Debug
This will analyze all assemblies that exist under C:\git\Application\bin\Debug recursively, and analyzes those assemblies against the default .NET platforms. (Note: The default platforms can be obtained by running ApiPort.exe listTargets and looking for targets that have an (*) in them.)
Analyzing a directory and show breaking changes
ApiPort.exe analyze -f C:\git\Application\bin\Debug -b
The -b flag will show any APIs that may have different behavior between versions of .NET Framework due to breaking changes that have been made. The entire list of breaking changes in .NET Framework can be found by examining Application Compatibility in the .NET Framework. For the list of breaking changes we analyze against, look here.
Analyzing a directory and show any non-portable APIs
ApiPort.exe analyze -f C:\git\Application\bin\Debug -p
The -p flag will highlight any APIs that are not portable against the default target .NET platforms. (No explicit -t arguments were specified, so we use the default targets.)
Analyzing a directory and show APIs that may cause PlatformNotSupportedException or NotImplementedException
ApiPort.exe analyze -f C:\git\Application\bin\Debug -x
The -x flag or --showExceptionApis will give a list of APIs currently being used that may throw on the target .NET Platforms. In JSON reports, this list will be labeled "ThrowingMembers" and contain information on which platforms throw which exceptions and group them together by DocID. In Excel reports, a tab labeled "Exceptions" will be added if there are exception throwing APIs found and will include information on assembly name, throwing API DocID, the exception thrown, and the corresponding target platforms that are thrown on. Currently this this argument is only supported with remotely generated JSON and Excel reports.
Using .NET Core application
The portability analyzer has a version that targets .NET Core. Possible reasons for using the .NET Core application include:
Compiling, Debugging and Running
From Commandline
- Execute build.cmd
- Execute dotnet.exe .\bin\Release\ApiPort\netcoreapp1.0\ApiPort.dll [Any other arguments to ApiPort]
In Visual Studio 2017
Alternate modes
The tool by default will gather the results and submit to a webservice that will analyze the data to determine which APIs need to be addressed. There are two alternate modes that can be used to alter this workflow.
See the data being transmitted
ApiPort.exe dump -f [path to file or directory]
The dump command will output the data that would otherwise be sent to the service. This is a good option if you would like to see what data will be collected. A file, which by default is ApiPortAnalysis.json, will be created with the information that would sent to the .NET Portability service.
Run the tool in an offline mode
Another option is to enable full offline access. This mode will not get automatic updates and no official releases of it are available. In order to use this mode, the solution must be manually built. To do so, please follow these steps:
- Clone the project: git clone https://github.com/Microsoft/dotnet-apiport
- Compile using the build.cmd or build.sh script as normal
- If in Visual Studio, set the project ApiPort.Offline as the startup project, or if from command line, go to bin[Configuration]\ApiPort.Offline\net46\win7-x64 and run ApiPort.exe from this directory.
There is a .NET Core build of the offline mode, but HTML reports will not be generated when running on .NET Core. Other than that, the functionality is expected to be the same.