Memverifikasi terhadap versi paket patokan

Validasi paket dapat membantu Anda memvalidasi proyek pustaka terhadap versi paket Anda yang dirilis sebelumnya dan stabil. Untuk mengaktifkan validasi paket, tambahkan properti PackageValidationBaselineVersion atau PackageValidationBaselineName ke file proyek Anda.

Validasi paket mendeteksi perubahan signifikan pada kerangka kerja target yang didistribusikan. Ini juga mendeteksi apakah ada dukungan kerangka kerja target yang telah dihilangkan.

Misalnya, pertimbangkan skenario berikut. Anda sedang mengerjakan paket AdventureWorks.Client NuGet dan ingin memastikan bahwa Anda tidak secara tidak sengaja membuat perubahan yang melanggar. Anda mengonfigurasi proyek untuk menginstruksikan alat validasi paket untuk menjalankan pemeriksaan kompatibilitas API terhadap versi paket sebelumnya.

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

Beberapa minggu kemudian, Anda ditugaskan untuk menambahkan dukungan untuk batas waktu koneksi ke pustaka Anda. Metode Connect saat ini terlihat seperti ini:

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

Karena batas waktu koneksi adalah pengaturan konfigurasi tingkat lanjut, Anda memperhitungkan bahwa Anda hanya dapat menambahkan parameter opsional:

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

Namun, ketika Anda mencoba untuk mengemas, itu memunculkan kesalahan.

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]

Anda menyadari bahwa meskipun ini bukan perubahan pemecah sumber, ini adalah perubahan pemecah biner. Anda menyelesaikan masalah ini dengan menambahkan kelebihan beban baru alih-alih menambahkan parameter ke metode yang ada:

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

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

Sekarang ketika Anda mengemas proyek, itu berhasil.

Untuk versi 2.0.0, Anda memutuskan ingin menghapus metode usang Connect yang memiliki parameter tunggal string . Setelah pertimbangan yang cermat, Anda memutuskan untuk menerima perubahan yang memutuskan kompatibilitas ini.

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

Untuk menyembunyikan CP0002 kesalahan untuk perubahan yang melanggar yang disengaja ini, Anda dapat menambahkan file CompatibilitySuppressions.xml ke proyek Anda. Anda dapat membuat file supresi secara otomatis dengan memanggil dotnet pack /p:GenerateCompatibilitySuppressionFile=true sekali. File berisi supresi untuk setiap kesalahan validasi yang terjadi selama paket. Untuk informasi selengkapnya, lihat Cara menghilangkan.

Dalam contoh ini, CompatibilitySuppressions.xml berisi supresi untuk CP0002 kesalahan:

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

File ini harus diperiksa ke kontrol sumber untuk mendokumen dan meninjau perubahan mencolok yang dibuat dalam PR dan rilis mendatang.

Setelah merilis paket versi 2.0.0, Anda dapat menghapus file CompatibilitySuppressions.xml dan memperbarui PackageValidationBaselineVersion properti untuk memvalidasi perubahan di masa mendatang terhadap rilis baru.

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