Herramientas de compatibilidad de API

  • Artículo

La compatibilidad multiplataforma se ha convertido en un requisito estándar para los autores de bibliotecas de .NET. Sin embargo, sin herramientas para validar ensamblados y paquetes, pueden contener cambios importantes accidentales. Como autor de la biblioteca, debe asegurarse de que los ensamblados de varios destino son compatibles. Por ejemplo, para un paquete que tenga varios destinos para .NET 6 y .NET Standard 2.0, debe asegurarse de que el código compilado con el binario de .NET Estándar 2.0 se puede ejecutar en el binario de .NET 6.

Es posible pensar que un cambio es seguro y compatible si el origen que consume ese cambio continúa compilándose sin cambios. Aun así, los cambios pueden seguir causando problemas en tiempo de ejecución si el consumidor no se ha recompilado. Por ejemplo, agregar un parámetro opcional a un método o cambiar el valor de una constante puede provocar estos tipos de problemas de compatibilidad.

El SDK de .NET proporciona varias maneras de comparar versiones compiladas para diferentes marcos de destino. También puede validar una versión más reciente en una versión de línea base para asegurarse de que no se han introducido cambios importantes. Habilite las tareas de MSBuild para validar los ensamblados en tiempo de compilación o los paquetes al empaquetar. O bien, use la herramienta global Microsoft.DotNet.ApiCompat.Tool para validarse fuera de MSBuild.

Para obtener más información acerca de la validación de paquetes, consulte Validación de paquetes. La validación de ensamblados debe usarse cuando la aplicación no se pueda empaquetar. Para obtener más información acerca de la validación de ensamblados, consulte Validación de ensamblados.

Nota:

Para ejecutar la validación de ensamblados como una tarea de MSBuild, debe agregar una referencia de paquete a Microsoft.DotNet.ApiCompat.Task. Del mismo modo, también puede agregar una referencia a este paquete cuando quiera probar características más recientes que aún no están disponibles en el SDK de .NET. Por ejemplo, puede hacer referencia a la versión 9.0.100-preview del Paquete Microsoft.DotNet.ApiCompat.Task mientras usa el SDK de .NET 8.

Modo strict

De manera predeterminada, la validación realiza comprobaciones de compatibilidad. Sin embargo, también puede optar por el modo estricto. En modo estricto, la validación realiza comprobaciones de igualdad. La igualdad significa que no se han realizado adiciones de API ni cambios de ensamblado, incluso los compatibles.

Los casos de uso para el modo strict incluyen lo siguiente:

  • El mantenimiento, en el que las adiciones de API suelen estar prohibidas.
  • Para realizar el seguimiento de los cambios de la API. La funcionalidad de compatibilidad de API registra todas las diferencias de compatibilidad en el archivo de supresión si establece ApiCompatGenerateSuppressionFile en true.

Para habilitar el modo estricto para la herramienta de línea de comandos, especifique la opción --strict-mode o una de las opciones --enable-strict*. Para habilitar el modo estricto para las tareas de MSBuild, agregue una o varias de las siguientes propiedades de MSBuild al archivo de proyecto: