Ajouter des fonctionnalités d’extension

Les fonctionnalités définissent ce qu’une extension CLI développeur (azd) Azure peut faire, de l’ajout de commandes personnalisées à la connexion au cycle de vie du déploiement. Cet article explique comment ajouter des fonctionnalités à l’exemple d’extension Contoso Resource Tagger à partir du guide de démarrage rapide Générer un exemple d’extension. Vous pouvez appliquer les mêmes modèles à n’importe quelle extension.

Chaque fonctionnalité nécessite deux éléments : une entrée dans le capabilities tableau de votre manifeste d’extension et l’implémentation correspondante dans votre code d’extension.

Note

azd les extensions sont actuellement en version bêta.

Fonctionnalités disponibles

azd les extensions peuvent déclarer les fonctionnalités suivantes :

custom-commands: ajoute de nouvelles commandes et groupes de commandes dans azd l’espace de noms de votre extension. Par exemple, l’exemple d’extension ajoute azd tagger show. Utilisez cette fonctionnalité pour exposer les tâches que les utilisateurs exécutent directement à partir de la ligne de commande.
lifecycle-events : s’abonne aux événements que azd déclenche pendant son exécution, tels que preprovision, postprovision ou postdeploy. Votre extension exécute une logique personnalisée à ces points sans que l’utilisateur l’appelle directement. Par exemple, l’exemple d’extension vérifie les balises requises preprovision avant la création de ressources.
service-target-provider : Enregistre une nouvelle cible de déploiement afin que azd sache comment packager et déployer un service sur un hôte qu’il ne prend pas en charge nativement. Une cible de service correspond à la valeur host dans azure.yaml. Par exemple, vous pouvez ajouter un fournisseur qui déploie un service sur une plateforme tierce ou un environnement d’hébergement interne.
framework-service-provider: Enregistre la prise en charge d’un langage ou d’un framework pour que azd sache comment restaurer, compiler et packager ce type de projet. Cela correspond à la language valeur dans azure.yaml. Par exemple, vous pouvez ajouter la prise en charge des builds pour une langue qui azd ne reconnaît pas par défaut.
provisioning-provider: remplace la façon dont azd provisionne l’infrastructure pendant azd provision et azd up. Au lieu du flux intégré Bicep ou Terraform, votre extension définit ce qui se passe. Par exemple, vous pouvez intégrer un autre outil d’infrastructure en tant que code ou une API de déploiement personnalisée.
validation-provider: ajoute des vérifications au pipeline de validation azd qui sont exécutées sur un projet ou un environnement. Par exemple, vous pouvez vérifier que les conventions d’affectation de noms, les balises requises ou les paramètres de sécurité sont en place avant qu’un déploiement ne se poursuive.
mcp-server: expose les fonctionnalités de votre extension en tant qu'outils MCP (Model Context Protocol) que les agents IA, tels que GitHub Copilot, peuvent découvrir et appeler. Par exemple, l’extension d’exemple peut exposer un outil suggest_tags. Pour plus d’informations, consultez Ajouter un serveur MCP à une extension.
metadata : fournit des métadonnées de commande et de configuration plus détaillées, que azd utilise pour décrire votre extension, comme des descriptions détaillées des commandes et des indications de configuration affichées dans la sortie d’aide et IntelliSense.

Cet article se concentre sur les deux fonctionnalités les plus courantes : les commandes personnalisées et les événements de cycle de vie. Pour obtenir la mcp-server fonctionnalité, consultez Ajouter un serveur MCP à une extension. Pour plus d’informations sur les fonctionnalités du fournisseur, consultez la référence de l’infrastructure d’extension.

Ajouter des commandes personnalisées

La fonctionnalité custom-commands permet à votre extension d’enregistrer de nouvelles commandes dans un espace de noms dans azd. L’exemple d’extension utilise déjà cette fonctionnalité pour la azd tagger show commande.

Déclarez la fonctionnalité dans extension.yaml.
```
capabilities:
  - custom-commands
```
Générez vos commandes à l’aide de l’assistance azdext.NewExtensionRootCommand , qui inscrit les indicateurs standard azd et la gestion des variables d’environnement afin de ne pas avoir à les déclarer manuellement :
```
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
}
```
L’assistance retourne un *ExtensionContext qui expose les valeurs résolues des indicateurs standard, tels que Environment et OutputFormat. Transmettez le contexte à vos sous-commandes et lisez ce contexte dans leurs gestionnaires RunE au lieu de redéclarer les indicateurs standard.

La lifecycle-events fonctionnalité permet à votre extension d’exécuter une logique personnalisée pendant les événements de cycle de vie du projet et du service, tels que preprovision ou postdeploy. Pour l’exemple d’extension, utilisez un preprovision événement pour vérifier que les balises requises sont définies avant azd de provisionner des ressources.

Déclarez la fonctionnalité dans extension.yaml.

capabilities:
  - custom-commands
  - lifecycle-events

Ajoutez une listen commande à votre extension. azd appelle cette commande pour établir la connexion bidirectionnelle utilisée pour les événements. Utilisez le azdext.NewExtensionHost générateur pour inscrire vos gestionnaires d’événements :

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
        },
    }
}

Inscrivez la listen commande sur votre commande racine :
```
rootCmd.AddCommand(newListenCommand())
```

Lorsqu’un utilisateur exécute azd provision ou azd up, azd invoque votre extension et appelle le gestionnaire preprovision avant de provisionner les ressources.

Filtrer les événements de service

Les gestionnaires d’événements de service prennent en charge le filtrage facultatif afin de gérer uniquement des types de service spécifiques. Par exemple, vous pouvez gérer l’événement prepackage uniquement pour Python services d’application conteneur :

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",
        },
    )

Reconstruire et tester

Après avoir ajouté une fonctionnalité, régénérez l’extension et testez le nouveau comportement :

Si vous utilisez l’observateur, vos modifications sont régénérées automatiquement. Sinon, générez manuellement :
```
azd x build
```
Testez la fonctionnalité. Pour les événements du cycle de vie, exécutez une commande qui déclenche l’événement, comme azd provision.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-07-29