diff --git a/docs/standard/analyzers/media/portability-analyzer/portability-screenshot.png b/docs/standard/analyzers/media/portability-analyzer/portability-screenshot.png deleted file mode 100644 index 2ded7a27fae26..0000000000000 Binary files a/docs/standard/analyzers/media/portability-analyzer/portability-screenshot.png and /dev/null differ diff --git a/docs/standard/analyzers/media/portability-analyzer/portability-solution-explorer.png b/docs/standard/analyzers/media/portability-analyzer/portability-solution-explorer.png deleted file mode 100644 index 28583eefb07bf..0000000000000 Binary files a/docs/standard/analyzers/media/portability-analyzer/portability-solution-explorer.png and /dev/null differ diff --git a/docs/standard/analyzers/portability-analyzer.md b/docs/standard/analyzers/portability-analyzer.md index 2a5074040b4ae..2897ee2935b2c 100644 --- a/docs/standard/analyzers/portability-analyzer.md +++ b/docs/standard/analyzers/portability-analyzer.md @@ -1,44 +1,37 @@ --- title: The .NET Portability Analyzer - .NET description: Learn how to use the .NET Portability Analyzer tool to evaluate how portable your code is among the various .NET implementations, including .NET Core, .NET Standard, and UWP. -ms.date: 04/22/2022 -ms.assetid: 0375250f-5704-4993-a6d5-e21c499cea1e +ms.date: 01/19/2025 --- # The .NET Portability Analyzer [!INCLUDE[](~/includes/deprecating-api-port.md)] -Want to make your libraries support multi-platform? Want to see how much work is required to make your .NET Framework application run on .NET Core? The [.NET Portability Analyzer](https://github.com/microsoft/dotnet-apiport) 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. The Portability Analyzer is offered as a [Visual Studio Extension](https://marketplace.visualstudio.com/items?itemName=ConnieYau.NETPortabilityAnalyzer), which analyzes one assembly per project, and as an [ApiPort console app](https://aka.ms/apiportdownload), which analyzes assemblies by specified files or directory. +Want to make your libraries support multi-platform? Want to see how much work is required to make your .NET Framework application run on .NET Core? The [.NET Portability Analyzer](https://github.com/microsoft/dotnet-apiport) 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. The Portability Analyzer is a [console app](https://aka.ms/apiportdownload) that analyzes assemblies by specified files or directory. Once you've converted your project to target the new platform, like .NET Core, you can use the Roslyn-based [Platform compatibility analyzer](platform-compat-analyzer.md) to identify APIs that throw exceptions and other compatibility issues. ## Common targets -- [.NET Core](../../core/introduction.md): Has a modular design, supports side-by-side installation, and targets cross-platform scenarios. Side-by-side installation allows you to adopt new .NET Core versions without breaking other apps. If your goal is to port your app to .NET Core and support multiple platforms, this is the recommended target. -- [.NET Standard](../net-standard.md): Includes the .NET Standard APIs available on all .NET implementations. If your goal is to make your library run on all .NET supported platforms, this is recommended target. -- [ASP.NET Core](/aspnet/core): A modern web-framework built on .NET Core. If your goal is to port your web app to .NET Core to support multiple platforms, this is the recommended target. -- .NET Core + [Platform Extensions](../../core/porting/windows-compat-pack.md): Includes the .NET Core APIs in addition to the Windows Compatibility Pack, which provides many of the .NET Framework available technologies. This is a recommended target for porting your app from .NET Framework to .NET Core on Windows. -- .NET Standard + [Platform Extensions](../../core/porting/windows-compat-pack.md): Includes the .NET Standard APIs in addition to the Windows Compatibility Pack, which provides many of the .NET Framework available technologies. This is a recommended target for porting your library from .NET Framework to .NET Core on Windows. +- [.NET](../../core/introduction.md): Has a modular design, supports side-by-side installation, and targets cross-platform scenarios. Side-by-side installation allows you to adopt new .NET versions without breaking other apps. If your goal is to port your app to .NET and support multiple platforms, this is the recommended target. +- [.NET Standard](../net-standard.md): Includes the .NET Standard APIs available on all .NET implementations. +- [ASP.NET Core](/aspnet/core): A modern web-framework built on .NET. If your goal is to port your web app to .NET (Core) to support multiple platforms, this is the recommended target. +- .NET + [Platform Extensions](../../core/porting/windows-compat-pack.md): Includes the .NET APIs in addition to the Windows Compatibility Pack, which provides many of the Windows-specific .NET Framework technologies. +- .NET Standard + [Platform Extensions](../../core/porting/windows-compat-pack.md): Includes the .NET Standard APIs in addition to the Windows Compatibility Pack, which provides many of the Windows-specific .NET Framework technologies. ## How to use the .NET Portability Analyzer -To begin using the .NET Portability Analyzer in Visual Studio, you first need to download and install the extension from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ConnieYau.NETPortabilityAnalyzer). It works on Visual Studio 2017 and Visual Studio 2019 versions. +To begin using the .NET Portability Analyzer in Visual Studio, you first need to [clone and build the dotnet-apiport project](https://github.com/microsoft/dotnet-apiport/blob/dev/docs/Console/README.md#run-the-tool-in-an-offline-mode). It works on Visual Studio 2017 and Visual Studio 2019 versions. > [!IMPORTANT] > The .NET Portability Analyzer is not supported in Visual Studio 2022. -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. +### Solution-wide view -![Screenshot of portability analyzer.](./media/portability-analyzer/portability-screenshot.png) +A useful step in analyzing a solution with many projects is to visualize the dependencies to understand which subset of assemblies depend on what. The general recommendation is to apply the results of the analysis in a bottom-up approach starting with the leaf nodes in a dependency graph. -You can also use the ApiPort console application, download it from [ApiPort repository](https://aka.ms/apiportdownload). You can use `listTargets` command option to display the available target list, then pick target platforms by specifying `-t` or `--target` command option. - -### Solution wide view - -A useful step in analyzing a solution with many projects would be to visualize the dependencies to understand which subset of assemblies depend on what. The general recommendation is to apply the results of the analysis in a bottom-up approach starting with the leaf nodes in a dependency graph. - -To retrieve this, you may run the following command: +To retrieve this, run the following command: ```console ApiPort.exe analyze -r DGML -f [directory or file] @@ -50,19 +43,13 @@ A result of this would look like the following when opened in Visual Studio: ### Analyze portability -To analyze your entire project in Visual Studio, right-click on your project in **Solution Explorer** and select **Analyze Assembly Portability**. Otherwise, go to the **Analyze** menu and select **Analyze Assembly Portability**. From there, select your project's executable or DLL. - -![Screenshot of Portability Analyzer from Solution Explorer.](./media/portability-analyzer/portability-solution-explorer.png) - -You can also use the [ApiPort console app](https://aka.ms/apiportdownload). - -Type the following command to analyze the current directory: +Enter the following command to analyze the current directory: ```console ApiPort.exe analyze -f . ``` -To analyze a specific list of .dll files, type the following command: +To analyze a specific list of *.dll* files, enter the following command: ```console ApiPort.exe analyze -f first.dll -f second.dll -f third.dll @@ -76,12 +63,11 @@ ApiPort.exe analyze -t ".NET, Version=5.0" -f . Run `ApiPort.exe -?` to get more help. -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. +It's 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 -Only APIs that are unsupported by a Target Platform appear in the report. -After running the analysis in Visual Studio, you'll see your .NET Portability report file link pops up. If you used the [ApiPort console app](https://aka.ms/apiportdownload), your .NET Portability report is saved as a file in the format you specified. The default is in an Excel file (*.xlsx*) in your current directory. +Only APIs that are unsupported by a Target Platform appear in the report. Your .NET Portability report is saved as a file in the format you specified. The default is in an Excel file (*.xlsx*) in your current directory. #### Portability Summary @@ -95,18 +81,18 @@ The Portability Summary section of the report shows the portability percentage f The **Details** section of the report lists the APIs missing from any of the selected **Targeted Platforms**. -- Target type: the type has missing API from a Target Platform -- Target member: the method is missing from a Target Platform -- Assembly name: the .NET Framework assembly that the missing - API lives in. -- 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: the recommended API or technology to change to. Currently, this field is empty or out of date for many APIs. Due to the large number of APIs, we have a significant challenge to keep it up to date. We're looking at alternative solutions to provide helpful information to customers. +- Target type: the type has missing API from a Target Platform. +- Target member: the method is missing from a Target Platform. +- Assembly name: the .NET Framework assembly that the missing API lives in. +- 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: the recommended API or technology to change to. Currently, this field is empty or out of date for many APIs. Due to the large number of APIs, it's a significant challenge to keep it up to date. -#### Missing Assemblies +#### Missing assemblies ![Screenshot of missing assemblies.](./media/portability-analyzer/api-catalog-missing-assemblies.png) -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. 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. +You might 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. 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. + +## See also For more information on the .NET Portability Analyzer, visit the [GitHub documentation](https://github.com/Microsoft/dotnet-apiport#documentation). diff --git a/includes/deprecating-api-port.md b/includes/deprecating-api-port.md index 54032811ce1a5..d6b0fe6f04b58 100644 --- a/includes/deprecating-api-port.md +++ b/includes/deprecating-api-port.md @@ -1,2 +1,2 @@ -> [!NOTE] +> [!IMPORTANT] > API Port has been deprecated in favor of binary analysis with the [.NET Upgrade Assistant](../docs/core/porting/upgrade-assistant-overview.md) tool. The backend service of API Port has been shut down, so to use the tool, you must use it offline. For more information, see [.NET API Port README](https://github.com/microsoft/dotnet-apiport/blob/dev/docs/Console/README.md#run-the-tool-in-an-offline-mode).