Definir o manifesto da extensão

Cada extensão da CLI do Desenvolvedor Azure (azd) inclui um extension.yaml manifesto que descreve seus metadados e recursos. azd usa esses metadados no registro de extensão para ajudar os usuários a descobrir, instalar e entender sua extensão. Este artigo explica as propriedades do manifesto usando a extensão de exemplo Contoso Resource Tagger do guia de início rápido Criar uma extensão de exemplo. Você pode aplicar os mesmos conceitos a qualquer extensão.

Note

azd as extensões estão atualmente na versão beta.

Propriedades do manifesto

O extension.yaml manifesto dá suporte às propriedades a seguir.

Propriedades obrigatórias

Cada manifesto deve incluir as seguintes propriedades:

Property Description
id Identificador exclusivo para a extensão, como contoso.azd.tagger.
version Versão semântica em MAJOR.MINOR.PATCH formato.
displayName Nome legível para humanos da extensão.
description Descrição detalhada da extensão.

Cada manifesto também deve incluir um capabilities ou dependencies. Uma extensão que fornece comandos ou provedores declara capabilities. Um pacote de extensões declara dependencies em vez disso.

Propriedades opcionais

O manifesto também dá suporte às seguintes propriedades opcionais:

Property Description
namespace Namespace de comandos que agrupa os comandos da extensão, como tagger.
entryPoint Executável ou script que serve como ponto de entrada.
language Linguagem de programação em que a extensão é escrita, como go.
capabilities Conjunto de capacidades de extensão.
usage Instruções sobre como usar a extensão.
examples Matriz de exemplos de uso com nome, descrição e uso.
tags Palavras-chave para categorização e filtragem.
dependencies Outras extensões das quais essa extensão depende.
providers Lista de provedores que a extensão registra.
platforms Metadados específicos da plataforma.
mcp Configuração do servidor do Protocolo de Contexto do Modelo.
requiredAzdVersion Restrição de versão semântica para a versão azd necessária para usar a extensão, como >= 1.24.0.

Exemplo de manifesto

O exemplo a seguir mostra um manifesto extension.yaml para a extensão de exemplo do Marcador de Recursos Contoso:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/cli/azd/extensions/extension.schema.json

id: contoso.azd.tagger
namespace: tagger
displayName: Contoso Resource Tagger
description: Standardize and report Azure resource tags for an azd project.
usage: azd tagger <command> [options]
version: 0.1.0
language: go
capabilities:
  - custom-commands

examples:
  - name: show
    description: Displays a greeting from the extension.
    usage: azd tagger show

tags:
  - tags
  - governance
  - example

O $schema comentário na parte superior do arquivo habilita a validação e o IntelliSense em editores que dão suporte ao servidor de linguagem YAML.

Declarar funcionalidades

A capabilities matriz declara o que sua extensão pode fazer. azd concede as permissões correspondentes em tempo de execução, e alguns serviços do framework falham com um erro de permissão se a capacidade correspondente não for declarada. A extensão de exemplo começa com apenas custom-commands:

capabilities:
  - custom-commands

À medida que você adiciona funcionalidade nos outros artigos, você adiciona mais recursos. Por exemplo, adicionar recursos de extensão adiciona lifecycle-eventse adicionar um servidor MCP a uma extensão adiciona mcp-server. Os recursos disponíveis são:

  • custom-commands: adicione novos comandos ao azd namespace, como azd tagger show.
  • lifecycle-events: Execute lógica personalizada quando azd gerar eventos como preprovision ou postdeploy.
  • mcp-server: Exponha as ferramentas do Protocolo de Contexto de Modelo que os agentes de IA podem invocar.
  • service-target-provider: adicione um destino de implantação personalizado para um host que azd não dá suporte por padrão.
  • framework-service-provider: adicione suporte de build e pacote para um language que azd não reconhece por padrão.
  • provisioning-provider: substitua como azd provisiona a infraestrutura por uma implementação personalizada.
  • validation-provider: Adicione verificações que são executadas no pipeline de validação do azd.
  • metadata: forneça metadados mais ricos de comando e configuração para a saída de ajuda e o IntelliSense.

Para obter uma explicação mais completa de cada funcionalidade com exemplos, consulte Adicionar recursos de extensão.

Adicionar exemplos de uso

A examples matriz documenta maneiras comuns de usar sua extensão. azd apresenta estes exemplos quando os usuários exibem detalhes sobre sua extensão:

examples:
  - name: show
    description: Displays a greeting from the extension.
    usage: azd tagger show

Registrar provedores

Quando sua extensão fornece destinos de serviço personalizados ou serviços de estrutura, declare-os na providers seção para azd saber o que sua extensão oferece:

providers:
  - name: tagger
    type: service-target
    description: Deploys tagged resources to Azure.

Adicionar configuração específica da plataforma

Use a platforms propriedade para fornecer metadados específicos da plataforma, como o nome executável para cada sistema operacional.

platforms:
  windows:
    executable: tagger.exe
  linux:
    executable: tagger
  darwin:
    executable: tagger

Declarar dependências

As extensões podem depender de outras extensões usando a dependencies matriz. As dependências dão suporte a restrições semânticas de controle de versão:

dependencies:
  - id: microsoft.azd.core
    version: "^1.0.0"

azd instala ou atualiza para a versão mais alta publicada que atende a cada restrição. Os formatos de restrição comuns incluem:

  • ^1.0.0: compatível com a versão 1.x.x.
  • ~1.2.0: compatível com a versão 1.2.x.
  • >=1.0.0 <2.0.0: um intervalo de versão.

Agrupar extensões com pacotes de extensão

Um pacote de extensões é um manifesto que agrupa extensões relacionadas para que os usuários possam instalá-las com um único comando. Um pacote declara dependencies , mas não fornece um executável, namespace de comando ou funcionalidades próprias. Use um pacote para publicar um conjunto de extensões, como uma família de produtos ou um pacote de cenários:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/cli/azd/extensions/extension.schema.json

id: contoso.tools
displayName: Contoso Tools Extension Pack
description: Installs the Contoso azd extensions.
version: 0.1.0

dependencies:
  - id: contoso.azd.tagger
    version: "~0.1.0"

A instalação de um pacote instala recursivamente suas dependências da mesma fonte de extensão que o pacote.

Conteúdo relacionado

  • Last updated on