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.
• Los orígenes de extensión son un concepto equivalente a las fuentes del Administrador de paquetes de NuGet o Node (NPM) y deben cumplir 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.
• Los orígenes basados en direcciones URL hacen referencia a manifiestos remotos del Registro que el equipo hospeda para la distribución pública o privada.
• Los orígenes basados en archivos hacen referencia a manifiestos del Registro local para el uso sin conexión o el desarrollo local.
• 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. Ú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 cuando no desea hospedar un registro.

Los nombres de origen de extensión personalizados 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 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 fuente de extensión

Utilice los siguientes comandos para administrar orígenes de extensión para su instalación azd.

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 del origen de la extensión.
• -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 heredado no válido 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 restricción de versión que se va a aplicar al instalar extensiones.
• -s, --source Especifica el origen de extensión usado para las instalaciones. El nombre de origen debe ser un nombre de origen registrado válido.

Actualización de una extensión

azd extension upgrade <extension-name>

• --all Actualiza todas las extensiones instaladas anteriormente cuando se especifica.
• -v, --version Actualiza una extensión especificada mediante una restricción de versión, si se proporciona.
• -s, --source Especifica el origen de extensión usado para las instalaciones. El nombre de origen debe ser un nombre de origen registrado válido.

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 extensiones necesarias para azure.yaml poder azd resolver e instalar las versiones de extensión que necesita el proyecto. Agregue requisitos de extensión en requiredVersions.extensionsy use latest, una versión exacta o una restricción de versión semántica admitida.

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

Use los requisitos de nivel de proyecto cuando una plantilla dependa de hosts de servicio proporcionados por extensiones, controladores de 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 se pueden integrar de azd varias maneras:

• 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 automáticamente las extensiones, agregue la extensions opción a la entrada de características en azd el devcontainer.json archivo:

{
    "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
• Léame del marco de extensión