Conceitos de desenvolvimento de extensão

CLI do Desenvolvedor do Azure (azd) extensões adicionam novos comandos, automatizam fluxos de trabalho e integram outros serviços com azd. Este artigo explica os conceitos que você precisa entender antes de criar uma extensão, como as ferramentas de desenvolvedor, o SDK (software development kit) e como azd se comunica com uma extensão em execução. Para saber quais extensões são da perspectiva do usuário, confira a visão geral das extensões.

A extensão do desenvolvedor

A maneira mais rápida de criar extensões é usar a extensão de azd desenvolvedor (microsoft.azd.extensions). A extensão de desenvolvedor adiciona um conjunto de comandos no namespace azd x que criam a estrutura, compilam, empacotam e publicam sua extensão:

O início rápido Criar uma extensão de exemplo mostra como instalar a extensão para desenvolvedor e criar a estrutura inicial da sua primeira extensão.

A extensão do desenvolvedor oferece suporte a fluxos de trabalho de publicação baseados em registro central e à distribuição de pacotes portáteis. Use azd x pack para criar artefatos de plataforma para publicação de versão e registro ou crie um pacote .zip autocontido quando precisar compartilhar uma extensão sem hospedar um registro. Os pacotes podem ser instalados de um arquivo local ou hospedados remotamente em uma URL HTTPS. Para obter diretrizes passo a passo, consulte Publicar uma extensão.

O framework de extensão e o gRPC

azd e as extensões são executadas como processos separados que se comunicam por meio de gRPC. Quando você invoca um comando de extensão, as seguintes etapas ocorrem:

1. azd inicia um servidor gRPC em uma porta aleatória e define a variável de AZD_SERVER ambiente com o endereço do servidor.
2. azd define a AZD_ACCESS_TOKEN variável de ambiente, que é um JWT (Token Web JSON) assinado que concede acesso de extensão aos azd serviços durante o tempo de vida do comando.
3. azd invoca o comando de extensão e passa os argumentos, sinalizadores e variáveis de ambiente atuais.
4. Sua extensão usa um cliente gRPC para se comunicar com azd por meio dos serviços do framework, como solicitar informações ao usuário ou ler a configuração do projeto.
5. azd aguarda a conclusão do comando e relata um código de saída diferente de zero como um erro.

Esse modelo permite que as extensões interajam azd de forma consistente e segura sem acessar diretamente o estado interno azd .

Requisitos de extensão no nível do projeto

Os projetos podem declarar as extensões necessárias em azure.yaml. Use a requiredVersions.extensions seção para listar IDs de extensão e restrições de versão para azd resolver as versões que atendem ao projeto.

requiredVersions:
  extensions:
    azure.ai.agents: ">=1.0.0"
    contoso.azd.tagger: "^2.0.0"

Declare as extensões necessárias quando um projeto depende de hosts, provedores, manipuladores de ciclo de vida, validação ou comandos fornecidos por extensão. Para obter o esquema exato e a sintaxe de versão com suporte, consulte requiredVersions.

O SDK do azdext

O azdext pacote é o SDK do Go para a estrutura de extensão. Ele fornece um cliente gRPC e auxiliares que lidam com os detalhes de comunicação, para que você possa se concentrar em sua lógica de extensão. O SDK inclui auxiliares para:

• Crie um comando raiz que registre os sinalizadores padrão azd e a manipulação da variável de ambiente.
• Anexe o azd token de acesso às requisições de saída.
• Chame os serviços do framework azd, como os serviços Projeto, Ambiente, Conta e Prompt.
• Relatar eventos de uso nomeados por meio da TelemetryService.ReportUsage API gRPC para extensões de origem oficial. Para obter detalhes de uso da API, consulte Comunicar-se com o azd usando o SDK.
• Registre manipuladores de eventos do ciclo de vida e provedores personalizados por meio de um host de extensão.

Para aprender a chamar serviços azd da sua extensão, consulte Comunicar-se com o azd usando o SDK.

Funcionalidades de extensão

As capacidades declaram o que uma extensão pode fazer. Liste as capacidades de uma extensão no extension.yaml manifesto, e azd concede as permissões correspondentes em tempo de execução. Os recursos disponíveis incluem:

• custom-commands: adicione novos grupos de comandos e comandos a azd.
• lifecycle-events: Assinar os eventos de ciclo de vida do projeto e do serviço, como preprovision e postdeploy.
• mcp-server: forneça ferramentas do PROTOCOLO MCP (Model Context Protocol) para agentes de IA.
• service-target-provider: forneça destinos de implantação de serviço personalizado.
• framework-service-provider: Fornecer suporte a builds para linguagens e frameworks personalizados.
• provisioning-provider: forneça uma experiência de provisionamento de infraestrutura personalizada.
• validation-provider: Contribuir com verificações de validação para o pipeline de validação azd.
• metadata: Fornecer metadados ricos de comando e configuração para a saída de ajuda e o IntelliSense.

Para saber como adicionar recursos a uma extensão, consulte Adicionar recursos de extensão.

Idiomas com suporte

Você pode criar azd extensões em qualquer idioma que dê suporte a gRPC e azd x init inclui modelos de início para vários idiomas. O Go tem o suporte mais completo, incluindo auxiliares do SDK de primeira classe azdext , portanto, os artigos nesta seção usam o Go para todos os exemplos.

Para extensões desenvolvidas em linguagens diferentes de Go, você pode gerar clientes gRPC a partir dos arquivos proto no repositório azure/azure-dev. Para consultar o estado atual do suporte a idiomas, consulte a documentação upstream do framework de extensão.

Registros de extensões

Você distribui extensões por meio de fontes de registro ou pacotes de extensão. As fontes do Registro são manifestos baseados em URL ou baseados em arquivo que descrevem extensões disponíveis e seus artefatos. Os pacotes de extensão são pacotes portáteis .zip que você pode instalar diretamente de um arquivo local ou hospedar remotamente em uma URL HTTPS quando não quiser hospedar um registro.

• O registro oficial vem pré-configurado em azd e hospeda extensões validadas e oficiais. As extensões oficiais são desenvolvidas em uma bifurcação do repositório azure/azure-dev .
• As fontes baseadas em URL permitem que você instale de manifestos de registro públicos ou privados remotos.
• Fontes baseadas em arquivo permitem instalar a partir de manifestos de registro local para cenários de desenvolvimento, teste ou sem conexão.
• Os repositórios de desenvolvimento e noturnos são fontes opcionais para conteúdo em desenvolvimento e extensões oficiais compiladas automaticamente. As extensões no registro de desenvolvimento não são atribuídas, não cobertas por Suporte do Azure e podem ser alteradas ou removidas sem aviso prévio.

Para saber como publicar uma extensão em um registro, consulte Publicar uma extensão.

Conteúdo relacionado

• Criar uma extensão de exemplo
• Definir o manifesto da extensão
• Adicionar recursos de extensão