Microsoft.DotNet.ApiCompat.Tool 전역 도구

2025-06-17

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 및 public API를 모두 확인합니다.
--roslyn-assemblies-path <FILE>

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

로그 수준의 상세도를 조절합니다. 허용 가능한 값은 high, normal및 low. 기본값은 normal입니다.
--enable-rule-cannot-change-parameter-name

매개 변수 이름이 public 메서드에서 변경되었는지 여부를 확인하는 규칙을 사용하도록 설정합니다.
--enable-rule-attributes-must-match

특성이 일치하는지 확인하는 규칙을 사용하도록 설정합니다.
--exclude-attributes-file <FILE>

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

어셈블리별 옵션

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

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

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

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

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

패키지별 옵션

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

--baseline-package

현재 패키지의 유효성을 검사할 기준 패키지의 경로를 지정합니다.
--enable-strict-mode-for-compatible-tfms

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

대상 프레임워크에 따라 호환되는 어셈블리에 대해 엄격한 모드 에서 API 호환성의 유효성을 검사합니다.
--enable-strict-mode-for-baseline-validation

패키지 기준 검사를 위해 엄격한 모드 에서 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.