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

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

A validação do pacote detecta alterações interruptivas em qualquer uma das estruturas de destino enviadas. Ele também detecta se algum suporte de framework de destino foi descontinuado.

Por exemplo, considere o cenário a seguir. Você está trabalhando no pacote NuGet AdventureWorks.Client e deseja garantir que você não fará alterações interruptivas acidentalmente. Configure seu projeto para orientar as ferramentas de validação de pacotes a realizar verificações de compatibilidade da 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. O Connect método atualmente tem esta aparência:

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

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

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

No entanto, quando você tenta empacotar, ele gera 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 essa não seja uma alteração interruptiva de origem, é uma alteração interruptiva 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)
{
    // ...
}

Ao fazer o empacotamento do 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. Após uma consideração cuidadosa, você decide aceitar essa mudança disruptiva.

<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 erro CP0002 causado por essa quebra intencional, você pode adicionar um arquivo 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>

Esse arquivo deve ser verificado no controle do código-fonte para documentar e revisar as alterações interrompidas 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 CompatibilitySuppressions.xml e atualizar a PackageValidationBaselineVersion propriedade para validar alterações futuras na 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>

Dica

Em vez de excluir o arquivo CompatibilitySuppressions.xml , você também pode considerar a configuração de propriedades como ApiCompatPreserveUnnecessarySuppressions.