중요
이 항목의 정보는 모든 버전의 Windows 10 이상에 적용됩니다. 여기서는 이러한 버전을 "Windows"라고 하며 필요한 경우 예외를 호출합니다.
모든 버전의 Windows는 핵심 OS라고 하는 OS(운영 체제) 구성 요소의 공통 기반을 공유합니다(일부 컨텍스트에서는 이 공통 기반을 OneCore라고도 함). 핵심 OS 구성 요소에서 Win32 API는 API 집합이라는 기능 그룹으로 구성됩니다.
API 집합의 목적은 지정된 Win32 API가 구현되는 호스트 DLL과 API가 속한 기능 계약 간에 아키텍처 분리를 제공하는 것입니다. API 집합이 구현과 계약 간에 제공하는 분리는 개발자에게 많은 엔지니어링 이점을 제공합니다. 특히 코드에서 API 집합을 사용하면 Windows 디바이스와의 호환성을 향상시킬 수 있습니다.
API 집합은 특히 다음 시나리오를 해결합니다.
Win32 API의 전체 범위는 PC에서 지원되지만 Win32 API의 하위 집합만 HoloLens, XBOX 및 기타 장치와 같은 다른 Windows 장치에서 사용할 수 있습니다. API 집합 이름을 사용하면 앱이 런타임에 현재 디바이스에서 기능을 사용할 수 있는지 여부를 검색할 수 있도록 안정적인 질문을 할 수 있습니다. 쿼리 자체는 IsApiSetImplemented 함수에 의해 수행됩니다.
일부 Win32 API 구현은 여러 Windows 디바이스에서 서로 다른 이름을 가진 DLL에 존재합니다. API 가용성을 검색하고 API 로드를 지연할 때 DLL 이름 대신 API 집합 이름을 사용하면 API가 실제로 구현되는 위치에 관계없이 구현에 대한 올바른 경로를 제공합니다.
자세한 내용은 API 집합 로더 작업 및 API 집합 가용성 검색을 참조하세요.
API 집합과 DLL이 동일한가요?
아니요- API 집합 이름은 파일이 아닌 계약을 식별합니다. 런타임에 로더는 현재 디바이스의 API 집합 스키마를 통해 해당 계약을 확인하고 구현을 호스트하는 DLL에 대한 참조를 라우팅합니다. 호출자로서 정보를 호스팅하는 모듈을 정확히 알 필요가 없는 구현 숨기기 기술입니다.
이 기술을 사용하면 다른 Windows 버전 및 버전에서 모듈을 리팩터링(분할, 통합, 이름 바꾸기 등)할 수 있습니다. 앱은 여전히 연결되고 런타임에 올바른 코드로 라우팅됩니다.
그렇다면 API 집합의 이름에 있는 .dll 이유는 무엇일까요? 그 이유는 DLL 로더가 구현되는 방식입니다. 로더는 DLL을 로드하거나 DLL에 대한 참조를 확인하는 OS의 일부이며, 가져오기 테이블에서 파일 이름의 철자가 지정된 모듈 이름으로 로드할 항목을 식별합니다. API 집합 이름은 동일한 위치에 맞도록 동일한 규칙을 따릅니다.
로더는 또는 api-로 시작하는 이름을 인식하여, 스키마를 통해 계약을 확인하는 로더의 확장인 ext-으로 전달합니다. 이 시점부터 이름은 파일 이름이 아닌 API 집합 명명 규칙에 의해 구문 분석되므로 .dll 접미사는 확인 중인 계약 이름의 일부가 아닙니다.
API 집합 이름을 LoadLibrary에 전달하거나 지연 로드 대상으로 사용할 수 있습니다. 현재 디바이스의 스키마가 해당 계약을 사용 가능한 호스트에 매핑하면 작업이 성공합니다. PC에서 해당 이름의 실제 파일이 반드시 있는 것은 아닙니다. 계약이 현재 디바이스에 매핑되지 않으면 직접 LoadLibrary 가 실패합니다. 지연 로드 참조는 다르게 동작합니다. 프로세스는 여전히 로드되고 API가 호출될 때 나중에 부재 화면이 표시됩니다.
어느 쪽이든 성공적인 링크 또는 로드는 그 자체로 구현이 존재한다는 증거가 아닙니다. 이를 확인하려면 API 집합 가용성 검색을 참조하세요.
통합 라이브러리 연결
코드를 핵심 OS에서 지원되는 Win32 API로 쉽게 제한할 수 있도록 일련의 우산 라이브러리를 제공합니다. 우산 라이브러리를 사용하면 호출하는 각 API에 대한 개별 가져오기 라이브러리를 식별하는 대신 단일 라이브러리를 연결할 수 있습니다.
자세한 내용을 확인하고 대상과 일치하는 우산 라이브러리를 선택하려면 Windows 우산 라이브러리를 참조하세요.
API 집합 계약 이름
API 집합은 라이브러리 로더에서 인식하는 규칙을 따르는 계약 이름으로 식별됩니다.
모든 계약 이름은 다음 규칙을 공유합니다.
- 이름은 문자열 api 또는ext-로 시작합니다.
- 이름의 본문은 영숫자 문자 또는 대시(-)일 수 있습니다. 타일(~)은 그룹 이름 앞에 구분 기호로만 나타납니다.
- 이름은 대소문자를 구분하지 않습니다.
두 가지 형태의 계약 이름이 사용 중이며 둘 중 하나가 발생할 수 있습니다.
버전이 지정된 계약 이름은 l<n>->n<->n< 시퀀스로 끝나며, 여기서 n은 10진수 숫자로 이루어집니다. 예를 들어 ext-ms-win-core-samplefeature-l1-1-0입니다. 후행 번호는 계약의 특정 버전을 식별하며, 이 양식의 이름은 해당 버전의 변경할 수 없는 식별자로 간주되어야 합니다.
계약 별칭에는 버전이 없습니다(예: api-win-core-samplefeature.). 하나의 버전이 아닌 계약 자체를 식별합니다. 계약이 개별적으로 사용 가능한 기능을 명명된 그룹으로 구성하면 그룹 이름을 계약 별칭에 추가하여 타일로 구분 api-win-core-samplefeature~AdvancedOperations하여 그룹 주소를 지정합니다.
samplefeature 여기서 사용되는 이름은 가상의 Windows 구성 요소에 대한 설명 이름입니다.
api- 및 ext- 접두사
접두사는 명명 규칙입니다. 원래는 모든 적격 버전(api-)에 있는 계약과 결석할 수 있는 계약(ext-)을 구분하기 위한 것이었습니다. 이러한 구분은 일관되게 적용되지 않았으며 계약의 이름이 바뀌지 않으면 시간이 지남에 따라 계약의 역할이 변경될 수 있습니다.
로더는 접두사에 아무런 의미도 할당하지 않습니다. 동일한 규칙에 따라 api 및ext- 이름을 확인합니다. 접두사에서 가용성을 유추하지 마세요. 대신 쿼리하세요. 자세한 내용은 API 집합 가용성 확인을 참조하세요.
계약 이름 사용
서로 다른 두 종류의 작업은 계약 이름을 사용합니다.
LoadLibrary 또는 P/Invoke와 같은 로더 작업은 일반적으로 DLL 모듈 이름이 나타나는 동일한 위치에서 계약 이름을 사용합니다. 추가된 .dll 항목은 해당 컨텍스트에서 일반적으로 사용되지만 API 집합 이름 확인에는 필요하지 않으며 계약 이름의 일부가 아닙니다. 실제 DLL 모듈 이름 대신 계약 이름을 사용하여 API가 현재 디바이스에서 실제로 구현되는 위치에 관계없이 구현에 대한 올바른 경로를 보장합니다. 디스크에 해당 계약 이름을 가진 파일이 있을 필요는 없습니다.
가용성 쿼리 예제는 일반적으로 .dll 접미사를 생략하고 API의 주소 지정 방식과 일치하는 양식을 사용합니다.
| API 표면 | 쿼리 양식 | 예시 |
|---|---|---|
| 명명된 그룹 | <contract>~<group> |
api-win-core-samplefeature~AdvancedOperations |
| 기본 그룹 |
~Default 없이 계약 별칭 |
api-win-core-samplefeature |
| 버전이 지정된 계약 | 전체 버전 관리 계약 이름 | ext-ms-win-core-samplefeature-l1-1-0 |
그룹 이름은 버전이 있는 계약 이름과 함께 사용할 수 없습니다.
Win32 API에 대한 API 집합 식별
특정 Win32 API가 API 집합에 속하는지 여부를 식별하려면 API에 대한 참조 설명서의 요구 사항 테이블을 검토합니다. API가 API 집합에 속하는 경우 문서의 요구 사항 테이블에는 API 집합 이름과 API가 API 집합에 처음 도입된 Windows 버전이 나열됩니다. API 집합에 속하는 API의 예제는 다음 문서를 참조하세요.
- AllowSetForegroundWindow
- FindWindowEx
- GetClassFile
API의 헤더가 도우미 함수를 Is<APIName>Present 제공하는 경우 가용성을 테스트할 때 해당 도우미를 사용하는 것이 좋습니다. API를 전달하는 API 집합 또는 그룹에 대한 올바른 이름이 이미 포함되어 있습니다. 자세한 내용은 API 집합 가용성 검색을 참조하세요.