Azure Developer CLI(azd) 확장 기능은 새 명령을 추가하고, 워크플로를 자동화하며, 다른 서비스를 azd와 통합합니다. 이 문서에서는 개발자 도구, SDK(소프트웨어 개발 키트) 등 확장을 빌드하기 전에 이해해야 하는 개념과 실행 중인 확장과 통신하는 방법을 azd 설명합니다. 사용자 관점에서 확장이 무엇인지 알아보려면 확장 개요를 참조하세요.
개발자 확장 프로그램
확장을 빌드하는 가장 빠른 방법은 개발자 확장(azd)을 microsoft.azd.extensions 사용하는 것입니다. 개발자 확장은 확장을 스캐폴드, 빌드, 패키지 및 게시하는 네임스페이스 아래에 azd x 명령 모음을 추가합니다.
| Command | Description |
|---|---|
azd x init |
선택한 언어로 새 확장 프로젝트를 스캐폴드합니다. |
azd x build |
로컬 개발을 위한 확장 이진 파일을 빌드합니다. |
azd x watch |
프로젝트에서 변경 내용을 감시하고 확장을 자동으로 다시 빌드하고 설치합니다. |
azd x pack |
게시를 준비하기 위해 확장 아티팩트 패키지를 만듭니다. |
azd x release |
확장에 대한 GitHub 릴리스를 만듭니다. |
azd x publish |
확장 레지스트리를 새 확장 메타데이터로 업데이트합니다. |
샘플 확장 빌드 빠른 시작에서는 개발자 확장을 설치하고 첫 번째 확장을 스캐폴드하는 방법을 보여 줍니다.
개발자 확장은 레지스트리 기반 게시 워크플로 및 이식 가능한 번들 배포를 지원합니다. 릴리스 및 레지스트리 게시를 위한 플랫폼 아티팩트를 만들거나 레지스트리를 호스팅하지 않고 확장을 공유해야 하는 경우 자체 포함 .zip 번들을 만드는 데 사용합니다azd x pack. 번들은 로컬 파일에서 설치하거나 HTTPS URL에서 원격으로 호스트할 수 있습니다. 단계별 지침은 확장 게시를 참조하세요.
확장 프레임워크 및 gRPC
azd 및 확장은 gRPC를 통해 통신하는 별도의 프로세스로 실행됩니다. 확장 명령을 호출하면 다음 단계가 수행됩니다.
-
azd는 임의 포트에서 gRPC 서버를 시작하고 서버 주소를 사용하여 환경 변수를 설정합니다AZD_SERVER. -
azd는 명령의AZD_ACCESS_TOKEN수명 동안 서비스에 대한 확장 액세스 권한을azd부여하는 서명된 JWT(JSON Web Token)인 환경 변수를 설정합니다. -
azd는 확장 명령을 호출하고 현재 인수, 플래그 및 환경 변수를 전달합니다. - 사용자의 확장은 gRPC 클라이언트를 사용해 사용자에게 메시지를 표시하거나 프로젝트 구성을 읽는 것과 같은 프레임워크 서비스를 통해
azd와 다시 통신합니다. -
azd명령이 완료되기를 기다렸다가 0이 아닌 종료 코드를 오류로 보고합니다.
이 모델을 사용하면 확장이 내부 azd 상태에 직접 액세스하지 않고 일관되고 안전한 방식으로 상호 작용 azd 할 수 있습니다.
프로젝트 수준의 확장 요구 사항
프로젝트는 필요한 확장을 선언할 수 있습니다 azure.yaml. 이 섹션을 requiredVersions.extensions 사용하여 확장 ID 및 버전 제약 조건을 나열하여 azd 프로젝트를 만족하는 버전을 확인할 수 있습니다.
requiredVersions:
extensions:
azure.ai.agents: ">=1.0.0"
contoso.azd.tagger: "^2.0.0"
프로젝트가 확장 제공 호스트, 공급자, 수명 주기 처리기, 유효성 검사 또는 명령에 종속되는 경우 필요한 확장을 선언합니다. 정확한 스키마 및 지원되는 버전 구문은 다음을 참조하세요 requiredVersions.
The azdext SDK
패키지는 azdext 확장 프레임워크에 대한 Go SDK입니다. 확장 논리에 집중할 수 있도록 통신 세부 정보를 처리하는 gRPC 클라이언트 및 도우미를 제공합니다. SDK에는 다음을 위한 도우미가 포함되어 있습니다.
- 표준
azd플래그 및 환경 변수 처리를 등록하는 루트 명령을 빌드합니다. - 발신 요청에
azd액세스 토큰을 추가합니다. -
azdProject, Environment, Account 및 Prompt 서비스와 같은 프레임워크 서비스를 호출합니다. - 공식 소스 확장 프로그램의 이름이 지정된 사용 이벤트를
TelemetryService.ReportUsagegRPC API를 통해 보고합니다. API 사용량 세부 정보는 SDK를 사용하여 azd와 통신을 참조하세요. - 확장 호스트를 통해 수명 주기 이벤트 처리기 및 사용자 지정 공급자를 등록합니다.
확장에서 서비스를 호출 azd 하는 방법을 알아보려면 SDK를 사용하여 azd와 통신을 참조하세요.
확장 기능
기능은 확장에서 수행할 수 있는 작업을 선언합니다. 매니페스트에 extension.yaml 확장의 기능을 나열하고 azd 런타임에 해당 권한을 부여합니다. 사용 가능한 기능은 다음과 같습니다.
-
custom-commands: 에 새 명령 그룹 및 명령을 추가합니다azd. -
lifecycle-events: 프로젝트 및 서비스 수명 주기 이벤트(예:preprovision및postdeploy.)를 구독합니다. -
mcp-server: AI 에이전트에 대한 MCP(모델 컨텍스트 프로토콜) 도구를 제공합니다. -
service-target-provider: 사용자 지정 서비스 배포 대상을 제공합니다. -
framework-service-provider: 사용자 지정 언어 및 프레임워크 빌드 지원을 제공합니다. -
provisioning-provider: 사용자 지정 인프라 프로비저닝 환경을 제공합니다. -
validation-provider:azd유효성 검사 파이프라인에 유효성 검사 확인 항목을 추가합니다. -
metadata: 도움말 출력 및 IntelliSense에 대한 다양한 명령 및 구성 메타데이터를 제공합니다.
확장에 기능을 추가하는 방법을 알아보려면 확장 기능 추가를 참조하세요.
지원되는 언어
gRPC를 지원하는 모든 언어로 azd 확장 프로그램을 빌드할 수 있으며, azd x init 에는 여러 언어용 스타터 템플릿이 포함되어 있습니다. Go는 최고 수준의 azdext SDK 도우미를 포함하여 가장 완벽한 지원을 제공합니다. 따라서 이 섹션의 문서에서는 모든 예제에 Go를 사용합니다.
| Language | 지원 수준 |
|---|---|
| Go | 최고의 지원 및 최고 수준의 SDK 도우미. |
| .NET(C#) | 시작 템플릿과 강력한 통합. |
| Python | 시작 템플릿과 잘 통합되었습니다. |
| 자바 스크립트 | 시작 템플릿과 기본 통합. |
Go 이외의 언어로 작성된 확장의 경우 리포지토리의 proto 파일 에서 gRPC 클라이언트를 azure/azure-dev 생성할 수 있습니다. 현재 언어 지원 상태는 업스트림 확장 프레임워크 설명서를 참조하세요.
확장 레지스트리
레지스트리 원본 또는 확장 번들을 통해 확장을 배포합니다. 레지스트리 원본은 사용 가능한 확장 및 해당 아티팩트 설명 URL 기반 또는 파일 기반 매니페스트입니다. 확장 번들은 레지스트리를 호스팅하지 않으려는 경우 로컬 파일이나 원격 HTTPS URL에 호스팅된 위치에서 직접 설치할 수 있는 이동 가능한 .zip 패키지입니다.
-
공식 레지스트리는 미리 구성되어
azd있으며 심사된 자사 확장을 호스트합니다. 공식 확장은 azure/azure-dev 리포지토리의 포크로 개발됩니다. - URL 기반 원본을 사용하면 원격 공용 또는 프라이빗 레지스트리 매니페스트에서 설치할 수 있습니다.
- 파일 기반 원본을 사용하면 개발, 테스트 또는 오프라인 시나리오를 위해 로컬 레지스트리 매니페스트에서 설치할 수 있습니다.
- 개발 및 나이틀리 레지스트리는 개발 중이거나 자동으로 빌드되는 자사 확장을 위해 사용자가 선택적으로 사용할 수 있는 소스입니다. 개발 레지스트리의 확장은 서명되지 않으며 Azure 지원 적용되지 않으며 예고 없이 변경하거나 제거할 수 있습니다.
레지스트리에 확장을 게시하는 방법을 알아보려면 확장 게시를 참조하세요.