기준 패키지 버전에 대해 유효성 검사

패키지 유효성 검사는 이전에 출시된 안정적인 버전의 패키지를 기준으로 라이브러리 프로젝트의 유효성을 검사하는 데 도움이 됩니다. 패키지 유효성 검사를 사용하도록 설정하려면 프로젝트 파일에 PackageValidationBaselineVersion 또는 PackageValidationBaselineName 속성을 추가합니다.

패키지 유효성 검사는 출고된 모든 대상 프레임워크에서 호환성이 손상되는 변경을 감지합니다. 대상 프레임워크 지원이 제거되었는지도 감지합니다.

예를 들어 다음과 같은 경우를 고려해야 합니다. AdventureWorks.Client NuGet 패키지를 작업 중인 여러분은 실수로 호환성이 손상되는 변경을 적용하지 않도록 주의하려고 합니다. 패키지 유효성 검사 도구에 이전 버전의 패키지를 기준으로 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의 경우 단일 string 매개 변수가 있는 사용되지 않는 Connect 메서드를 제거하려고 합니다. 신중하게 고려한 후에는 이 호환성이 손상되는 변경을 적용하기로 결정합니다.

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