Conceitos de desenvolvimento de extensões

azd do Azure Developer CLI () adicionam novos comandos, automatizam fluxos de trabalho e integram outros serviços com azd. Este artigo explica os conceitos que precisa de compreender antes de construir uma extensão, como as ferramentas para desenvolvedores, o kit de desenvolvimento de software (SDK) e como azd comunica com uma extensão em execução. Para saber o que são extensões do ponto de vista do utilizador, veja a visão geral das extensões.

A extensão para desenvolvedores

A forma mais rápida de construir extensões é usar a azd extensão developer (microsoft.azd.extensions). A extensão para desenvolvedores adiciona um conjunto de comandos sob o azd x namespace que estruturam, constroem, empacotam e publicam a sua extensão:

O Início rápido para criar uma extensão de exemplo mostra como instalar a extensão de programador e criar a estrutura base da tua primeira extensão.

A extensão para desenvolvedores suporta fluxos de trabalho de publicação baseados em registos e distribuição portátil de pacotes. Use azd x pack para criar artefactos da plataforma para lançamento e publicação de registos, ou crie um pacote autónomo .zip quando precisar de partilhar uma extensão sem alojar um registo. Para orientações passo a passo, veja Publicar uma extensão.

A plataforma de extensões e o gRPC

azd e as extensões executam-se como processos separados que comunicam através de gRPC. Quando invoca um comando de extensão, ocorrem os seguintes passos:

1. azd inicia um servidor gRPC numa porta aleatória e define a AZD_SERVER variável de ambiente com o endereço do servidor.
2. azd define a AZD_ACCESS_TOKEN variável de ambiente, que é um JSON Web Token (JWT) assinado, que concede à extensão acesso a azd serviços durante a vida útil do comando.
3. azd invoca o comando de extensão e passa os argumentos, flags e variáveis de ambiente atuais.
4. A sua extensão utiliza um cliente gRPC para comunicar de volta com azd através dos serviços da framework, como apresentar pedidos ao utilizador ou ler a configuração do projeto.
5. azd espera que o comando seja concluído e reporta um código de saída diferente de zero como erro.

Este modelo permite que as extensões interajam com azd de forma consistente e segura, sem acederem diretamente ao estado azd interno.

Requisitos de extensão ao nível do Project

Os projetos podem declarar as extensões que necessitam em azure.yaml. Use a requiredVersions.extensions secção para listar IDs de extensão e restrições de versão, para azd poder resolver as versões que satisfazem o 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, fornecedores, handlers do ciclo de vida, validação ou comandos fornecidos pela extensão. Para o esquema exato e a sintaxe da versão suportada, veja requiredVersions.

O SDK azdext

O pacote azdext é o SDK Go para a estrutura de extensões. Fornece um cliente gRPC e ajudantes que tratam dos detalhes da comunicação por ti, para que possas focar-te na lógica de extensão. O SDK inclui auxiliares para:

• Crie um comando raiz que regista as flags padrão azd e o tratamento das variáveis de ambiente.
• Anexe o azd token de acesso aos pedidos enviados.
• Invocar azd serviços da framework, como os serviços Project, Environment, Account e Prompt.
• Registe manipuladores de eventos do ciclo de vida e fornecedores personalizados através de um anfitrião de extensões.

Para aprender como chamar azd serviços a partir da sua extensão, veja Comunicar com azd usando o SDK.

Capacidades de extensão

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

• custom-commands: Adicionar novos grupos de comandos e comandos a azd.
• lifecycle-events: Subscreva-se a eventos do ciclo de vida de projetos e serviços, como preprovision e postdeploy.
• mcp-server: Fornecer ferramentas do Protocolo de Contexto de Modelo (MCP) para agentes de IA.
• service-target-provider: Fornecer alvos personalizados de implementação de serviços.
• framework-service-provider: Fornecer suporte de construção personalizada de linguagens e frameworks.
• provisioning-provider: Proporcionar uma experiência personalizada de provisionamento de infraestruturas.
• validation-provider: Contribuir para verificações de validação no canal de validação azd.
• metadata: Forneça metadados detalhados sobre comandos e configuração para a saída da ajuda e o IntelliSense.

Para saber como adicionar capacidades a uma extensão, veja Adicionar capacidades de extensão.

Idiomas suportados

Pode criar azd extensões em qualquer linguagem que suporte gRPC, e azd x init inclui templates iniciais para várias línguas. O Go tem o suporte mais completo, incluindo ajudantes de SDK de primeira classe azdext , por isso os artigos desta secção usam o Go para todos os exemplos.

Para extensões desenvolvidas em linguagens diferentes de Go, pode gerar clientes gRPC a partir dos ficheiros .proto no repositório azure/azure-dev. Para conhecer o estado atual do suporte de idiomas, consulte a documentação da estrutura de extensões a montante.

Registos de extensões

Distribui extensões através de fontes de extensão. As fontes de extensões são manifestos baseados em URLs ou ficheiros que descrevem extensões disponíveis e os seus artefactos. azd Também suporta ficheiros bundle portáteis para instalação direta quando não queres alojar um registo.

• O registo oficial está pré-configurado e azd aloja extensões verificadas e de primeira parte. As extensões oficiais são desenvolvidas num fork do repositório azure/azure-dev .
• Fontes baseadas em URL permitem instalar a partir de manifestos de registo públicos ou privados remotos.
• Fontes baseadas em ficheiros permitem instalar a partir de manifestos de registo locais para desenvolvimento, testes ou cenários offline.
• Os registos de desenvolvimento e noturnos são fontes optativas para trabalhos em progresso e desenvolvem automaticamente extensões de primeira parte. As extensões no registo de programadores não têm assinatura, não estão cobertas pelo suporte do Azure, e podem ser alteradas ou removidas sem aviso prévio.

Para saber como publicar uma extensão num registo, consulte Publicar uma extensão.

Conteúdo relacionado

• Construir uma extensão de exemplo
• Defina o manifesto de extensão
• Adicionar capacidades de extensão