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

Проверка пакета поможет вам проверить проект библиотеки с ранее выпущенной стабильной версией пакета. Чтобы включить проверку пакета, добавьте свойство 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>