Validación con una versión del paquete de línea de base

La validación de paquetes puede ayudar a validar el proyecto de biblioteca con una versión estable publicada anteriormente del paquete. Para habilitar la validación de paquetes, agregue la propiedad PackageValidationBaselineVersion o PackageValidationBaselineName al archivo del proyecto.

La validación de paquetes detecta los cambios importantes en cualquiera de los marcos de destino enviados. También detecta si se ha anulado la compatibilidad con la plataforma de destino.

Por ejemplo, tenga en cuenta el siguiente caso. Está trabajando en el paquete NuGet AdventureWorks.Client y quiere asegurarse de que no realiza cambios importantes accidentalmente. El proyecto se configura para indicar a las herramientas de validación de paquetes que ejecuten comprobaciones de compatibilidad de API en la versión anterior del paquete.

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

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <PackageVersion>1.1.0</PackageVersion>
    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
  </PropertyGroup>

</Project>

Unas semanas más tarde, se le asigna la tarea de agregar compatibilidad con un tiempo de espera de conexión a la biblioteca. El aspecto actual del método Connect es similar al siguiente:

public static HttpClient Connect(string url)
{
    // ...
}

Puesto que un tiempo de espera de conexión es una configuración avanzada, se considera que solo puede agregar un parámetro opcional:

public static HttpClient Connect(string url, TimeSpan timeout = default)
{
    // ...
}

Pero al intentar empaquetar se produce un error.

D:\demo>dotnet pack
MSBuild version 17.3.2+561848881 for .NET
  Determining projects to restore...
  All projects are up-to-date for restore.
  AdventureWorks.Client -> D:\demo\bin\Debug\net6.0\AdventureWorks.Client.dll
C:\Program Files\dotnet\sdk\6.0.413\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.Compatibility.Common.targets(33,5): error CP0002: Member 'A.B.Connect(string)' exists on [Baseline] lib/net6.0/AdventureWorks.Client.dll but not on lib/net6.0/AdventureWorks.Client.dll [D:\demo\AdventureWorks.Client.csproj]

Se da cuenta de que, aunque no se trata de un cambio importante de origen, es un cambio importante binario. Para resolver este problema, agregue una sobrecarga nueva en lugar de agregar un parámetro al método existente:

public static HttpClient Connect(string url)
{
    return Connect(url, Timeout.InfiniteTimeSpan);
}

public static HttpClient Connect(string url, TimeSpan timeout)
{
    // ...
}

Ahora, cuando empaqueta el proyecto, se realiza correctamente.

Para la versión 2.0.0, decide quitar el método obsoleto Connect que tiene el parámetro string único. Tras considerarlo detenidamente, decide aceptar este cambio importante.

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

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <PackageVersion>2.0.0</PackageVersion>
    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>1.1.0</PackageValidationBaselineVersion>
  </PropertyGroup>

</Project>

- public static HttpClient Connect(string url)
- {
-     return Connect(url, Timeout.InfiniteTimeSpan);
- }

public static HttpClient Connect(string url, TimeSpan timeout)
{
    // ...
}

Para suprimir el error CP0002 de este cambio importante intencional, puede agregar un archivo CompatibilitySuppressions.xml al proyecto. Puede generar automáticamente el archivo de supresión llamando a dotnet pack /p:GenerateCompatibilitySuppressionFile=true una vez. El archivo contiene una supresión para cada error de validación que se ha producido durante el paquete. Para obtener más información, consulte Cómo suprimir.

En este ejemplo, CompatibilitySuppressions.xml contiene la supresión del error CP0002:

<?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.Connect(System.String)</Target>
    <Left>lib/net6.0/AdventureWorks.Client.dll</Left>
    <Right>lib/net6.0/AdventureWorks.Client.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
</Suppressions>

Este archivo debe estar insertado en el repositorio de control de código fuente para documentar y revisar los cambios importantes realizados en una solicitud de incorporación de cambios y en la próxima versión.

Después de publicar la versión 2.0.0 del paquete, puede eliminar el archivo CompatibilitySuppressions.xml y actualizar la propiedad PackageValidationBaselineVersion para validar los cambios futuros en la nueva versión.

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

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <PackageVersion>2.1.0</PackageVersion>
    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>2.0.0</PackageValidationBaselineVersion>
  </PropertyGroup>

</Project>