Visão geral das extensões da CLI do Desenvolvedor do Azure

As extensões da CLI do Desenvolvedor do Azure (azd) são componentes modulares que estendem a funcionalidade da CLI do Desenvolvedor do Azure. Eles permitem que você adicione novos recursos, automatize fluxos de trabalho e integre-se a outros serviços diretamente da CLI. Use extensões para adaptar azd às necessidades em constante evolução da equipe e aos cenários do Azure.

Gerenciar fontes de extensão

Você pode descobrir, instalar e atualizar extensões à medida que seus requisitos aumentam. As fontes de extensão lidam com a distribuição e o gerenciamento.

• As fontes de extensão são manifestações baseadas em arquivos ou URLs que fornecem listas de extensões disponíveis azd.
• Você pode adicionar fontes de extensão personalizadas que se conectam a registros privados, locais ou públicos.
• As fontes de extensão são um conceito equivalente aos feeds do NuGet ou NPM (Gerenciador de Pacotes do Node) e devem aderir ao esquema oficial do registro de extensão.

azd dá suporte a várias maneiras de resolver extensões:

• O registro de origem da extensão oficial está pré-configurado azd e está hospedado em https://aka.ms/azd/extensions/registry.
• Fontes baseadas em URL fazem referência a manifestos de registro remoto que sua equipe hospeda para distribuição pública ou privada.
• Fontes baseadas em arquivo fazem referência a manifestos do registro local para uso offline ou desenvolvimento local.
• 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. Use-os para testar cenários em vez de fluxos de trabalho de produção.
• Os arquivos de pacotes autocontidos fornecem pacotes portáteis .zip para instalação direta quando você não deseja hospedar um registro.

Os nomes de origem de extensão personalizados devem conter de 1 a 64 letras ascii minúsculas ou dígitos. Você pode incluir hifens (-) e sublinhados (_) entre letras ou dígitos. Os nomes devem iniciar e terminar com uma letra ou dígito. azd retorna um erro para nomes inválidos; não os normaliza. Os nomes azd são bundle reservados e não podem ser usados para fontes personalizadas.

A origem pré-configurada azd é o registro oficial. Você não pode removê-lo ou alterar sua localização.

Para aceitar o registro de desenvolvimento, execute o seguinte comando:

# Add a new extension source name 'dev' to your `azd` configuration.
azd extension source add -n dev -t url -l "https://aka.ms/azd/extensions/registry/dev"

Comandos de origem da extensão

Use os comandos a seguir para gerenciar fontes de extensão para sua azd instalação.

Listar fontes de extensão instaladas

azd extension source list

Adicionar uma nova fonte de extensão

azd extension source add -n <name> -t url -l <registry-url>

• -l, --location: o local da origem da extensão.
• -n, --name: Nome da fonte da extensão. Use um nome de origem personalizado válido.
• -t, --type: o tipo de fonte da extensão. Os tipos com suporte são arquivo e URL.

Remover uma fonte de extensão

azd extension source remove <name>

Não é possível remover a origem pré-configurada azd .

Se uma atualização relatar um erro de carga de origem causado por um nome ~/.azd/config.jsonde origem inválido herdado, remova a origem ofensiva e azd extension source removeadicione-a novamente com um nome válido.

Gerenciar extensões

Depois de habilitar extensões e configurar suas fontes de extensão, instale extensões para adicionar novos recursos a azd. Para obter um exemplo de como trabalhar com extensões, consulte Início Rápido – use a extensão de IA.

Extensões de lista

azd extension list [flags]

• --installed Exibe uma lista de extensões instaladas.
• --source Lista apenas extensões da origem especificada. O nome de origem deve ser um nome de origem registrado válido.
• --tags Filtra extensões por etiquetas, como IA ou teste.

Instalar uma extensão

azd extension install <extension-names> [flags]

Substitua <extension-name> pelo nome da extensão que você deseja instalar.

• -v, --version Especifica a restrição de versão a ser aplicada ao instalar extensões.
• -s, --source Especifica a fonte de extensão usada para instalações. O nome de origem deve ser um nome de origem registrado válido.

Atualizar uma extensão

azd extension upgrade <extension-name>

• --all Atualiza todas as extensões instaladas anteriormente quando especificadas.
• -v, --version Atualiza uma extensão especificada usando uma restrição de versão, se fornecida.
• -s, --source Especifica a fonte de extensão usada para instalações. O nome de origem deve ser um nome de origem registrado válido.

Desinstalar uma extensão

azd extension uninstall <extension-name>

• --all Remove todas as extensões instaladas quando especificadas.

Declarar extensões necessárias em um projeto

Os projetos podem declarar as extensões necessárias azure.yaml para azd que possam resolver e instalar as versões de extensão que o projeto precisa. Adicione requisitos de extensão em requiredVersions.extensions, e use latest, uma versão exata ou uma restrição de versão semântica com suporte.

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

Use os requisitos no nível do projeto quando um modelo depende de hosts de serviço fornecidos por extensão, manipuladores de ciclo de vida, provedores de validação ou comandos. Para obter os detalhes completos do esquema e da restrição de versão, consulte requiredVersions.

Entender os pontos de integração de extensão

As extensões podem ser integradas de azd várias maneiras:

• Adicione namespaces de comando com metadados, ajuda e exemplos.
• Forneça esquemas de configuração e metadados do IntelliSense para arquivos de projeto.
• Registre manipuladores de eventos de ciclo de vida para fluxos de trabalho, como provisionamento, pacote e implantação.
• Adicione provedores para provisionamento personalizado, validação, destinos de serviço e suporte a linguagem ou estrutura.
• Expor os recursos do servidor MCP (Model Context Protocol) para agentes e ferramentas de desenvolvedor.

Para obter diretrizes de implementação, consulte os conceitos de desenvolvimento de extensão.

Usar extensões azd em contêineres de desenvolvimento

O recurso azd Dev Container oferece suporte a uma opção extensions para instalar automaticamente uma lista de azd extensões separadas por vírgulas durante a construção do contêiner. As extensões instaladas dessa forma estão disponíveis assim que o contêiner é iniciado, reduzindo a instalação manual e permitindo azd que os comandos sejam executados com as extensões necessárias já instaladas.

Para instalar automaticamente as extensões, adicione a opção extensions à entrada do recurso azd em seu arquivo devcontainer.json.

{
    "name": "Azure Developer CLI",
    "image": "mcr.microsoft.com/devcontainers/python:3.10-bullseye",
    "features": {
        "ghcr.io/azure/azure-dev/azd:latest": {
            "extensions": "my-ext-1,my-ext-2"
        }
    }
}

O valor extensions é uma lista separada por vírgulas de nomes de extensões azd. A instalação ocorre durante o build do contêiner, de modo que as extensões estejam prontas para uso assim que o contêiner for iniciado. Depois de alterar a lista de extensões, use o comando Rebuild and Reopen in Dev Container no Visual Studio Code para recompilar o contêiner com as extensões atualizadas.

Saiba mais sobre o recurso de contêiner de desenvolvimento azd.

Próximas etapas

• Início rápido: Use a extensão de IA
• Conceitos de desenvolvimento de extensão
• Início Rápido: Criar uma extensão do azd de exemplo
• Leiame da estrutura de extensão