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-internalsinternalAPI와publicAPI를 모두 확인합니다.--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-modestrict 모드에서 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.
.NET