Definición del manifiesto de extensión

Cada extensión de la CLI para desarrolladores (azd) de Azure incluye un extension.yaml manifiesto que describe sus metadatos y funcionalidades. azd usa estos metadatos en el Registro de extensiones para ayudar a los usuarios a detectar, instalar y comprender la extensión. En este artículo se explican las propiedades del manifiesto usando la extensión de ejemplo Contoso Resource Tagger del inicio rápido «Compilación de una extensión de ejemplo». Se pueden aplicar los mismos conceptos a cualquier extensión.

Note

azd las extensiones están actualmente en versión beta.

Propiedades del manifiesto

El extension.yaml manifiesto admite las siguientes propiedades.

Propiedades necesarias

Cada manifiesto debe incluir las siguientes propiedades:

Propiedad Description
id Identificador único de la extensión, como contoso.azd.tagger.
version Versión semántica en MAJOR.MINOR.PATCH formato.
displayName Nombre de la extensión legible para las personas.
description Descripción detallada de la extensión.

Cada manifiesto también debe incluir capabilities o dependencies. Una extensión que proporciona comandos o proveedores declara capabilities. Un paquete de extensiones declara dependencies en su lugar.

Propiedades opcionales

El manifiesto también admite las siguientes propiedades opcionales:

Propiedad Description
namespace Espacio de nombres de comandos que agrupa los comandos de la extensión, como tagger.
entryPoint Ejecutable o script que actúa como punto de entrada.
language Lenguaje de programación en el que se escribe la extensión, como go.
capabilities Matriz de funcionalidades de extensión.
usage Instrucciones sobre cómo usar la extensión.
examples Matriz de ejemplos de uso con un nombre, una descripción y un uso.
tags Palabras clave para categorización y filtrado.
dependencies Otras extensiones de las que depende esta extensión.
providers Lista de proveedores que registra la extensión.
platforms Metadatos específicos de la plataforma.
mcp Configuración del servidor de Model Context Protocol.
requiredAzdVersion Restricción de versión semántica sobre la versión azd necesaria para usar la extensión, como >= 1.24.0.

Manifiesto de ejemplo

En el ejemplo siguiente se muestra un manifiesto extension.yaml para la extensión de ejemplo 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

El $schema comentario de la parte superior del archivo habilita la validación e IntelliSense en los editores que admiten el servidor de lenguaje YAML.

Declarar funcionalidades

La capabilities matriz declara lo que puede hacer la extensión. azd concede los permisos correspondientes en tiempo de ejecución y algunos servicios de marco producen un error de permiso si no se declara la funcionalidad coincidente. La extensión de ejemplo comienza solo con custom-commands:

capabilities:
  - custom-commands

A medida que agrega funcionalidad en los otros artículos, agregará más funcionalidades. Por ejemplo, Agregar funcionalidades de extensión agrega lifecycle-eventsy Agregar un servidor MCP a una extensión agrega mcp-server. Las funcionalidades disponibles son:

  • custom-commands: Agregue nuevos comandos a azd dentro de su espacio de nombres, como azd tagger show.
  • lifecycle-events: ejecute lógica personalizada cuando azd genere eventos como preprovision o postdeploy.
  • mcp-server: Exponer herramientas de Model Context Protocol que los agentes de IA pueden invocar.
  • service-target-provider: agregue un destino de implementación personalizado para un host que azd no admita de forma predeterminada.
  • framework-service-provider: se ha agregado compatibilidad de compilación y paquete para un language que azd no reconoce de forma predeterminada.
  • provisioning-provider: reemplace cómo azd aprovisiona la infraestructura con una implementación personalizada.
  • validation-provider: Agrega comprobaciones que se ejecutan en la canalización de validación de azd.
  • metadata: Proporcionar metadatos más completos de comandos y configuración para la salida de ayuda e IntelliSense.

Para obtener una explicación más completa de cada funcionalidad con ejemplos, consulte Adición de funcionalidades de extensión.

Adición de ejemplos de uso

La examples matriz documenta formas comunes de usar la extensión. azd muestra estos ejemplos cuando los usuarios ven detalles sobre la extensión:

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

Registro de proveedores

Cuando la extensión proporciona destinos de servicio personalizados o servicios de marco, declarelos en la providers sección para azd saber lo que ofrece la extensión:

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

Adición de una configuración específica de la plataforma

Use la platforms propiedad para proporcionar metadatos específicos de la plataforma, como el nombre ejecutable de cada sistema operativo.

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

Declarar dependencias

Las extensiones pueden depender de otras extensiones mediante la dependencies matriz . Las dependencias admiten restricciones de control de versiones semánticas:

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

azd instala o actualiza a la versión publicada más alta que satisface cada restricción. Entre los formatos de restricción comunes se incluyen:

  • ^1.0.0: compatible con la versión 1.x.x.
  • ~1.2.0: compatible con la versión 1.2.x.
  • >=1.0.0 <2.0.0: un intervalo de versiones.

Agrupar extensiones con paquetes de extensiones

Un paquete de extensiones es un manifiesto que agrupa extensiones relacionadas para que los usuarios puedan instalarlos con un solo comando. Un paquete declara dependencies pero no proporciona un archivo ejecutable, un espacio de nombres de comandos o funcionalidades propios. Use un paquete para publicar un conjunto mantenido de extensiones, como una familia de productos o un conjunto de escenarios:

# 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"

Al instalar un paquete de forma recursiva, se instalan sus dependencias desde el mismo origen de extensión que el paquete.

Contenido relacionado

  • Last updated on