확장 매니페스트 정의

모든 Azure 개발자 CLI(azd) 확장에는 해당 메타데이터 및 기능을 설명하는 매니페스트가 포함되어 extension.yaml 있습니다. azd 는 사용자가 확장을 검색, 설치 및 이해하는 데 도움이 되도록 확장 레지스트리에서 이 메타데이터를 사용합니다. 이 문서에서는 샘플 확장 빌드 빠른 시작에서 Contoso Resource Tagger 샘플 확장을 사용하는 매니페스트 속성을 설명합니다. 모든 확장에 동일한 개념을 적용할 수 있습니다.

Note

azd 확장은 현재 베타 버전입니다.

매니페스트 속성

매니페스트는 extension.yaml 다음 속성을 지원합니다.

필수 속성

모든 매니페스트에는 다음 속성이 포함되어야 합니다.

재산 Description
id 확장에 대한 고유 식별자(예: contoso.azd.tagger.)
version MAJOR.MINOR.PATCH 형식의 시맨틱 버전입니다.
displayName 사람이 읽을 수 있는 확장 이름입니다.
description 확장에 대한 자세한 설명입니다.

각 매니페스트에는 둘 중 하나 capabilities 또는 dependencies.도 포함되어야 합니다. 명령 또는 공급자를 제공하는 확장은 capabilities를 선언합니다. 대신 확장 팩이 선언됩니다dependencies.

선택적 속성

매니페스트는 다음과 같은 선택적 속성도 지원합니다.

재산 Description
namespace 확장의 명령을 그룹화하는 명령 네임스페이스(예: tagger.)
entryPoint 진입점 역할을 하는 실행 파일 또는 스크립트입니다.
language 확장이 작성된 프로그래밍 언어(예: go.
capabilities 확장 기능의 배열입니다.
usage 확장을 사용하는 방법에 대한 지침입니다.
examples 이름, 설명 및 사용량이 있는 사용 예제의 배열입니다.
tags 분류 및 필터링을 위한 키워드입니다.
dependencies 이 확장이 의존하는 다른 확장입니다.
providers 확장이 등록하는 공급자 목록입니다.
platforms 플랫폼별 메타데이터입니다.
mcp 모델 컨텍스트 프로토콜 서버 구성.
requiredAzdVersion 확장을 사용하기 위해 필요한 azd 버전에 대한 시맨틱 버전 제약 조건(예: >= 1.24.0).

매니페스트 예제

다음 예제에서는 Contoso Resource Tagger 샘플 확장의 extension.yaml 매니페스트를 보여 줍니다:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/cli/azd/extensions/extension.schema.json

id: contoso.azd.tagger
namespace: tagger
displayName: Contoso Resource Tagger
description: Standardize and report Azure resource tags for an azd project.
usage: azd tagger <command> [options]
version: 0.1.0
language: go
capabilities:
  - custom-commands

examples:
  - name: show
    description: Displays a greeting from the extension.
    usage: azd tagger show

tags:
  - tags
  - governance
  - example

$schema 파일 맨 위에 있는 주석을 사용하면 YAML 언어 서버를 지원하는 편집기에서 유효성 검사 및 IntelliSense를 사용할 수 있습니다.

기능 선언

배열은 capabilities 확장에서 수행할 수 있는 작업을 선언합니다. azd 는 런타임에 해당 권한을 부여하고 일치 기능이 선언되지 않은 경우 일부 프레임워크 서비스가 사용 권한 오류와 함께 실패합니다. 샘플 확장은 custom-commands만으로 시작합니다:

capabilities:
  - custom-commands

다른 문서에서 기능을 추가하면 더 많은 기능이 추가됩니다. 예를 들어 확장 기능 추가lifecycle-events및 확장에 MCP 서버 추가 추가 mcp-server 사용 가능한 기능은 다음과 같습니다.

  • custom-commands: 네임스페이스 azd 아래에 새 명령을 추가합니다(예: azd tagger show.).
  • lifecycle-events: azd에서 preprovision 또는 postdeploy와 같은 이벤트가 발생할 때 사용자 지정 논리를 실행합니다.
  • mcp-server: AI 에이전트가 호출할 수 있는 모델 컨텍스트 프로토콜 도구를 노출합니다.
  • service-target-provider: host에서 기본적으로 지원하지 않는 azd용 사용자 지정 배포 대상을 추가합니다.
  • framework-service-provider: 기본적으로 language에서 인식하지 못하는 azd에 대한 빌드 및 패키지 지원을 추가합니다.
  • provisioning-provider: 인프라를 사용자 지정 구현으로 프로비전하는 방법을 azd 대체합니다.
  • validation-provider: azd 유효성 검사 파이프라인에서 실행되는 검사를 추가합니다.
  • metadata: 도움말 출력 및 IntelliSense에 대한 보다 풍부한 명령 및 구성 메타데이터를 제공합니다.

예제가 포함된 각 기능에 대한 자세한 설명은 확장 기능 추가를 참조하세요.

사용 예제 추가

배열은 examples 확장을 사용하는 일반적인 방법을 문서화합니다. azd 는 사용자가 확장에 대한 세부 정보를 볼 때 다음 예제를 표시합니다.

examples:
  - name: show
    description: Displays a greeting from the extension.
    usage: azd tagger show

공급자 등록

확장에서 사용자 지정 서비스 대상 또는 프레임워크 서비스를 제공하는 경우, providers 섹션에서 이를 선언하여 azd가 확장에서 제공하는 내용을 알 수 있도록 하세요:

providers:
  - name: tagger
    type: service-target
    description: Deploys tagged resources to Azure.

플랫폼별 구성 추가

각 운영 체제의 platforms 실행 파일 이름과 같은 플랫폼별 메타데이터를 제공하려면 이 속성을 사용합니다.

platforms:
  windows:
    executable: tagger.exe
  linux:
    executable: tagger
  darwin:
    executable: tagger

종속성 선언

확장 프로그램은 dependencies 배열을 사용하여 다른 확장 프로그램에 종속될 수 있습니다. 종속성은 의미 체계 버전 관리 제약 조건을 지원합니다.

dependencies:
  - id: microsoft.azd.core
    version: "^1.0.0"

azd 는 각 제약 조건을 충족하고 종속성의 속성에 따라 현재 azd 버전과 호환되는 가장 높은 종속성 버전으로 설치하거나 업그레이드합니다 requiredAzdVersion . 제약 조건을 충족하는 릴리스가 호환되지 않는 릴리스뿐인 경우, azd는 호환성 오류를 보고하고 이를 해결하는 방법에 대한 지침을 제공합니다. 일반적인 제약 조건 형식은 다음과 같습니다.

  • ^1.0.0: 버전 1.x.x와 호환됩니다.
  • ~1.2.0: 버전 1.2.x와 호환됩니다.
  • >=1.0.0 <2.0.0: 버전 범위입니다.

확장 팩을 사용하여 확장 그룹화

확장 팩은 사용자가 단일 명령으로 설치할 수 있도록 관련 확장을 그룹화하는 매니페스트입니다. 팩은 dependencies 실행 파일, 명령 네임스페이스 또는 자체 기능을 선언하지만 제공하지는 않습니다. 팩을 사용하여 제품 패밀리 또는 시나리오 번들 같은 큐레이팅된 확장 집합을 게시합니다.

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/cli/azd/extensions/extension.schema.json

id: contoso.tools
displayName: Contoso Tools Extension Pack
description: Installs the Contoso azd extensions.
version: 0.1.0

dependencies:
  - id: contoso.azd.tagger
    version: "~0.1.0"

팩을 재귀적으로 설치하면 해당 종속성이 설치됩니다. 각 종속성에 azd 대해 선언된 제약 조건을 충족하고 종속성의 requiredAzdVersion 속성에 따라 현재 azd 버전과 호환되는 가장 높은 버전을 선택합니다.

관련 콘텐츠

  • Last updated on