Convalidare in base a una versione del pacchetto di base

La convalida dei pacchetti consente di convalidare il progetto di libreria rispetto a una versione stabile rilasciata in precedenza del pacchetto. Per abilitare la convalida del pacchetto, aggiungere la proprietà PackageValidationBaselineVersion o PackageValidationBaselineName al file di progetto.

La convalida del pacchetto rileva eventuali modifiche che causano interruzioni in uno dei framework di destinazione forniti. Rileva anche se è stato eliminato un supporto del framework di destinazione.

Si consideri ad esempio lo scenario seguente. Si sta lavorando al pacchetto NuGet AdventureWorks.Client e ci si vuole assicurare di non apportare accidentalmente modifiche che causano interruzioni. Configurare il progetto per indicare agli strumenti di convalida dei pacchetti di eseguire controlli di compatibilità dell'API rispetto alla versione precedente del pacchetto.

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

Alcune settimane dopo, viene richiesto di aggiungere il supporto per un timeout di connessione alla libreria. Il metodo Connect è attualmente simile al seguente:

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

Poiché un timeout di connessione è un'impostazione di configurazione avanzata, si ritiene che sia sufficiente aggiungere un parametro facoltativo:

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

Tuttavia, quando si tenta di comprimere, viene generato un errore.

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]

Ci si rende conto che, anche se non è una modifica che causa un'interruzione di origine, si tratta di una modifica binaria che causa un'interruzione. Per risolvere questo problema, aggiungere un nuovo overload anziché un parametro al metodo esistente:

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

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

Ora, quando si comprime il progetto, l'operazione ha esito positivo.

Per la versione 2.0.0, si decide di rimuovere il metodo obsoleto Connect con il singolo parametro string. Dopo un'attenta considerazione, si decide di accettare questa modifica che causa un'interruzione.

<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)
{
    // ...
}

Per eliminare l'errore CP0002 per questa modifica intenzionale che causa un'interruzione, è possibile aggiungere un file CompatibilitySuppressions.xml al progetto. È possibile generare automaticamente il file di eliminazione chiamando dotnet pack /p:GenerateCompatibilitySuppressionFile=true una sola volta. Il file contiene un'eliminazione per ogni errore di convalida che si è verificato durante il pacchetto. Per altre informazioni, vedere Come eliminare.

In questo esempio, CompatibilitySuppressions.xml contiene l'eliminazione per l'errore 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>

Questo file deve essere archiviato nel controllo del codice sorgente per documentare ed esaminare le modifiche di rilievo apportate in una richiesta pull e nella versione futura.

Dopo aver rilasciato la versione 2.0.0 del pacchetto, è possibile eliminare il file CompatibilitySuppressions.xml e aggiornare la proprietà PackageValidationBaselineVersion per convalidare le modifiche future rispetto alla nuova versione.

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