Ověření oproti základní verzi balíčku

Ověření balíčku vám může pomoct ověřit projekt knihovny oproti dříve vydané stabilní verzi balíčku. Chcete-li povolit ověření balíčku, přidejte do souboru projektu vlastnost PackageValidationBaselineVersion nebo PackageValidationBaselineName.

Ověření balíčku detekuje jakékoli narušující změny v některém z odeslaných cílových frameworků. Zjistí také, jestli nedošlo k vyřazení podpory cílového rámce.

Představte si například následující scénář. Pracujete na balíčku NuGet AdventureWorks.Client a chcete se ujistit, že omylem neprovádíte zásadní změny. Nakonfigurujete projekt tak, aby nástroje pro ověření balíčku daly pokyn ke spuštění kontrol kompatibility rozhraní API oproti předchozí verzi balíčku.

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

O několik týdnů později máte za úkol přidat do knihovny podporu vypršení časového limitu připojení. Metoda Connect aktuálně vypadá takto:

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

Vzhledem k tomu, že vypršení časového limitu připojení je rozšířené nastavení konfigurace, počítejte s tím, že stačí přidat volitelný parametr:

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

Když se ale pokusíte balíček zabalit, dojde k chybě.

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]

Uvědomujete si, že i když se nejedná o změnu, která neovlivňuje zdroj, jedná se o binárně narušující změnu. Tento problém vyřešíte přidáním nového přetížení místo přidání parametru do existující metody:

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

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

Když teď projekt zabalíte, proběhne úspěšně.

U verze 2.0.0 se rozhodnete odebrat zastaralou Connect metodu, která má jediný string parametr. Po pečlivém zvážení se rozhodnete přijmout tuto zásadní změnu.

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

Pokud chcete potlačit CP0002 chybu pro tuto úmyslnou změnu, můžete do projektu přidat souborCompatibilitySuppressions.xml. Soubor potlačení můžete automaticky vytvořit tím, že jednou zavoláte dotnet pack /p:GenerateCompatibilitySuppressionFile=true. Soubor obsahuje potlačení pro každou chybu ověření, ke které došlo během balíčku. Další informace naleznete v tématu Jak potlačit.

V tomto příkladu CompatibilitySuppressions.xml obsahuje potlačení pro chybu 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>

Tento soubor by se měl vrátit do správy zdrojového kódu, abyste dokumentovali a zkontrolovali zásadní změny provedené v žádosti o přijetí změn a v nadcházející verzi.

Po uvolnění verze 2.0.0 balíku můžete odstranit souborCompatibilitySuppressions.xml a aktualizovat PackageValidationBaselineVersion vlastnost k ověření budoucích změn proti nové verzi.

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

Návod

Místo odstranění souboru CompatibilitySuppressions.xml můžete také zvážit nastavení vlastností, jako je ApiCompatPreserveUnnecessarySuppressions.