DotNet API Diff

프로그램 소개

DotNet API Diff는 .NET 어셈블리의 공개 API를 비교하여 브레이킹 체인지, 추가, 제거, 수정을 감지하는 명령줄 도구입니다. jbrinkman이 개발했으며, 라이브러리 유지 관리자와 개발 팀이 API 진화를 추적하고 시맨틱 버저닝을 준수하도록 돕습니다. 콘솔, JSON, XML, HTML, 마크다운 등 다양한 출력 형식을 지원하며, CI/CD 파이프라인에 통합하기 적합합니다.

주요 기능

포괄적인 API 분석

타입, 메서드, 속성, 필드, 이벤트 및 그들의 시그니처를 분석하여 API 변경 사항을 종합적으로 검사합니다.

브레이킹 체인지 감지

브레이킹 체인지와 비브레이킹 추가를 자동으로 식별 및 분류하여 API 호환성 영향을 명확히 보여줍니다.

다중 출력 형식 지원

콘솔, JSON, XML, HTML, 마크다운 형식으로 보고서를 생성하여 다양한 환경에서 활용할 수 있습니다.

유연한 필터링

네임스페이스, 타입, 멤버 패턴을 포함하거나 제외하여 비교 대상을 세부적으로 제어할 수 있습니다.

구성 파일 기반 설정

JSON 구성 파일을 통해 복잡한 비교 시나리오를 정의하고, 네임스페이스 매핑, 타입 매핑, 제외 규칙, 브레이킹 체인지 규칙 등을 세부적으로 설정할 수 있습니다.

CI/CD 통합 최적화

시맨틱 버저닝과 일치하는 종료 코드를 반환하여 GitHub Actions, Azure DevOps 등 CI/CD 파이프라인에 쉽게 통합할 수 있습니다.

다운로드·설치 방법

Windows에서는 Chocolatey 패키지 관리자를 통해 간단히 설치할 수 있습니다. 공식 배포 채널은 GitHub 릴리스 페이지이며, ZIP 형식의 설치 파일을 제공합니다.

Chocolatey를 통한 설치 (Windows)

관리자 권한으로 PowerShell을 열고 다음 명령을 실행합니다:

choco install dotnetapidiff

수동 설치 방법

1. GitHub 릴리스 페이지에서 최신 버전의 ZIP 파일을 다운로드합니다. (Windows용: dotnet-api-diff-win-x64.zip 또는 dotnet-api-diff-win-arm64.zip)

2. 다운로드한 ZIP 파일을 압축 해제합니다.

3. 추출된 실행 파일의 경로를 시스템 환경 변수 PATH에 추가합니다.

4. 명령 프롬프트에서 dotnetapidiff 명령을 실행하여 정상 설치 여부를 확인합니다.

기본 사용법

두 .NET 어셈블리의 API를 비교하는 기본적인 사용 방법은 다음과 같습니다.

기본 비교 실행

두 어셈블리 파일을 지정하여 콘솔에 결과를 출력합니다:

dotnetapidiff compare MyLibrary.v1.dll MyLibrary.v2.dll

JSON 형식 보고서 생성

–output json 옵션을 사용하여 JSON 형식의 보고서를 생성합니다:

dotnetapidiff compare source.dll target.dll –output json

파일에 보고서 저장

마크다운 형식으로 보고서를 생성하고 파일에 저장합니다:

dotnetapidiff compare source.dll target.dll –output markdown > api-changes.md

이런 경우에 유용합니다

.NET 라이브러리의 새 버전을 출시하기 전에 API 호환성을 검증해야 하는 개발 팀에게 유용합니다. 특히 브레이킹 체인지가 있는지 확인하여 시맨틱 버저닝 규칙에 따라 메이저/마이너/패치 버전을 결정하는 데 도움을 줍니다. CI/CD 파이프라인에 통합하여 풀 리퀘스트마다 자동으로 API 호환성을 검사하고, 브레이킹 체인지가 감지되면 알림을 받을 수 있습니다.

지원 환경·시스템 요구사항

이 도구는 .NET 8.0 SDK 이상이 설치된 Windows, macOS, Linux 환경에서 실행됩니다. 비교 대상 어셈블리는 .NET Framework, .NET Core, .NET 5 이상 버전과 호환되어야 하며, 실행 환경에는 해당 어셈블리의 의존성이 모두 해결되어 있어야 합니다.

최신 버전·업데이트

현재 버전은 1.0.0이며, GitHub 저장소의 릴리스 페이지에서 최신 버전 정보를 확인할 수 있습니다. 업데이트는 Chocolatey를 통해 choco upgrade dotnetapidiff 명령으로 수행할 수 있으며, 수동 설치의 경우 최신 ZIP 파일을 다시 다운로드하여 교체 설치하면 됩니다.

제한 사항·확인 사항

이 도구는 공개 API만 비교하며, 비공개(internal) 타입이나 멤버는 기본적으로 제외됩니다. 내부 타입을 포함하려면 –include-internals 옵션을 사용해야 합니다. 또한, 비교 대상 어셈블리가 로드되지 못하면 종료 코드 3(Assembly Load Error)을 반환하므로, 어셈블리의 대상 프레임워크가 실행 환경과 호환되는지 확인해야 합니다. 매우 큰 어셈블리의 경우 메모리 사용량이 증가할 수 있으므로, –filter 옵션을 사용하여 비교 범위를 제한하는 것이 좋습니다.