Defina o manifesto de extensão

Cada extensão do Azure Developer CLI (azd) inclui um extension.yaml manifesto que descreve os seus metadados e capacidades. azd Utiliza estes metadados no registo de extensões para ajudar os utilizadores a descobrir, instalar e compreender a sua extensão. Este artigo explica as propriedades do manifesto usando a extensão de exemplo Contoso Resource Tagger do quickstart da extensão Build a sample. Podes aplicar os mesmos conceitos a qualquer extensão.

Note

azd As extensões estão atualmente em versão beta.

Propriedades manifestas

O extension.yaml manifesto suporta as seguintes propriedades.

Propriedades necessárias

Todo manifesto deve incluir as seguintes propriedades:

Property	Description
`id`	Identificador único 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 deve também incluir ou capabilities ou dependencies. Uma extensão que fornece comandos ou fornecedores declara capabilities. Um pacote de extensão declara dependencies em vez disso.

Propriedades opcionais

O manifesto também suporta as seguintes propriedades opcionais:

Property	Description
`namespace`	Espaço de nomes 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`	Gama de funcionalidades de extensão.
`usage`	Instruções sobre como usar a extensão.
`examples`	Variedade de exemplos de utilização com nome, descrição e uso.
`tags`	Palavras-chave para categorização e filtragem.
`dependencies`	Outras extensões das quais esta extensão depende.
`providers`	Lista de provedores que a extensão regista.
`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 na versão `azd` necessária para utilizar a extensão, como `>= 1.24.0`.

Exemplo de manifesto

O exemplo seguinte mostra um extension.yaml manifesto para a extensão de exemplo Contoso Resource Tagger:

# 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 no topo do ficheiro permite validação e IntelliSense em editores que suportam o servidor de linguagem YAML.

Declarar capacidades

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

capabilities:
  - custom-commands

À medida que adicionas funcionalidades nos outros artigos, acrescentas mais capacidades. Por exemplo, adicionar capacidades de extensão adiciona lifecycle-events, e adicionar um servidor MCP a uma extensão adiciona mcp-server. As capacidades disponíveis são:

custom-commands: Adicione novos comandos em azd, no seu espaço de nomes, como azd tagger show.
lifecycle-events: Execute lógica personalizada quando azd desencadeia eventos como preprovision ou postdeploy.
mcp-server: Disponibilizar ferramentas do Model Context Protocol que os agentes de IA possam invocar.
service-target-provider: Adicionar um destino de implementação personalizado para um host que azd não suporta por defeito.
framework-service-provider: Adicionar suporte a compilações e pacotes para um language que azd não reconhece por defeito.
provisioning-provider: Substituir a forma como azd aprovisiona infraestrutura por uma implementação personalizada.
validation-provider: Adicionar verificações que são executadas na pipeline de validação azd.
metadata: Fornecer metadados de comandos e configuração mais ricos para saída de ajuda e IntelliSense.

Para uma explicação mais completa de cada capacidade com exemplos, veja Adicionar capacidades de extensão.

Adicionar exemplos de utilização

O examples array documenta formas comuns de usar a sua extensão. azd apresenta estes exemplos quando os utilizadores veem os detalhes da sua extensão:

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

Registar prestadores

Quando a sua extensão fornece alvos de serviço personalizados ou serviços de framework, declare-os na providers secção para azd saber o que a 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 do executável para cada sistema operativo.

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

Declarar dependências

As extensões podem depender de outras extensões usando o dependencies array. Dependências suportam restrições semânticas de versionamento:

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

azd instala ou atualiza para a versão publicada mais alta que satisfaz cada restrição. Formatos comuns de restrições 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: Uma gama de versões.

Agrupar extensões com pacotes de extensões

Um pacote de extensões é um manifesto que agrupa extensões relacionadas para que os utilizadores possam instalá-las com um único comando. Um pack declara dependencies , mas não fornece um executável, namespace de comandos ou capacidades próprias. Use um pacote para publicar um conjunto selecionado 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"

Instalar um pack instala recursivamente as suas dependências a partir da mesma fonte de extensão que o pack.

Comentários

Esta página foi útil?

Last updated on 2026-07-29