Проверка по сравнению с базовой версией пакета

Проверка пакета поможет вам проверить проект библиотеки с ранее выпущенной стабильной версией пакета. Чтобы включить проверку пакета, добавьте свойство PackageValidationBaselineVersion или PackageValidationBaselineName в файл проекта.

При проверке пакета обнаруживаются критические изменения для любой из поставляемых целевых платформ. Он также определяет, была ли удалена поддержка целевой платформы.

Рассмотрим следующий сценарий. Вы работаете над пакетом NuGet AdventureWorks.Client и хотите убедиться, что случайно не внесли критические изменения. Вы настраиваете проект, чтобы средство проверки пакетов выполнило проверки совместимости API для предыдущей версии пакета.

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

Через несколько недель вы собираетесь добавить поддержку времени ожидания подключения к библиотеке. Теперь метод Connect выглядит следующим образом:

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

Так как время ожидания подключения является дополнительным параметром конфигурации, вы думаете, что можно просто добавить необязательный параметр:

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

Однако при попытке упаковки возникает ошибка.

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]

Вы понимаете, что это не критическое изменение источника, но критическое изменение двоичного файла. Чтобы решить эту проблему, вы добавляете новую перегрузку вместо добавления параметра в существующий метод:

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

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

Теперь упаковка проекта проходит успешно.

Для версии 2.0.0 вы решите удалить устаревший Connect метод с одним string параметром. После тщательного рассмотрения вы решите принять это критическое изменение.

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

Чтобы отключить ошибку CP0002 для этого намеренного критического изменения, можно добавить в проект файл CompatibilitySuppressions.xml . Вы можете автоматически создать файл подавления, вызвав dotnet pack /p:GenerateCompatibilitySuppressionFile=true один раз. Файл содержит подавление для каждой ошибки проверки, которая произошла во время пакета. Дополнительные сведения см. в разделе "Как отключить".

В этом примере CompatibilitySuppressions.xml содержит подавление 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>

Этот файл должен быть проверка в систему управления версиями, чтобы документировать и просматривать критические изменения, внесенные в PR и предстоящий выпуск.

После выпуска пакета версии 2.0.0 можно удалить файл CompatibilitySuppressions.xml и обновить PackageValidationBaselineVersion свойство, чтобы проверить будущие изменения в новом выпуске.

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