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 hataya neden olan bir değişiklik olmadığını, ancak ikili hataya neden olan 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)
{
    // ...
}

Şimdi projeyi paketlediğinizde başarılı olur.

Sürüm 2.0.0 için, tek string parametreli eski Connect yöntemi kaldırmak istediğinize karar verirsiniz. Dikkatli bir şekilde değerlendirdikten sonra, bu hataya neden olan 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ı hataya neden olan değişikliğin hatasını CP0002 engellemek için projenize bir 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. Gizleme.

Bu örnekte, CompatibilitySuppressions.xml hatanın gizlemesini CP0002 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, çekme isteğinde ve yaklaşan sürümde yapılan hataya neden olan değişiklikleri belgeleyip gözden geçirmek için kaynak denetimine iade edilmelidir.

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>