Analizador de portabilidad de .NET

Nota:

El puerto API ha quedado en desuso en favor del análisis binario por el Asistente de actualización de .NET. El servicio back-end del puerto API se cerró, por lo que para usar la herramienta, es necesario hacerlo sin conexión. Para obtener más información, consulte Archivo Léame del puerto de API de .NET.

¿Quiere que sus bibliotecas sean multiplataforma? ¿Quiere ver cuánto trabajo se requiere para que su aplicación de .NET Framework se ejecute en .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. 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.

Cuando hayas 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.

Destinos comunes

• .NET Core: tiene un diseño modular, admite la instalación en paralelo y está dirigido a escenarios multiplataforma. La instalación en paralelo permite adoptar nuevas versiones de .NET Core sin que ello afecte a otras aplicaciones. Si su objetivo es portar su aplicación a .NET Core para que sea compatible con varias plataformas, este es el destino recomendado.
• .NET Standard: incluye las API de .NET Standard disponibles en todas las implementaciones de .NET. Si su objetivo es que la biblioteca se ejecute en todas las plataformas compatibles con .NET, este es el destino recomendado.
• ASP.NET Core: Un marco web moderno basado en .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.
• .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. Se trata de un destino recomendado para la portabilidad de la aplicación de .NET Framework a .NET Core en 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. Se trata de un destino recomendado para la portabilidad de la biblioteca de .NET Framework a .NET Core en Windows.

Cómo usar el Analizador de portabilidad de .NET

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. Funciona en Visual Studio 2017 y versiones de Visual Studio 2019.

Importante

El Analizador de portabilidad de .NET no se admite en Visual Studio 2022.

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.

También puede usar la aplicación de consola ApiPort, descárguela desde el repositorio de ApiPort. 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.

Vista de toda la solución

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é. 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.

Para recuperarlo, ejecute el siguiente comando:

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

El resultado sería similar al siguiente al abrirse en Visual Studio:

Análisis de portabilidad

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). También puede ir al menú Analizar y seleccionar Analyze Assembly Portability (Analizar la portabilidad del ensamblado). Desde allí, seleccione el ejecutable o DLL del proyecto.

También puede usar la aplicación de consola ApiPort.

Escriba el comando siguiente para analizar el directorio actual:

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.dll

Para establecer como destino una versión específica, use el -t parámetro :

ApiPort.exe analyze -t ".NET, Version=5.0" -f .

Ejecute ApiPort.exe -? para obtener más ayuda.

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. Esto le proporcionará un informe de portabilidad más relevante.

Vista e interpretación de los resultados de portabilidad

Solo las API que no son compatibles con una plataforma de destino aparecen en el informe. Después de ejecutar el análisis en Visual Studio, verá que aparecerá el vínculo del archivo de informe de portabilidad de .NET. Si ha usado la aplicación de consola ApiPort, el informe de portabilidad de .NET se guardará como archivo en el formato especificado. El valor predeterminado es en un archivo de Excel ( .xlsx) ubicado en el directorio actual.

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. 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. 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.

Detalles

La sección Detalles del informe enumera las API que faltan desde cualquiera de las plataformas de destino seleccionadas.

• Tipo de destino: al tipo le falta la API desde una plataforma de destino
• Miembro de destino: el método no está presente en una plataforma de destino
• Nombre del ensamblado: el ensamblado de .NET Framework en el que se encuentra la API que falta.
• 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.
• Cambios recomendados: la API o tecnología recomendada a la que realizar el cambio. Actualmente, este campo está vacío o no está actualizado para muchas de las API. Debido al gran número de API, nos enfrentamos a un gran desafío para mantenerlas actualizadas. Estamos examinando soluciones alternativas para proporcionar información útil a los clientes.

Ensamblados que faltan

Puede encontrar la sección Ensamblados que faltan en el informe. Esta sección contiene una lista de ensamblados a los que hacen referencia los ensamblados analizados y que no se han analizado. 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. 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. 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.

Para obtener más información sobre .NET Portability Analyzer, consulta la documentación de GitHub.