확장 기능 추가

기능은 사용자 지정 명령을 추가하는 것부터 배포 수명 주기에 연결하는 것까지 Azure 개발자 CLI(azd) 확장이 수행할 수 있는 작업을 정의합니다. 이 문서에서는 샘플 확장 만들기 빠른 시작의 Contoso Resource Tagger 샘플 확장에 기능을 추가하는 방법을 설명합니다. 모든 확장에 동일한 패턴을 적용할 수 있습니다.

각 기능에는 capabilities 배열의 항목 과 확장 코드의 해당 구현이라는 두 가지가 필요합니다.

Note

azd 확장 프레임워크는 일반적으로 사용할 수 있습니다. 개별 확장 또는 기능에는 자체 미리 보기 상태가 있을 수 있습니다. GA에 대한 자세한 내용은 정식 출시: Azure Developer CLI(azd) 확장 프레임워크를 참조하세요.

사용 가능한 기능

azd 확장은 다음 기능을 선언할 수 있습니다.

  • custom-commands: 확장 프로그램의 네임스페이스 아래에 새 명령과 명령 그룹을 azd에 추가합니다. 예를 들어, 샘플 확장은 azd tagger show을 추가합니다. 이 기능을 사용하여 사용자가 명령줄에서 직접 실행하는 작업을 노출합니다.
  • lifecycle-events: azd가 실행되는 동안 발생시키는 이벤트(예: preprovision, postprovision 또는 postdeploy)를 구독합니다. 확장은 사용자가 직접 호출하지 않고 해당 지점에서 사용자 지정 논리를 실행합니다. 예를 들어 샘플 확장 프로그램은 리소스가 생성되기 전에 preprovision에 필요한 태그가 있는지 확인합니다.
  • service-target-provider: 새 배포 대상을 등록하므로 azd 서비스를 패키지하고 기본으로 지원하지 않는 호스트에 배포하는 방법을 알 수 있습니다. 서비스 대상은 host의 azure.yaml 값에 매핑됩니다. 예를 들어 타사 플랫폼 또는 내부 호스팅 환경에 서비스를 배포하는 공급자를 추가할 수 있습니다.
  • framework-service-provider: 언어 또는 프레임워크에 대한 지원을 등록하므로 azd 해당 프로젝트 형식을 복원, 빌드 및 패키지하는 방법을 알 수 있습니다. 이는 language의 azure.yaml 값에 매핑됩니다. 예를 들어 기본적으로 인식되지 않는 언어 azd 에 대한 빌드 지원을 추가할 수 있습니다.
  • provisioning-provider: azd가 azd provision 및 azd up 중에 인프라를 프로비저닝하는 방식을 대체합니다. 기본 제공 Bicep 또는 Terraform 흐름 대신 사용자의 확장이 무엇이 수행될지를 정의합니다. 예를 들어 다른 코드 기반 인프라 도구 또는 사용자 지정 배포 API를 통합할 수 있습니다.
  • validation-provider: 프로젝트 또는 환경을 대상으로 실행되는 검사를 azd 유효성 검사 파이프라인에 추가합니다. 예를 들어 배포가 진행되기 전에 명명 규칙, 필수 태그 또는 보안 설정이 있는지 확인할 수 있습니다.
  • mcp-server: GitHub Copilot 같은 AI 에이전트가 검색하고 호출할 수 있는 MCP(모델 컨텍스트 프로토콜) 도구로 확장 기능을 노출합니다. 예를 들어 샘플 확장은 suggest_tags 도구를 노출할 수 있습니다. 자세한 내용은 확장에 MCP 서버 추가를 참조하세요.
  • metadata: 도움말 출력 및 IntelliSense에 표시되는 자세한 명령 설명 및 구성 힌트와 같이 확장을 설명하는 데 사용하는 보다 풍부한 명령 및 구성 메타데이터 azd 를 제공합니다.

이 문서에서는 사용자 지정 명령 및 수명 주기 이벤트의 두 가지 가장 일반적인 기능에 중점을 둡니다. 기능에 대해서는 mcp-server확장에 MCP 서버 추가를 참조하세요. 공급자 기능에 대한 자세한 내용은 확장 프레임워크 참조를 참조하세요.

사용자 지정 명령 추가

이 custom-commands 기능을 사용하면 확장에서 .의 네임스페이스 아래에 새 명령을 등록할 수 있습니다 azd. 샘플 확장은 azd tagger show 명령에 이미 이 기능을 사용합니다.

  1. extension.yaml에서 해당 기능을 선언하세요.

    capabilities:
  - custom-commands

  2. 수동으로 선언할 필요가 없도록 표준 azdext.NewExtensionRootCommand 플래그 및 환경 변수 처리를 등록하는 도우미를 사용하여 azd 명령을 빌드합니다.

    import "github.com/azure/azure-dev/cli/azd/pkg/azdext"

func NewRootCommand() *cobra.Command {
    rootCmd, extCtx := azdext.NewExtensionRootCommand(azdext.ExtensionCommandOptions{
        Name:  "tagger",
        Use:   "tagger <command> [options]",
        Short: "Standardize and report Azure resource tags.",
    })

    rootCmd.AddCommand(newShowCommand(extCtx))
    // Add other subcommands here.
    return rootCmd
}

    도우미는 *ExtensionContext 및 Environment와 같은 표준 플래그의 결정된 값을 노출하는 OutputFormat를 반환합니다. 표준 플래그를 다시 선언하는 대신 컨텍스트를 하위 명령어에 전달하고, 해당 RunE 핸들러 내부에서 그 컨텍스트를 읽으세요.

수명 주기 이벤트 구독

lifecycle-events 기능을 사용하면 확장에서 preprovision 또는 postdeploy와 같은 프로젝트 및 서비스의 수명 주기 이벤트 동안 사용자 지정 논리를 실행할 수 있습니다. 샘플 확장의 경우 이벤트를 사용하여 리소스를 preprovision 프로비전하기 전에 azd 필요한 태그가 설정되어 있는지 확인합니다.

  1. extension.yaml에서 해당 기능을 선언하세요.

    capabilities:
  - custom-commands
  - lifecycle-events

  2. 확장에 listen 명령을 추가합니다. azd 는 이벤트에 사용되는 양방향 연결을 설정하기 위해 이 명령을 호출합니다. azdext.NewExtensionHost 빌더를 사용하여 이벤트 핸들러를 등록하세요:

    func newListenCommand() *cobra.Command {
    return &cobra.Command{
        Use:    "listen",
        Short:  "Starts the extension and listens for azd events.",
        Hidden: true,
        RunE: func(cmd *cobra.Command, args []string) error {
            ctx := azdext.WithAccessToken(cmd.Context())

            azdClient, err := azdext.NewAzdClient()
            if err != nil {
                return fmt.Errorf("failed to create azd client: %w", err)
            }
            defer azdClient.Close()

            host := azdext.NewExtensionHost(azdClient).
                WithProjectEventHandler(
                    "preprovision",
                    func(ctx context.Context, args *azdext.ProjectEventArgs) error {
                        fmt.Printf("Verifying required tags for project: %s\n", args.Project.Name)
                        // Add your tag validation logic here.
                        return nil
                    },
                )

            // Run blocks until azd closes the connection.
            if err := host.Run(ctx); err != nil {
                return fmt.Errorf("failed to run extension: %w", err)
            }

            return nil
        },
    }
}

  3. 루트 명령에 listen 명령을 등록합니다.

    rootCmd.AddCommand(newListenCommand())

사용자가 azd provision 또는 azd up을(를) 실행하면 azd가 사용자의 확장을 호출하고, 리소스를 프로비저닝하기 전에 preprovision 처리기를 호출합니다.

서비스 이벤트 필터링

서비스 이벤트 처리기는 선택적 필터링을 지원하므로 특정 서비스 유형만 처리합니다. 예를 들어, Python 컨테이너 앱 서비스에서만 prepackage 이벤트를 처리할 수 있습니다.

host := azdext.NewExtensionHost(azdClient).
    WithServiceEventHandler(
        "prepackage",
        func(ctx context.Context, args *azdext.ServiceEventArgs) error {
            fmt.Printf("Packaging service: %s\n", args.Service.Name)
            return nil
        },
        &azdext.ServiceEventOptions{
            Host:     "containerapp",
            Language: "python",
        },
    )

다시 빌드 및 테스트

기능을 추가한 후 확장을 다시 빌드하고 새 동작을 테스트합니다.

  1. 감시자를 사용하는 경우 변경 내용이 자동으로 다시 빌드됩니다. 그렇지 않으면 수동으로 빌드합니다.

    azd x build

  2. 기능을 테스트합니다. 수명 주기 이벤트의 경우 이벤트를 트리거하는 명령을 실행합니다(예: azd provision.).

관련 콘텐츠

  • Last updated on