다음을 통해 공유

Microsoft.DotNet.ApiCompat.Tool 전역 도구

  • 아티클

Microsoft.DotNet.ApiCompat.Tool 도구를 사용하면 MSBuild 외부에서 API 호환성 검사를 수행할 수 있습니다. 도구에는 다음과 같은 두 가지 모드가 있습니다.

  • 패키지를 기준 패키지와 비교합니다.
  • 어셈블리를 기준 어셈블리와 비교합니다.

설치

도구를 설치하려면 다음 명령을 실행합니다.

dotnet tool install --global Microsoft.DotNet.ApiCompat.Tool

전역 도구를 설치하는 방법에 대한 자세한 내용은 전역 도구 설치를 참조하세요.

사용

Microsoft.DotNet.ApiCompat.Tool [command] [options]

또는

apicompat [command] [options]

명령

  • package | --package <PACKAGE_FILE>

    패키지 자산의 호환성 유효성을 검사합니다. 지정되지 않은 경우 도구는 어셈블리를 비교합니다. <PACKAGE_FILE>은 패키지 파일의 경로를 지정합니다.

옵션

일부 옵션은 어셈블리 및 패키지 유효성 검사 모두에 적용됩니다. 다른 항목은 어셈블리에만 적용되거나 패키지에만 적용됩니다.

일반 옵션

  • --version

    버전 정보를 표시합니다.

  • --generate-suppression-file

    호환성 제거 파일을 생성합니다.

  • --preserve-unnecessary-suppressions

    제거 파일을 다시 생성할 때 불필요한 제거를 유지합니다.

    기존 제거 파일이 다시 생성되면 해당 콘텐츠를 읽고 제거 집합으로 역직렬화한 다음 목록에 저장합니다. 비호환성이 해결되면 일부 제거 기능이 더 이상 필요하지 않을 수 있습니다. 제거가 다시 디스크에 직렬화되면 이 옵션을 지정하여 기존(역직렬화된) 식을 모두 유지하도록 선택할 수 있습니다.

  • --permit-unnecessary-suppressions

    제거 파일에서 불필요한 제거를 허용합니다.

  • --suppression-file <FILE>

    읽을 하나 이상의 제거 파일에 대한 경로를 지정합니다.

  • --suppression-output-file <FILE>

    --generate-suppression-file이 지정되어 있으면 쓸 제거 파일의 경로를 지정합니다. 지정하지 않으면 첫 번째 --suppression-file 경로가 사용됩니다.

  • --noWarn <NOWARN_STRING>

    제거할 진단 ID를 지정합니다. 예들 들어 "$(NoWarn);PKV0001"입니다.

  • --respect-internals

    internal API와 public API를 모두 확인합니다.

  • --roslyn-assemblies-path <FILE>

    사용하려는 Microsoft.CodeAnalytic 어셈블리가 포함된 디렉터리의 경로를 지정합니다. SDK에 있는 것보다 최신 컴파일러로 테스트하려는 경우에만 이 속성을 설정하면 됩니다.

  • -v, --verbosity [high|low|normal]

    로그 수준 세부 정보를 제어합니다. 허용되는 값은 high, normal 및 low입니다. 기본값은 normal입니다.

  • --enable-rule-cannot-change-parameter-name

    공용 메서드에서 매개 변수 이름이 변경되었는지를 검사하는 규칙을 사용하도록 설정합니다.

  • --enable-rule-attributes-must-match

    특성이 일치하는지를 검사하는 규칙을 사용하도록 설정합니다.

  • --exclude-attributes-file <FILE>

    DocId 형식으로 제외할 특성이 포함된 하나 이상의 파일에 대한 경로를 지정합니다.

어셈블리별 옵션

이러한 옵션은 어셈블리를 비교할 때만 적용됩니다.

  • -l, --left, --left-assembly <PATH>

    비교할 왼쪽 역할을 하는 하나 이상의 어셈블리에 대한 경로를 지정합니다. 이 옵션은 어셈블리를 비교할 때 필요합니다.

  • -r, --right, --right-assembly <PATH>

    비교할 오른쪽 역할을 하는 하나 이상의 어셈블리에 대한 경로를 지정합니다. 이 옵션은 어셈블리를 비교할 때 필요합니다.

  • --strict-mode

    strict 모드에서 API 호환성 검사를 수행합니다.

패키지별 옵션

이러한 옵션은 패키지를 비교할 때만 적용됩니다.

  • --baseline-package

    현재 패키지의 유효성을 검사할 기준 패키지의 경로를 지정합니다.

  • --enable-strict-mode-for-compatible-tfms

    호환되는 모든 대상 프레임워크의 계약 및 구현 어셈블리에 대해 strict 모드에서 API 호환성의 유효성을 검사합니다. 기본값은 true입니다.

  • --enable-strict-mode-for-compatible-frameworks-in-package

    대상 프레임워크를 기반으로 호환되는 어셈블리에 대해 strict 모드에서 API 호환성의 유효성을 검사합니다.

  • --enable-strict-mode-for-baseline-validation

    패키지 기준 검사에 대해 strict 모드에서 API 호환성의 유효성을 검사합니다.

  • --package-assembly-references

    패키지의 특정 대상 프레임워크에 대한 어셈블리 참조 또는 해당 기본 디렉터리에 대한 경로를 지정합니다. 쉼표를 사용하여 여러 값을 구분합니다.

  • --baseline-package-assembly-references

    기준 패키지의 특정 대상 프레임워크에 대한 어셈블리 참조 또는 해당 기본 디렉터리에 대한 경로를 지정합니다. 쉼표를 사용하여 여러 값을 구분합니다.

  • --baseline-package-frameworks-to-ignore

    기준 패키지에서 무시할 대상 프레임워크 집합을 지정합니다. 프레임워크 문자열은 기준 패키지의 폴더 이름과 정확히 일치해야 합니다.

예제

다음 명령은 어셈블리의 현재 버전과 기준 버전을 비교합니다.

apicompat --left bin\Release\net8.0\LibApp5.dll --right bin\Release\net8.0\LibApp5-baseline.dll

다음 명령은 패키지의 현재 버전과 기준 버전을 비교합니다.

apicompat package "bin\Release\LibApp5.1.0.0.nupkg" --baseline-package "bin\Release\LibApp5.2.0.0.nupkg"

다음 예제에서는 매개 변수 이름 변경에 대한 검사를 포함하여 어셈블리의 현재 버전과 기준 버전을 비교하는 명령을 보여 줍니다. 또한 이 예제에서는 매개 변수 이름이 변경된 경우 출력이 어떻게 표시되는지를 보여 줍니다.

>apicompat -l LibApp5-baseline.dll -r LibApp5.dll --enable-rule-cannot-change-parameter-name
API compatibility errors between 'LibApp5-baseline.dll' (left) and 'LibApp5.dll' (right):
CP0017: Parameter name on member 'KitchenHelpers.ToastBreadAsync(int, int)'
changed from 'slices' to 'numSlices'.
API breaking changes found. If those are intentional, the APICompat
suppression file can be updated by specifying the '--generate-suppression-file' parameter.