Validar em relação a uma versão de linha de base do pacote

A validação do pacote pode ajudá-lo a validar seu projeto de biblioteca em relação a uma versão estável lançada anteriormente do seu pacote. Para habilitar a validação de pacote, adicione a PackageValidationBaselineVersion propriedade or PackageValidationBaselineName ao seu arquivo de projeto.

A validação do pacote deteta quaisquer alterações significativas em qualquer uma das estruturas de destino enviadas. Ele também deteta se algum suporte à estrutura de destino foi descartado.

Por exemplo, considere o seguinte cenário. Você está trabalhando no pacote NuGet do AdventureWorks.Client e quer ter certeza de que não faz alterações de quebra acidentalmente. Você configura seu projeto para instruir as ferramentas de validação de pacote a executar verificações de compatibilidade de API em relação à versão anterior do pacote.

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

Algumas semanas depois, você terá a tarefa de adicionar suporte para um tempo limite de conexão à sua biblioteca. Atualmente, o Connect método tem esta aparência:

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

Como um tempo limite de conexão é uma definição de configuração avançada, você pode simplesmente adicionar um parâmetro opcional:

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

No entanto, quando você tenta empacotar, ele lança um erro.

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]

Você percebe que, embora isso não seja uma mudança de quebra de fonte, é uma mudança de quebra binária. Você resolve esse problema adicionando uma nova sobrecarga em vez de adicionar um parâmetro ao método existente:

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

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

Agora, quando você empacota o projeto, ele é bem-sucedido.

Para a versão 2.0.0, você decide que deseja remover o método obsoleto Connect que tem o único string parâmetro. Depois de uma consideração cuidadosa, você decide aceitar essa mudança de rutura.

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

Para suprimir o CP0002 erro dessa alteração de quebra intencional, você pode adicionar um arquivo de CompatibilitySuppressions.xml ao seu projeto. Você pode gerar o arquivo de supressão automaticamente chamando dotnet pack /p:GenerateCompatibilitySuppressionFile=true uma vez. O arquivo contém uma supressão para cada erro de validação que ocorreu durante o pacote. Para obter mais informações, consulte Como suprimir.

Neste exemplo, o CompatibilitySuppressions.xml contém a supressão do CP0002 erro:

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

Este arquivo deve ser verificado no controle do código-fonte para documentar e revisar as alterações de quebra feitas em um PR e na próxima versão.

Depois de lançar a versão 2.0.0 do pacote, você pode excluir o arquivo de CompatibilitySuppressions.xml e atualizar a PackageValidationBaselineVersion propriedade para validar alterações futuras em relação à nova versão.

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