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 guia de Criar uma extensão de exemplo: início rápido mostra como instalar a extensão para desenvolvedor e criar a estrutura inicial da sua primeira extensão.

A extensão de desenvolvedor dá suporte a fluxos de trabalho de publicação baseados em registro e distribuição de pacote portátil. Use azd x pack para criar artefatos de plataforma para publicação de versão e registro ou crie um pacote autocontido .zip quando precisar compartilhar uma extensão sem hospedar um registro. 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 de nível Project

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 você, 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 azd os serviços do framework, como os serviços Project, Environment, Account e Prompt.
• 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: Assine 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 build para linguagens e frameworks personalizados.
• provisioning-provider: forneça uma experiência de provisionamento de infraestrutura personalizada.
• validation-provider: Contribua com verificações ao 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 extensão. As fontes de extensão são manifestos baseados em URL ou baseados em arquivo que descrevem extensões disponíveis e seus artefatos. azd também dá suporte a arquivos de pacote portáteis para instalação direta quando você não deseja 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.
• As fontes baseadas em arquivo permitem que você instale por meio de manifestos do Registro local para cenários de desenvolvimento, teste ou offline.
• O desenvolvimento e os registros noturnos são fontes de aceitação para o trabalho em andamento e as extensões de primeira parte criadas 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