Définir le manifeste d’extension

Chaque extension AZURE Developer CLI (azd) inclut un extension.yaml manifeste qui décrit ses métadonnées et ses fonctionnalités. azd utilise ces métadonnées dans le Registre d’extensions pour aider les utilisateurs à découvrir, installer et comprendre votre extension. Cet article explique les propriétés du manifeste en utilisant l’extension d’exemple Contoso Resource Tagger du guide de démarrage rapide Créer une extension d’exemple. Vous pouvez appliquer les mêmes concepts à n’importe quelle extension.

Note

azd les extensions sont actuellement en version bêta.

Propriétés du manifeste

Le extension.yaml manifeste prend en charge les propriétés suivantes.

Propriétés requises

Chaque manifeste doit inclure les propriétés suivantes :

Propriété Description
id Identificateur unique de l’extension, tel que contoso.azd.tagger.
version Version sémantique au MAJOR.MINOR.PATCH format.
displayName Nom compréhensible de l’extension.
description Description détaillée de l’extension.

Chaque manifeste doit également inclure soit capabilities, soit dependencies. Une extension qui fournit des commandes ou des fournisseurs de services déclare capabilities. Un pack d’extensions déclare dependencies à la place.

Propriétés facultatives

Le manifeste prend également en charge les propriétés facultatives suivantes :

Propriété Description
namespace Espace de noms de commandes qui regroupe les commandes de l’extension, telles que tagger.
entryPoint Exécutable ou script qui sert de point d’entrée.
language Langage de programmation dans lequel l’extension est écrite, tel que go.
capabilities Tableau de fonctionnalités d’extension.
usage Instructions sur l’utilisation de l’extension.
examples Tableau d’exemples d’utilisation avec un nom, une description et une utilisation.
tags Mots clés pour la catégorisation et le filtrage.
dependencies Les autres extensions dont dépend cette extension.
providers Liste des fournisseurs que l’extension enregistre.
platforms Métadonnées spécifiques à la plateforme.
mcp Configuration du serveur Model Context Protocol.
requiredAzdVersion Contrainte de version sémantique portant sur la azd version requise pour utiliser l’extension, par exemple >= 1.24.0.

Exemple de manifeste

L’exemple suivant présente le manifeste extension.yaml de l’extension d’exemple Contoso Resource Tagger :

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/cli/azd/extensions/extension.schema.json

id: contoso.azd.tagger
namespace: tagger
displayName: Contoso Resource Tagger
description: Standardize and report Azure resource tags for an azd project.
usage: azd tagger <command> [options]
version: 0.1.0
language: go
capabilities:
  - custom-commands

examples:
  - name: show
    description: Displays a greeting from the extension.
    usage: azd tagger show

tags:
  - tags
  - governance
  - example

Le $schema commentaire situé en haut du fichier active la validation et IntelliSense dans les éditeurs qui prennent en charge le serveur de langage YAML.

Déclarer des fonctionnalités

Le capabilities tableau déclare ce que votre extension peut faire. azd accorde les autorisations correspondantes au moment de l’exécution et certains services d’infrastructure échouent avec une erreur d’autorisation si la fonctionnalité correspondante n’est pas déclarée. L’exemple d’extension commence uniquement par custom-commands :

capabilities:
  - custom-commands

Lorsque vous ajoutez des fonctionnalités dans les autres articles, vous ajoutez d’autres fonctionnalités. Par exemple, ajouter des fonctionnalités d’extension ajoute lifecycle-events, et ajouter un serveur MCP à une extension ajoute mcp-server. Les fonctionnalités disponibles sont les suivantes :

  • custom-commands : Ajoutez de nouvelles commandes à azd sous votre espace de noms, comme azd tagger show.
  • lifecycle-events : Exécuter une logique personnalisée lorsque azd déclenche des événements comme preprovision ou postdeploy.
  • mcp-server: Exposez les outils Model Context Protocol que les agents IA peuvent invoquer.
  • service-target-provider: Ajoutez une cible de déploiement personnalisée pour un host qui azd ne prend pas en charge par défaut.
  • framework-service-provider: Ajoutez la prise en charge de build et de package pour un language élément qui azd ne reconnaît pas par défaut.
  • provisioning-provider: remplacez la configuration azd de l’infrastructure par une implémentation personnalisée.
  • validation-provider : ajoutez des vérifications qui s’exécutent dans le pipeline de validation azd.
  • metadata: fournissez des métadonnées de commande et de configuration plus riches pour la sortie d’aide et IntelliSense.

Pour obtenir une explication complète de chaque fonctionnalité avec des exemples, consultez Ajouter des fonctionnalités d’extension.

Ajouter des exemples d’utilisation

Le examples tableau documente les méthodes courantes d’utilisation de votre extension. azd présente ces exemples lorsque les utilisateurs affichent des détails sur votre extension :

examples:
  - name: show
    description: Displays a greeting from the extension.
    usage: azd tagger show

Inscrire des fournisseurs

Lorsque votre extension fournit des cibles de service personnalisées ou des services d’infrastructure, déclarez-les dans la providers section pour azd savoir ce que votre extension offre :

providers:
  - name: tagger
    type: service-target
    description: Deploys tagged resources to Azure.

Ajouter une configuration spécifique à la plateforme

Utilisez la propriété pour fournir des métadonnées spécifiques à la platforms plateforme, telles que le nom exécutable de chaque système d’exploitation.

platforms:
  windows:
    executable: tagger.exe
  linux:
    executable: tagger
  darwin:
    executable: tagger

Déclarer des dépendances

Les extensions peuvent dépendre d’autres extensions en utilisant le tableau dependencies. Les dépendances prennent en charge les contraintes de versionnement sémantique :

dependencies:
  - id: microsoft.azd.core
    version: "^1.0.0"

azd installe ou met à niveau vers la version publiée la plus élevée qui satisfait à chaque contrainte. Les formats de contrainte courants sont les suivants :

  • ^1.0.0: compatible avec la version 1.x.x.
  • ~1.2.0: compatible avec la version 1.2.x.
  • >=1.0.0 <2.0.0: une plage de versions.

Regrouper des extensions à l’aide de packs d’extensions

Un pack d’extensions est un manifeste qui regroupe les extensions associées afin que les utilisateurs puissent les installer avec une seule commande. Un pack déclare dependencies , mais ne fournit pas d’exécutable, d’espace de noms de commande ou de fonctionnalités propres. Utilisez un pack pour publier un ensemble organisé d’extensions, comme une famille de produits ou un bundle de scénarios :

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/cli/azd/extensions/extension.schema.json

id: contoso.tools
displayName: Contoso Tools Extension Pack
description: Installs the Contoso azd extensions.
version: 0.1.0

dependencies:
  - id: contoso.azd.tagger
    version: "~0.1.0"

L’installation d’un pack installe de manière récursive ses dépendances à partir de la même source d’extension que le pack.

Contenu connexe

  • Last updated on