Analizador de portabilidad de .NETThe .NET Portability Analyzer

¿Quiere que sus bibliotecas sean multiplataforma?Want to make your libraries support multi-platform? ¿Quiere ver cuánto trabajo se requiere para que su aplicación de .NET Framework se ejecute en .NET Core?Want to see how much work is required to make your .NET Framework application run on .NET Core? El Analizador de portabilidad de .NET es una herramienta que analiza ensamblados y proporciona un informe detallado sobre las API de .NET que faltan para que las aplicaciones o bibliotecas sean portátiles en las plataformas .NET de destino.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. El analizador de portabilidad se ofrece como una extensión de Visual Studio, que analiza un ensamblado por proyecto y, como una aplicación de consola ApiPort, que analiza los ensamblados por archivos especificados o directorio.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.

Cuando haya convertido el proyecto para que tenga como destino la nueva plataforma, como .NET Core, puede usar la herramienta del analizador de API basada en Roslyn para identificar las API que producen excepciones PlatformNotSupportedException y otras incidencias de compatibilidad.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.

Destinos comunesCommon targets

  • .NET Core: tiene un diseño modular, admite la instalación en paralelo y está dirigido a escenarios multiplataforma..NET Core: Has a modular design, supports side-by-side installation, and targets cross-platform scenarios. La instalación en paralelo permite adoptar nuevas versiones de .NET Core sin que ello afecte a otras aplicaciones.Side-by-side installation allows you to adopt new .NET Core versions without breaking other apps. Si su objetivo es portar su aplicación a .NET Core para que sea compatible con varias plataformas, este es el destino recomendado.If your goal is to port your app to .NET Core and support multiple platforms, this is the recommended target.
  • .NET Standard: Incluye las API de .NET Standard disponibles en todas las implementaciones de .NET..NET Standard: Includes the .NET Standard APIs available on all .NET implementations. Si su objetivo es que la biblioteca se ejecute en todas las plataformas compatibles con .NET, este es el destino recomendado.If your goal is to make your library run on all .NET supported platforms, this is recommended target.
  • ASP.NET Core: Un marco web moderno basado en .NET Core.ASP.NET Core: A modern web-framework built on .NET Core. Si su objetivo es portar su aplicación web a .NET Core para que sea compatible con varias plataformas, éste es el destino recomendado.If your goal is to port your web app to .NET Core to support multiple platforms, this is the recommended target.
  • .NET Core + extensiones de plataforma: Incluye las API de .NET Core además del paquete de compatibilidad de Windows, que proporciona muchas de las tecnologías disponibles de .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. Se trata de un destino recomendado para la portabilidad de la aplicación de .NET Framework a .NET Core en Windows.This is a recommended target for porting your app from .NET Framework to .NET Core on Windows.
  • .NET standard + extensiones de la plataforma: Incluye las API de .NET Standard además del paquete de compatibilidad de Windows, que proporciona muchas de las tecnologías disponibles de .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. Se trata de un destino recomendado para la portabilidad de la biblioteca de .NET Framework a .NET Core en Windows.This is a recommended target for porting your library from .NET Framework to .NET Core on Windows.

Cómo usar el Analizador de portabilidad de .NETHow to use the .NET Portability Analyzer

Para empezar a usar el Analizador de portabilidad de .NET en Visual Studio, primero debe descargar e instalar la extensión desde 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. Funciona en Visual Studio 2017 y versiones posteriores.It works on Visual Studio 2017 and later versions. Configúrelo en Visual Studio, en Analizar > Portability Analyzer Settings (Configuración del Analizador de portabilidad), y seleccionando las plataformas de destino, que son las plataformas y versiones de .NET en las que se quiere evaluar las brechas de portabilidad en comparación con la plataforma y versión con la que se ha creado el ensamblado actual.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.

Captura de pantalla del analizador de portabilidad.

También puede usar la aplicación de consola ApiPort, descárguela desde el repositorio de ApiPort.You can also use the ApiPort console application, download it from ApiPort repository. Puede usar la opción de comando listTargets para mostrar la lista de destinos disponible y elegir las plataformas de destino especificando la opción de comando -t o --target.You can use listTargets command option to display the available target list, then pick target platforms by specifying -t or --target command option.

Vista de toda la soluciónSolution wide view

Un paso útil en el análisis de una solución con muchos proyectos sería visualizar las dependencias para comprender qué subconjunto de ensamblados depende de qué.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. La recomendación general es aplicar los resultados del análisis en un enfoque de orden ascendente a partir de los nodos hoja de un gráfico de dependencias.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.

Para recuperarlo, ejecute el siguiente comando:To retrieve this, you may run the following command:

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

El resultado sería similar al siguiente al abrirse en Visual Studio:A result of this would look like the following when opened in Visual Studio:

Captura de pantalla del análisis DGML.

Análisis de portabilidadAnalyze portability

Para analizar todo el proyecto en Visual Studio, haga clic con el botón derecho en el proyecto en Explorador de soluciones y seleccione Analyze Assembly Portability (Analizar la portabilidad del ensamblado).To analyze your entire project in Visual Studio, right-click on your project in Solution Explorer and select Analyze Assembly Portability. También puede ir al menú Analizar y seleccionar Analyze Assembly Portability (Analizar la portabilidad del ensamblado).Otherwise, go to the Analyze menu and select Analyze Assembly Portability. Desde allí, seleccione el ejecutable o DLL del proyecto.From there, select your project's executable or DLL.

Captura de pantalla del analizador de portabilidad del Explorador de soluciones.

También puede usar la aplicación de consola ApiPort.You can also use the ApiPort console app.

  • Escriba el comando siguiente para analizar el directorio actual: ApiPort.exe analyze -f .Type the following command to analyze the current directory: ApiPort.exe analyze -f .
  • Para analizar una lista específica de archivos .dll, escriba el comando siguiente: 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
  • Ejecute ApiPort.exe -? para obtener más ayuda.Run ApiPort.exe -? to get more help

Se recomienda que incluya todos los archivos exe y dll relacionados que posea y desea portar, y que excluya los archivos de los que depende la aplicación, pero que no posee y no puede portar.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. Esto le proporcionará un informe de portabilidad más relevante.This will give you most relevant portability report.

Vista e interpretación de los resultados de portabilidadView and interpret portability result

Solo las API que no son compatibles con una plataforma de destino aparecen en el informe.Only APIs that are unsupported by a Target Platform appear in the report. Después de ejecutar el análisis en Visual Studio, verá que aparecerá el vínculo del archivo de informe de portabilidad de .NET.After running the analysis in Visual Studio, you'll see your .NET Portability report file link pops up. Si ha usado la aplicación de consola ApiPort, el informe de portabilidad de .NET se guardará como archivo en el formato especificado.If you used the ApiPort console app, your .NET Portability report is saved as a file in the format you specified. El valor predeterminado es en un archivo de Excel ( .xlsx) ubicado en el directorio actual.The default is in an Excel file (.xlsx) in your current directory.

Resumen de portabilidadPortability Summary

Captura de pantalla del resumen de portabilidad.

En la sección Resumen de portabilidad del informe se muestra el porcentaje de portabilidad para cada ensamblado incluido en la ejecución.The Portability Summary section of the report shows the portability percentage for each assembly included in the run. En el ejemplo anterior, el 71,24 % de las API de .NET Framework utilizadas en la aplicación svcutil están disponibles en .NET Core + extensiones de la plataforma.In the previous example, 71.24% of the .NET Framework APIs used in the svcutil app are available in .NET Core + Platform Extensions. Si ejecuta la herramienta Analizador de portabilidad de .NET en varios ensamblados, cada ensamblado debe tener una fila en el informe de Resumen de portabilidad.If you run the .NET Portability Analyzer tool against multiple assemblies, each assembly should have a row in the Portability Summary report.

DetallesDetails

Captura de pantalla de los detalles de portabilidad.

La sección Detalles del informe enumera las API que faltan desde cualquiera de las plataformas de destino seleccionadas.The Details section of the report lists the APIs missing from any of the selected Targeted Platforms.

  • Tipo de destino: al tipo le falta la API desde una plataforma de destinoTarget type: the type has missing API from a Target Platform
  • Miembro de destino: el método no está presente en una plataforma de destinoTarget member: the method is missing from a Target Platform
  • Nombre del ensamblado: el ensamblado de .NET Framework en el que se encuentra la API que falta.Assembly name: the .NET Framework assembly that the missing API lives in.
  • Cada una de las plataformas de destino seleccionada es una columna, como ".NET Core": El valor de "No compatible" significa que la API no se admite en esta plataforma de destino.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.
  • Cambios recomendados: la API o tecnología recomendada a la que realizar el cambio.Recommended Changes: the recommended API or technology to change to. Actualmente, este campo está vacío o no está actualizado para muchas de las API.Currently, this field is empty or out of date for many APIs. Debido al gran número de API, nos enfrentamos a un gran desafío para mantenerlas actualizadas.Due to the large number of APIs, we have a significant challenge to keep it up to date. Estamos examinando soluciones alternativas para proporcionar información útil a los clientes.We're looking at alternative solutions to provide helpful information to customers.

Ensamblados que faltanMissing Assemblies

Captura de pantalla de los ensamblados que faltan.

Puede encontrar la sección Ensamblados que faltan en el informe.You may find a Missing Assemblies section in your report. Esta sección contiene una lista de ensamblados a los que hacen referencia los ensamblados analizados y que no se han analizado.This section contains a list of assemblies that are referenced by your analyzed assemblies and were not analyzed. Si se trata un ensamblado que posee, inclúyalo en la ejecución del analizador de portabilidad de API para que pueda obtener un informe detallado de portabilidad a nivel de 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. Si se trata de una biblioteca de terceros, compruebe si hay una versión más reciente que admita la plataforma de destino y considere la posibilidad de usar dicha versión más reciente.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. Finalmente, la lista debe incluir todos los ensamblados de terceros de los que depende la aplicación que tengan una versión compatible con la plataforma de destino.Eventually, the list should include all the third-party assemblies that your app depends on that have a version supporting your target platform.

Para obtener más información sobre el Analizador de portabilidad de .NET, visite la documentación de GitHub y el vídeo de Channel 9 A Brief Look at the .NET Portability Analyzer (Información breve sobre el Analizador de portabilidad de .NET).For more information on the .NET Portability Analyzer, visit the GitHub documentation and A Brief Look at the .NET Portability Analyzer Channel 9 video.