Información general sobre la validación de paquetes

  • Artículo
  • 2 minutos para leer

La compatibilidad multiplataforma se ha convertido en un requisito estándar para los autores de bibliotecas de .NET. Pero sin herramientas de validación para estos paquetes, a menudo no funcionan bien. Esto es especialmente problemático para las plataformas emergentes en las que la adopción no es lo suficientemente alta como para garantizar una atención especial por parte de los autores de bibliotecas.

Hasta que se introdujo la validación de paquetes, las herramientas del SDK de .NET no proporcionaban casi ninguna validación de que los paquetes de varios destinos estaban bien formados. Por ejemplo, un paquete que tiene varios destinos para .NET 6 y .NET Standard 2.0 debe asegurarse de que el código compilado en el binario de .NET Standard 2.0 se pueda 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.

Las herramientas de validación de paquetes permiten a los desarrolladores de bibliotecas validar que sus paquetes son coherentes y están bien formados. Proporciona las comprobaciones siguientes:

  • Valida que no haya cambios importantes en las versiones.
  • Valida que el paquete tenga el mismo conjunto de API públicas para todas las implementaciones específicas del entorno de ejecución diferentes.
  • Permite los desarrolladores detectar cualquier brecha de aplicabilidad.

Habilitación de la validación de paquetes

Puede habilitar la validación de paquetes en el proyecto de .NET estableciendo la propiedad EnablePackageValidation en true.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;net6.0</TargetFrameworks>
    <EnablePackageValidation>true</EnablePackageValidation>
  </PropertyGroup>

</Project>

EnablePackageValidation ejecuta una serie de comprobaciones después de la tarea pack. Hay algunas comprobaciones adicionales que se pueden ejecutar estableciendo otras propiedades de MSBuild.

Tipos de validador

Hay tres validadores diferentes que comprueban el paquete como parte de la tarea pack:

Eliminación de errores de compatibilidad

Para eliminar los errores de compatibilidad de los cambios intencionados, agregue un archivo CompatibilitySuppressions.xml al proyecto. Puede generar este archivo automáticamente pasando /p:GenerateCompatibilitySuppressionFile=true en caso de que compile el proyecto desde la línea de comandos o agregando la propiedad siguiente al proyecto: <GenerateCompatibilitySuppressionFile>true</GenerateCompatibilitySuppressionFile>.

El archivo de eliminación tiene este aspecto.

<?xml version="1.0" encoding="utf-8"?>
<Suppressions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:A.B.DoStringManipulation(System.String)</Target>
    <Left>lib/netstandard2.0/A.dll</Left>
    <Right>lib/net6.0/A.dll</Right>
    <isBaseline>false</isBaseline>
  </Suppression>
</Suppressions>

  • DiagnosticID especifica el id. del error que se debe eliminar.

  • Target especifica dónde eliminar en el código los id. de diagnóstico.

  • Left especifica el operando izquierdo de una comparación APICompat.

  • Right especifica el operando derecho de una comparación APICompat.

  • isBaseline: se establece en true para aplicar la eliminación a una validación de línea de base; de lo contrario, se establece en false.