Adición de funcionalidades de extensión

Las funcionalidades definen lo que puede hacer una extensión de la CLI de desarrollador (azd) de Azure, desde la adición de comandos personalizados para enlazar al ciclo de vida de la implementación. Este artículo te muestra cómo añadir capacidades a la extensión de ejemplo Contoso Resource Tagger desde la guía de Inicio rápido para crear una extensión de ejemplo. Puede aplicar los mismos patrones a cualquier extensión.

Cada funcionalidad requiere dos cosas: una entrada en la matriz capabilities del manifiesto de la extensión y la implementación correspondiente en el código de la extensión.

Funcionalidades disponibles

azd las extensiones pueden declarar las siguientes funcionalidades:

• custom-commands: Agrega nuevos comandos y grupos de comandos en el espacio de nombres de azd tu extensión. Por ejemplo, la extensión de ejemplo agrega azd tagger show. Use esta funcionalidad para exponer tareas que los usuarios ejecutan directamente desde la línea de comandos.
• lifecycle-events: se suscribe a eventos que se generan a medida que azd se ejecuta, como preprovision, postprovisiono postdeploy. La extensión ejecuta lógica personalizada en esos puntos sin que el usuario lo llame directamente. Por ejemplo, la extensión de ejemplo comprueba si hay etiquetas necesarias en preprovision antes de crear los recursos.
• service-target-provider: registra un nuevo destino de implementación, por lo que azd sabe cómo empaquetar e implementar un servicio en un host que no admite de forma predeterminada. Un destino de servicio se asigna al valor host en azure.yaml. Por ejemplo, puede agregar un proveedor que implemente un servicio en una plataforma de terceros o en un entorno de hospedaje interno.
• framework-service-provider: registra la compatibilidad con un lenguaje o marco, por lo que azd sabe cómo restaurar, compilar y empaquetar ese tipo de proyecto. Esto corresponde al valor de language en azure.yaml. Por ejemplo, puede agregar compatibilidad de compilación para un lenguaje que azd no reconoce de forma predeterminada.
• provisioning-provider: cambia la forma en que azd aprovisiona la infraestructura durante azd provision y azd up. En lugar del flujo predeterminado de Bicep o Terraform, tu extensión determina lo que ocurre. Por ejemplo, puede integrar una herramienta de infraestructura como código diferente o una API de implementación personalizada.
• validation-provider: Aporta comprobaciones al canal de validación azd que se ejecutan en un proyecto o entorno. Por ejemplo, puede comprobar que las convenciones de nomenclatura, las etiquetas necesarias o la configuración de seguridad están en vigor antes de que continúe una implementación.
• mcp-server: Expone la funcionalidad de su extensión como herramientas del Protocolo de contexto de modelo (MCP) que los agentes de IA, como GitHub Copilot, pueden detectar e invocar. Por ejemplo, la extensión de ejemplo puede poner a disposición una herramienta suggest_tags. Para obtener más información, vea Agregar un servidor MCP a una extensión.
• metadata: proporciona metadatos más completos sobre comandos y configuración que azd usa para describir su extensión, como descripciones detalladas de comandos y sugerencias de configuración que aparecen en la salida de ayuda e IntelliSense.

Este artículo se centra en las dos funcionalidades más comunes: comandos personalizados y eventos de ciclo de vida. Para obtener la mcp-server funcionalidad, consulte Adición de un servidor MCP a una extensión. Para obtener más información sobre las funcionalidades del proveedor, consulte la referencia del marco de extensión.

Adición de comandos personalizados

La capacidad custom-commands permite que su extensión registre nuevos comandos bajo un espacio de nombres en azd. La extensión de ejemplo ya usa esta funcionalidad para el azd tagger show comando .

1. Declare la funcionalidad en extension.yaml.

   capabilities:
     - custom-commands
   

2. Compile los comandos mediante el azdext.NewExtensionRootCommand asistente, que registra las marcas estándar azd y el control de variables de entorno para que no tenga que declararlos manualmente:

   import "github.com/azure/azure-dev/cli/azd/pkg/azdext"
   
   func NewRootCommand() *cobra.Command {
       rootCmd, extCtx := azdext.NewExtensionRootCommand(azdext.ExtensionCommandOptions{
           Name:  "tagger",
           Use:   "tagger <command> [options]",
           Short: "Standardize and report Azure resource tags.",
       })
   
       rootCmd.AddCommand(newShowCommand(extCtx))
       // Add other subcommands here.
       return rootCmd
   }
   

   El asistente devuelve un *ExtensionContext que expone los valores resueltos de las marcas estándar, como Environment y OutputFormat. Pase el contexto a sus subcomandos y léalo dentro de sus controladores RunE, en lugar de volver a declarar los indicadores estándar.

Suscripción a eventos de ciclo de vida

La funcionalidad permite que la lifecycle-events extensión ejecute lógica personalizada durante los eventos del ciclo de vida del proyecto y del servicio, como preprovision o postdeploy. Para la extensión de ejemplo, use un preprovision evento para comprobar que las etiquetas necesarias están establecidas antes de azd aprovisionar los recursos.

1. Declare la funcionalidad en extension.yaml.

   capabilities:
     - custom-commands
     - lifecycle-events
   

2. Agregue un listen comando a la extensión. azd invoca este comando para establecer la conexión bidireccional que se usa para los eventos. Use el azdext.NewExtensionHost generador para registrar los controladores de eventos:

   func newListenCommand() *cobra.Command {
       return &cobra.Command{
           Use:    "listen",
           Short:  "Starts the extension and listens for azd events.",
           Hidden: true,
           RunE: func(cmd *cobra.Command, args []string) error {
               ctx := azdext.WithAccessToken(cmd.Context())
   
               azdClient, err := azdext.NewAzdClient()
               if err != nil {
                   return fmt.Errorf("failed to create azd client: %w", err)
               }
               defer azdClient.Close()
   
               host := azdext.NewExtensionHost(azdClient).
                   WithProjectEventHandler(
                       "preprovision",
                       func(ctx context.Context, args *azdext.ProjectEventArgs) error {
                           fmt.Printf("Verifying required tags for project: %s\n", args.Project.Name)
                           // Add your tag validation logic here.
                           return nil
                       },
                   )
   
               // Run blocks until azd closes the connection.
               if err := host.Run(ctx); err != nil {
                   return fmt.Errorf("failed to run extension: %w", err)
               }
   
               return nil
           },
       }
   }
   

3. Registrar el comando listen en el comando raíz:

   rootCmd.AddCommand(newListenCommand())
   

Cuando un usuario ejecuta azd provision o azd up, azd invoca la extensión y llama al preprovision controlador antes de aprovisionar recursos.

Filtrar eventos de servicio

Los controladores de eventos de servicio admiten el filtrado opcional para que solo controle tipos de servicio específicos. Por ejemplo, puede gestionar el evento prepackage solo para los servicios de aplicaciones en contenedor de Python:

host := azdext.NewExtensionHost(azdClient).
    WithServiceEventHandler(
        "prepackage",
        func(ctx context.Context, args *azdext.ServiceEventArgs) error {
            fmt.Printf("Packaging service: %s\n", args.Service.Name)
            return nil
        },
        &azdext.ServiceEventOptions{
            Host:     "containerapp",
            Language: "python",
        },
    )

Recompilación y prueba

Después de agregar una funcionalidad, vuelva a generar la extensión y pruebe el nuevo comportamiento:

1. Si estás usando el modo de supervisión, los cambios se recompilan automáticamente. De lo contrario, compile manualmente:

   azd x build
   

2. Pruebe la funcionalidad. Para los eventos de ciclo de vida, ejecute un comando que desencadene el evento, como azd provision.

Contenido relacionado

• Comunicación con azd mediante el SDK
• Agregar un servidor MCP a una extensión
• Publicación de una extensión
• Referencia del marco de extensiones