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

As extensões da CLI do Desenvolvedor do Azure (azd) são componentes modulares que estendem a funcionalidade da CLI do Desenvolvedor do Azure. Permitem-lhe adicionar novas capacidades, automatizar fluxos de trabalho e integrar-se diretamente com outros serviços a partir da linha de código. Use extensões para adaptar azd às necessidades evolutivas da equipa e aos cenários do Azure.

Observação

A estrutura de extensões azd está agora disponível de forma geral. Extensões ou capacidades individuais podem ter o seu próprio estado de pré-visualização.

Gerenciar fontes de extensão

Pode descobrir, instalar e atualizar extensões à medida que as suas necessidades aumentam. As fontes de extensão tratam da distribuição e gestão.

• As fontes de extensão são manifestos que se baseiam em ficheiros ou URLs e fornecem listas de extensões disponíveis azd.
• Pode adicionar fontes de extensão personalizadas que se ligam a registos privados, locais ou públicos.
• As fontes de extensão são um conceito equivalente aos feeds do NuGet ou do Gerenciador de Pacotes de Nó (NPM) e devem aderir ao esquema de registro de extensão oficial.

azd suporta várias formas de resolver extensões:

• O registro de origem da extensão oficial está pré-configurado e hospedado em azdhttps://aka.ms/azd/extensions/registry.
• Fontes baseadas em URL referem-se a manifestos de registos remotos que a sua equipa aloja para distribuição pública ou privada.
• Fontes baseadas em ficheiros referenciam manifestos locais de registo para uso offline ou desenvolvimento local.
• Os registos de desenvolvimento e noturnos são fontes opcionais para trabalho em curso e para extensões primárias compiladas automaticamente. Use-os para testar cenários em vez de fluxos de trabalho de produção.
• Ficheiros de pacote autónomos disponibilizam pacotes portáteis .zip para instalação direta a partir de um ficheiro local ou de um URL HTTPS quando não pretende alojar um repositório.

azd impõe validação rigorosa para nomes de fonte de extensões personalizadas. Os nomes devem conter de 1 a 64 letras ou dígitos ASCII minúsculos. Pode incluir hífens (-) e sublinhados (_) entre letras ou dígitos. Os nomes devem começar e terminar com uma letra ou um dígito. azd devolve um erro para nomes inválidos; Não os normaliza. Os nomes azd e bundle são reservados e não podem ser usados para fontes personalizadas. O nome da origem tem de ser válido ao utilizá-lo com --source.

A fonte pré-configurada azd é o registo oficial. Não podes removê-lo nem mudar a sua localização.

Para aderir ao registo 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"

Atenção

As extensões alojadas no registo de programadores não têm assinatura, não são cobertas pelo suporte do Azure e podem ser alteradas ou removidas sem aviso prévio.

Comandos de fonte de 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: A localização da fonte de extensão.
• -n, --name: O nome da fonte de extensão. Use um nome de fonte personalizado válido.
• -t, --type: O tipo de fonte de extensão. Os tipos suportados são arquivo e url.

Remover uma fonte de extensão

azd extension source remove <name>

Não podes remover a fonte pré-configurada azd .

Se uma atualização reportar um erro de carregamento da fonte causado por um nome de fonte inválido legado em ~/.azd/config.json, remova a fonte inválida com azd extension source remove, e adicione-a novamente com um nome válido.

Gerenciar extensões

Depois de ativar extensões e configurar as suas fontes de extensões, instale extensões para adicionar novas capacidades a azd. Para um exemplo de trabalho com extensões, veja Quickstart - 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 fonte especificada. O nome de origem deve ser um nome de fonte registado válido.
• --tags Filtra extensões por etiquetas, como IA ou test.

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 versão exata a instalar. Esta opção não aceita intervalos de versões ou restrições e não pode ser usada ao instalar um bundle autónomo (.zip caminho de ficheiro ou URL).
• -s, --source Especifica a fonte de extensão usada para instalações. O nome de origem deve ser um nome de fonte registado válido.

Para instalar um bundle autónomo a partir de uma URL HTTPS, forneça a localização do bundle como nome da extensão:

azd extension install https://example.com/extensions/example.zip

• --all Atualiza todas as extensões instaladas anteriormente quando especificado.
• -v, --version Atualiza uma extensão especificada até à versão exata, se fornecida. Esta opção não aceita intervalos de versões ou restrições.
• -s, --source Especifica a fonte de extensão usada para instalações. O nome de origem deve ser um nome de fonte registado válido.
• --no-dependency-updates Impede atualizações das dependências quando tal for especificado.

Desinstalar uma extensão

azd extension uninstall <extension-name>

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

Declarar extensões obrigatórias num projeto

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

requiredVersions:
  extensions:
    azure.ai.agents: "latest"
    contoso.azd.tagger: "^2.0.0"

Utilize requisitos de projeto quando um modelo depender de hosts de serviço fornecidos por extensões, manipuladores do ciclo de vida, fornecedores de validação ou comandos. Para detalhes completos do esquema e das restrições de versão, veja requiredVersions.

Compreender os pontos de integração de extensões

As extensões podem integrar-se com azd de várias formas:

• Adicione namespaces de comandos com metadados, ajuda e exemplos.
• Fornecer esquemas de configuração e metadados IntelliSense para ficheiros de projeto.
• Registe os processadores de eventos do ciclo de vida para fluxos de trabalho como provisionamento, empacotamento e implantação.
• Adicione fornecedores para provisionamento personalizado, validação, alvos de serviço e suporte a linguagem ou framework.
• Exponha as capacidades do servidor Model Context Protocol (MCP) para agentes e ferramentas de desenvolvimento.

Para orientações de implementação, consulte Conceitos de desenvolvimento de extensões.

Use extensões azd em contentores de desenvolvimento

A azd funcionalidade Dev Container suporta uma extensions opção para instalar automaticamente uma lista separada por vírgulas de azd extensões durante a construção do contentor. As extensões instaladas desta forma estão disponíveis assim que o contentor inicia, reduzindo a configuração manual e permitindo azd que comandos sejam executados com as extensões necessárias já instaladas.

Para instalar extensões automaticamente, adicione a extensions opção à azd entrada de funcionalidades no seu devcontainer.json ficheiro:

{
    "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 extensions valor é uma lista separada por vírgulas de azd nomes de extensões. A instalação ocorre durante a construção do contentor, por isso as extensões ficam prontas a ser usadas assim que o contentor começa. Depois de alterar a lista de extensões, use o comando Reconstruir e Reabrir no Dev Container no Visual Studio Code para reconstruir o container com as extensões atualizadas.

Saiba mais sobre a funcionalidade do contentor de desenvolvimento azd.

Próximos passos

• Início rápido: Usa a extensão de IA
• Conceitos de desenvolvimento de extensões
• Início rápido: Constrói uma extensão de exemplo para o azd
• Leiame do framework de extensão