Temel paket sürümüne göre doğrulama

Paket doğrulama, kitaplık projenizi paketinizin daha önce yayımlanmış, kararlı bir sürümüne göre doğrulamanıza yardımcı olabilir. Paket doğrulamasını PackageValidationBaselineVersion etkinleştirmek için veya PackageValidationBaselineName özelliğini proje dosyanıza ekleyin.

Paket doğrulaması, gönderilen hedef çerçevelerden herhangi birinde hataya neden olan değişiklikleri algılar. Ayrıca herhangi bir hedef çerçeve desteğinin bırakılıp bırakılmadığını da algılar.

Örneğin aşağıdaki senaryoları düşünün. AdventureWorks.Client NuGet paketi üzerinde çalışıyorsunuz ve yanlışlıkla hataya neden olan değişiklikler yapmadığınızdan emin olmak istiyorsunuz. Projenizi, paketin önceki sürümüne göre API uyumluluk denetimlerini çalıştırmak üzere paket doğrulama araçlarına yönerge vermek üzere yapılandıracaksınız.

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

Birkaç hafta sonra kitaplığınıza bağlantı zaman aşımı için destek eklemekle görevlendirildiniz. Yöntemi Connect şu anda şöyle görünür:

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

Bağlantı zaman aşımı gelişmiş bir yapılandırma ayarı olduğundan isteğe bağlı bir parametre ekleyebileceğinizi varsayabilirsiniz:

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

Ancak, paketlemeye çalıştığınızda bir hata oluşturur.

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]

Bunun kaynak bozucu değişiklik olmadığını, ancak ikili bozucu bir değişiklik olduğunu fark ediyorsunuz. Mevcut yönteme parametre eklemek yerine yeni bir aşırı yükleme ekleyerek bu sorunu çözebilirsiniz:

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

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

Projeyi paketleme işlemi artık başarılı oluyor.

Sürüm 2.0.0 için, tek Connect parametreli eski string yöntemi kaldırmak istediğinize karar verirsiniz. Dikkatli bir şekilde değerlendirdikten sonra, bu köklü değişikliği kabul etmeye karar verirsiniz.

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

Bu kasıtlı değişikliğin hatasını CP0002 engellemek için projenize CompatibilitySuppressions.xml dosyası ekleyebilirsiniz. Bir kez çağırarak dotnet pack /p:GenerateCompatibilitySuppressionFile=true gizleme dosyasını otomatik olarak oluşturabilirsiniz. Dosya, paket sırasında oluşan her doğrulama hatası için bir gizleme içerir. Daha fazla bilgi için bkz. Nasıl Bastırılır.

Bu örnekte CompatibilitySuppressions.xml, CP0002 hatanın giderilmesini içerir.

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

Bu dosya, bir PR'de ve yaklaşan sürümde yapılan önemli değişiklikleri belgeleyip gözden geçirmek için kaynak kontrolüne eklenmelidir.

Paketin 2.0.0 sürümünü yayımladıktan sonra ,CompatibilitySuppressions.xml dosyasını silebilir ve yeni sürümde PackageValidationBaselineVersion gelecekteki değişiklikleri doğrulamak için özelliğini güncelleştirebilirsiniz.

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

Tavsiye

CompatibilitySuppressions.xml dosyasını silmek yerine ApiCompatPreserveUnnecessarySuppressions gibi özellikleri de ayarlayabilirsiniz.