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. Use azd x pack para crear artefactos de plataforma para publicación y publicación del registro, o cree una agrupación autocontenida .zip cuando necesite compartir una extensión sin hospedar un registro. 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 de nivel de Project

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.
• Llame a los servicios del framework, como Project, Environment, Account y Prompt.
• 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: Proporcionar metadatos completos sobre comandos y configuración 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 obtener el estado actual de compatibilidad con lenguajes, consulte la documentación del marco de extensión ascendente.

Registros de extensiones

Las extensiones se distribuyen a través de orígenes de extensión. Los orígenes de extensión son manifiestos basados en direcciones URL o basados en archivos que describen las extensiones disponibles y sus artefactos. azd también admite archivos de agrupación portátiles para la instalación directa 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.
• Los orígenes basados en archivos permiten instalar desde manifiestos del Registro local para escenarios de desarrollo, pruebas o sin conexión.
• Los registros de desarrollo y nocturnos son orígenes de participación para las extensiones de trabajo en curso y compilan automáticamente extensiones de primera entidad. 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