Introducción a las extensiones de la CLI para desarrolladores de Azure

Las extensiones de la CLI para desarrolladores de Azure (azd) son componentes modulares que amplían la funcionalidad de la CLI para desarrolladores de Azure. Permiten agregar nuevas funcionalidades, automatizar flujos de trabajo e integrarlos con otros servicios directamente desde la CLI. Use extensiones para adaptar azd a las necesidades cambiantes del equipo y a los escenarios de Azure.

Gestionar fuentes de extensiones

Puede detectar, instalar y actualizar extensiones a medida que crecen los requisitos. Las fuentes de extensiones se encargan de la distribución y la administración.

• Fuentes de extensión son manifiestos basados en archivos o direcciones URL que proporcionan listas disponibles de extensiones azd.
• Puede agregar orígenes de extensión personalizados que se conecten a registros privados, locales o públicos.
• Las fuentes de extensiones son un concepto equivalente a los canales de NuGet o del Gestor de paquetes de Node (NPM) y deben cumplir con el esquema oficial del registro de extensiones.

azd admite varias maneras de resolver extensiones:

• El registro de origen de la extensión oficial está preconfigurado en azd y se hospeda en https://aka.ms/azd/extensions/registry.
• Fuentes basadas en URL hace referencia a manifiestos de registro remotos que aloja tu equipo para su distribución pública o privada.
• Las fuentes basadas en archivos hacen referencia a manifiestos del registro local para su uso sin conexión o el desarrollo local.
• Los registros de desarrollo y de compilaciones nocturnas son fuentes opcionales para extensiones en desarrollo y extensiones propias compiladas automáticamente. Úselos para escenarios de prueba en lugar de flujos de trabajo de producción.
• Los archivos de agrupación independientes proporcionan paquetes portátiles .zip para la instalación directa desde un archivo local o una dirección URL HTTPS cuando no desea hospedar un registro.

azd aplica una validación estricta para los nombres de origen de extensión personalizados. Los nombres deben contener de 1 a 64 letras ASCII minúsculas o dígitos. Puede incluir guiones (-) y caracteres de subrayado (_) entre letras o dígitos. Los nombres deben comenzar y terminar con una letra o un dígito. azd devuelve un error para nombres no válidos; no las normaliza. Los nombres azd y bundle están reservados y no se pueden usar para orígenes personalizados. El nombre de origen debe ser válido cuando se usa con --source.

El origen preconfigurado azd es el registro oficial. No se puede quitar ni cambiar su ubicación.

Para participar en el Registro de desarrollo, ejecute el siguiente comando:

# Add a new extension source name 'dev' to your `azd` configuration.
azd extension source add -n dev -t url -l "https://aka.ms/azd/extensions/registry/dev"

Comandos de fuentes de extensiones

Utiliza los siguientes comandos para administrar las fuentes de extensiones de tu azd instalación.

Enumerar orígenes de extensión instalados

azd extension source list

Adición de un nuevo origen de extensión

azd extension source add -n <name> -t url -l <registry-url>

• -l, --location: La ubicación de la fuente de extensiones.
• -n, --name: nombre del origen de la extensión. Use un nombre de origen personalizado válido.
• -t, --type: tipo de origen de extensión. Los tipos admitidos son archivos y direcciones URL.

Eliminación de un origen de extensión

azd extension source remove <name>

No se puede quitar el origen preconfigurado azd .

Si una actualización notifica un error de carga de origen causado por un nombre de origen no válido heredado en ~/.azd/config.json, quite el origen infractor con azd extension source removey, a continuación, agréguelo de nuevo con un nombre válido.

Administrar extensiones

Después de habilitar las extensiones y configurar los orígenes de extensión, instale extensiones para agregar nuevas funcionalidades a azd. Para obtener un ejemplo de cómo trabajar con extensiones, consulte Inicio rápido: uso de la extensión ai.

Enumerar extensiones

azd extension list [flags]

• --installed Muestra una lista de extensiones instaladas.
• --source Solo enumera las extensiones del origen especificado. El nombre de origen debe ser un nombre de origen registrado válido.
• --tags Filtra las extensiones por etiquetas, como IA o prueba.

Instalar una extensión

azd extension install <extension-names> [flags]

Reemplace <extension-name> por el nombre de la extensión que desea instalar.

• -v, --version Especifica la versión exacta que se va a instalar. Esta opción no acepta intervalos de versiones ni restricciones y no se puede usar durante la instalación de un paquete autocontenido (ruta de acceso del archivo .zip o dirección URL).
• -s, --source Especifica la fuente de extensiones utilizada para las instalaciones. El nombre de origen debe ser un nombre de origen registrado válido.

Para instalar un paquete independiente desde una dirección URL HTTPS, proporcione la ubicación del lote como el nombre de la extensión:

azd extension install https://example.com/extensions/example.zip

• --all Actualiza todas las extensiones instaladas anteriormente cuando se especifica.
• -v, --version Actualiza una extensión especificada a la versión exacta, si se proporciona. Esta opción no acepta intervalos de versiones ni restricciones.
• -s, --source Especifica la fuente de extensiones utilizada para las instalaciones. El nombre de origen debe ser un nombre de origen registrado válido.
• --no-dependency-updates Impide las actualizaciones de las dependencias cuando se especifica.

Desinstalación de una extensión

azd extension uninstall <extension-name>

• --all Quita todas las extensiones instaladas cuando se especifica.

Declaración de extensiones necesarias en un proyecto

Los proyectos pueden declarar las extensiones requeridas en azure.yaml para que azd pueda resolver e instalar las versiones de las extensiones que necesita el proyecto. Añade requisitos de extensión en requiredVersions.extensions y utiliza latest, una versión exacta o una restricción de versión semántica compatible.

requiredVersions:
  extensions:
    azure.ai.agents: "latest"
    contoso.azd.tagger: "^2.0.0"

Utilice los requisitos a nivel de proyecto cuando una plantilla dependa de hosts de servicio proporcionados por extensiones, controladores del ciclo de vida, proveedores de validación o comandos. Para obtener los detalles completos de la restricción de esquema y versión, consulte requiredVersions.

Descripción de los puntos de integración de extensiones

Las extensiones pueden integrarse con azd de varias formas:

• Agregue espacios de nombres de comandos con metadatos, ayuda y ejemplos.
• Proporcione esquemas de configuración e metadatos de IntelliSense para archivos de proyecto.
• Registre controladores de eventos de ciclo de vida para flujos de trabajo como el aprovisionamiento, el paquete y la implementación.
• Agregue proveedores para el aprovisionamiento personalizado, la validación, los destinos de servicio y la compatibilidad con lenguajes o marcos.
• Exponga las funcionalidades del servidor del Protocolo de contexto de modelo (MCP) para agentes y herramientas de desarrollo.

Para obtener instrucciones de implementación, consulte Conceptos de desarrollo de extensiones.

Uso de extensiones azd en contenedores de desarrollo

La azd característica de contenedor de desarrollo admite una extensions opción para instalar automáticamente una lista separada por comas de azd extensiones durante la compilación del contenedor. Las extensiones instaladas de esta manera están disponibles en cuanto se inicia el contenedor, lo que reduce la configuración manual y habilita la ejecución azd de comandos con las extensiones necesarias ya instaladas.

Para instalar extensiones automáticamente, añada la extensions opción a la entrada de la azd característica en su archivo devcontainer.json:

{
    "name": "Azure Developer CLI",
    "image": "mcr.microsoft.com/devcontainers/python:3.10-bullseye",
    "features": {
        "ghcr.io/azure/azure-dev/azd:latest": {
            "extensions": "my-ext-1,my-ext-2"
        }
    }
}

El extensions valor es una lista separada por comas de nombres de azd extensión. La instalación se produce durante la compilación del contenedor, por lo que las extensiones están listas para usarse tan pronto como se inicie el contenedor. Después de cambiar la lista de extensiones, use el comando Reconstruir y volver a abrir en Contenedor de Desarrollo en Visual Studio Code para reconstruir el contenedor con las extensiones actualizadas.

Obtenga más información sobre la funcionalidad azd Dev Container.

Pasos siguientes

• Inicio rápido: Uso de la extensión ai
• Conceptos de desarrollo de extensiones
• Inicio rápido: Compilación de una extensión azd de ejemplo
• Archivo Léeme del marco de extensiones