Conceptos de desarrollo de extensiones

Las azd de la CLI para desarrolladores de Azure () agregan nuevos comandos, automatizan flujos de trabajo e integran otros servicios con azd. En este artículo se explican los conceptos que debe comprender antes de crear una extensión, como las herramientas para desarrolladores, el kit de desarrollo de software (SDK) y cómo azd se comunica con una extensión en ejecución. Para obtener información sobre las extensiones desde una perspectiva del usuario, consulte la introducción a las extensiones.

La extensión para desarrolladores

La forma más rápida de compilar extensiones es usar la azd extensión para desarrolladores (microsoft.azd.extensions). La extensión de desarrollo agrega un conjunto de comandos en el espacio de nombres azd x que crean la estructura base, compilan, empaquetan y publican tu extensión:

La guía de inicio rápido Crear una extensión de ejemplo te muestra cómo instalar la extensión de desarrollo y generar la estructura de tu primera extensión.

La extensión para desarrolladores admite flujos de trabajo de publicación basados en el Registro y distribución de paquetes portátiles. Utiliza azd x pack para crear artefactos de plataforma para el lanzamiento y la publicación en el registro, o crea un paquete .zip autónomo cuando necesites compartir una extensión sin hospedar un registro. Las agrupaciones se pueden instalar desde un archivo local o hospedarse de forma remota en una dirección URL HTTPS. Para obtener instrucciones paso a paso, consulte Publicación de una extensión.

El entorno de extensiones y gRPC

azd y las extensiones se ejecutan como procesos independientes que se comunican a través de gRPC. Al invocar un comando de extensión, se producen los pasos siguientes:

1. azd inicia un servidor gRPC en un puerto aleatorio y establece la AZD_SERVER variable de entorno con la dirección del servidor.
2. azd establece la AZD_ACCESS_TOKEN variable de entorno, que es un json Web Token (JWT) firmado que concede a la extensión acceso a azd los servicios durante la vigencia del comando.
3. azd invoca el comando de extensión y pasa los argumentos, marcas y variables de entorno actuales.
4. La extensión usa un cliente gRPC para comunicarse con azd a través de los servicios del marco, como mostrar avisos al usuario o leer la configuración del proyecto.
5. azd espera a que el comando se complete e informe de un código de salida distinto de cero como un error.

Este modelo permite que las extensiones interactúen con azd de forma coherente y segura sin acceder directamente al estado interno de azd.

Requisitos de extensión a nivel de proyecto

Los proyectos pueden declarar las extensiones que requieren en azure.yaml. Use la requiredVersions.extensions sección para enumerar los identificadores de extensión y las restricciones de versión para azd poder resolver las versiones que satisfacen el proyecto.

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

Declare las extensiones necesarias cuando un proyecto dependa de hosts, proveedores, controladores de ciclo de vida, validación o comandos proporcionados por la extensión. Para obtener el esquema exacto y la sintaxis de versión admitida, vea requiredVersions.

El SDK de azdext

El azdext paquete es el SDK de Go para el marco de extensión. Proporciona un cliente gRPC y utilidades que se encargan de los detalles de la comunicación, para que puedas centrarte en la lógica de tu extensión. El SDK incluye asistentes para:

• Cree un comando raíz que registre las marcas estándar azd y el control de variables de entorno.
• Adjunta el azd token de acceso a las solicitudes salientes.
• Llama a los servicios del marco azd, como los servicios Project, Environment, Account y Prompt.
• Informar de eventos de uso identificados a través de la API gRPC TelemetryService.ReportUsage para extensiones de origen oficial. Para más información sobre el uso de la API, consulte Comunicación con azd mediante el SDK.
• Registre controladores de eventos de ciclo de vida y proveedores personalizados a través de un host de extensión.

Para aprender a llamar a los servicios azd desde su extensión, consulte Comunicarse con azd mediante el SDK.

Funcionalidades de extensión

Las funcionalidades declaran lo que puede hacer una extensión. Enumere las funcionalidades de una extensión en su extension.yaml manifiesto y azd conceda los permisos correspondientes en tiempo de ejecución. Entre las funcionalidades disponibles se incluyen:

• custom-commands: agregue nuevos grupos de comandos y comandos a azd.
• lifecycle-events: suscríbase a eventos de ciclo de vida del proyecto y del servicio, como preprovision y postdeploy.
• mcp-server: proporcione herramientas de Protocolo de contexto de modelo (MCP) para agentes de IA.
• service-target-provider: proporciona destinos de implementación de servicios personalizados.
• framework-service-provider: Proporcionar compatibilidad para compilar lenguajes y frameworks personalizados.
• provisioning-provider: proporcione una experiencia de aprovisionamiento de infraestructura personalizada.
• validation-provider: Añade comprobaciones de validación a la canalización de validación de azd.
• metadata: Proporciona metadatos de comandos y configuración detallados para la salida de ayuda e IntelliSense.

Para obtener información sobre cómo agregar funcionalidades a una extensión, consulte Incorporación de funcionalidades de extensión.

Idiomas compatibles

Puede crear azd extensiones en cualquier lenguaje que admita gRPC e azd x init incluye plantillas de inicio para varios lenguajes. Go tiene la compatibilidad más completa, incluidos los asistentes del SDK de primera clase azdext , por lo que los artículos de esta sección usan Go para todos los ejemplos.

En el caso de las extensiones creadas en lenguajes distintos de Go, puede generar clientes gRPC a partir de los archivos proto del azure/azure-dev repositorio. Para conocer el estado actual de la compatibilidad con lenguajes, consulta la documentación del marco de extensiones de origen.

Registros de extensiones

Distribuye extensiones a través de fuentes de registro o paquetes de extensiones. Las fuentes del registro son manifiestos basados en URL o en archivos que describen las extensiones disponibles y sus artefactos. Los paquetes de extensiones son paquetes portátiles .zip que se pueden instalar directamente desde un archivo local o un host de forma remota en una dirección URL HTTPS cuando no desea hospedar un registro.

• El registro oficial está preconfigurado en azd y aloja extensiones propias verificadas. Las extensiones oficiales se desarrollan en una bifurcación del repositorio azure/azure-dev .
• Los orígenes basados en direcciones URL permiten instalar desde manifiestos de registro públicos o privados remotos.
• Las fuentes basadas en archivos permiten instalar desde manifiestos de registro locales para tareas de desarrollo, pruebas o en entornos sin conexión.
• Los registros de desarrollo y nightly son fuentes opcionales, de activación voluntaria, para extensiones en desarrollo y extensiones oficiales compiladas automáticamente. Las extensiones del registro de desarrollo no están firmadas, no cubiertas por Soporte técnico de Azure y pueden cambiarse o quitarse sin previo aviso.

Para obtener información sobre cómo publicar una extensión en un registro, consulte Publicación de una extensión.

Contenido relacionado

• Compilación de una extensión de ejemplo
• Definición del manifiesto de extensión
• Adición de funcionalidades de extensión