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 PackageValidationBaselineVersion proprietà o PackageValidationBaselineName al file di progetto.

La convalida del pacchetto rileva eventuali modifiche di rilievo in uno dei framework di destinazione forniti. Rileva anche se è stata eliminata la compatibilità con un framework di destinazione.

Si consideri ad esempio lo scenario seguente. Stai lavorando al pacchetto NuGet AdventureWorks.Client e vuoi assicurarti di non apportare accidentalmente modifiche incompatibili. 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>

Qualche settimana dopo, ti viene chiesto di aggiungere il supporto per un timeout di connessione alla tua libreria. Il Connect metodo è 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, mentre questa non è una modifica interruzione sorgente, si tratta di una modifica di interruzione binaria. Per risolvere questo problema, aggiungere un nuovo overload anziché aggiungere 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, funziona.

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

<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 questo cambiamento intenzionale di compatibilità, è possibile aggiungere un fileCompatibilitySuppressions.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, il CompatibilitySuppressions.xml contiene la soppressione 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 controllato nel controllo del codice sorgente per documentare ed esaminare le modifiche di rilievo apportate in una pull request e nella versione futura.

Dopo aver rilasciato la versione 2.0.0 del pacchetto, è possibile eliminare il file diCompatibilitySuppressions.xml e aggiornare la PackageValidationBaselineVersion proprietà 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>

Suggerimento

Invece di eliminare il file CompatibilitySuppressions.xml, puoi anche considerare di impostare proprietà come ApiCompatPreserveUnnecessarySuppressions.