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.

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 optativas para trabalhos em progresso e desenvolvem automaticamente extensões de primeira parte. Use-os para testar cenários em vez de fluxos de trabalho de produção.
• Ficheiros bundle autónomos fornecem pacotes portáteis .zip para instalação direta quando não se quer hospedar um registo.

Os nomes de origem das extensões personalizadas 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.

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"

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 problemática com azd extension source remove, e depois 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 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 fonte registado válido.

Atualizar uma extensão

azd extension upgrade <extension-name>

• --all Atualiza todas as extensões instaladas anteriormente quando especificado.
• -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 fonte registado válido.

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. Adicionar requisitos de extensão em requiredVersions.extensions, e usar latest, uma versão exata, ou uma restrição semântica de versão suportada.

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

Use requisitos ao nível do projeto quando um modelo depende de anfitriões de serviço fornecidos por extensões, handlers 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 de azd várias formas:

• Adicione namespaces de comandos com metadados, ajuda e exemplos.
• Fornecer esquemas de configuração e metadados IntelliSense para ficheiros de projeto.
• Registar os gestores de eventos do ciclo de vida para fluxos de trabalho como provisionamento, empacotamento e implementação.
• Adicione fornecedores para provisionamento personalizado, validação, alvos de serviço e suporte a linguagem ou framework.
• Expose Model Context Protocol (MCP) capacidades de servidores para agentes e ferramentas de programação.

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