Definieren des Erweiterungsmanifests

Jede Azure Developer CLI (azd)-Erweiterung enthält ein extension.yaml Manifest, das seine Metadaten und Funktionen beschreibt. azd verwendet diese Metadaten in der Erweiterungsregistrierung, um Benutzern zu helfen, Ihre Erweiterung zu ermitteln, zu installieren und zu verstehen. In diesem Artikel werden die Manifesteigenschaften mithilfe der Beispielerweiterung Contoso Resource Tagger aus der Schnellstartanleitung zum Erstellen einer Beispielerweiterung erläutert. Sie können dieselben Konzepte auf jede Erweiterung anwenden.

Note

azd Erweiterungen befinden sich derzeit in der Betaversion.

Manifesteigenschaften

Das extension.yaml Manifest unterstützt die folgenden Eigenschaften.

Erforderliche Eigenschaften

Jedes Manifest muss die folgenden Eigenschaften enthalten:

Eigentum	Description
`id`	Eindeutiger Bezeichner für die Erweiterung, z. B. `contoso.azd.tagger`.
`version`	Semantische Version im `MAJOR.MINOR.PATCH` Format.
`displayName`	Lesbarer Name der Erweiterung.
`description`	Detaillierte Beschreibung der Erweiterung.

Jedes Manifest muss außerdem entweder capabilities oder dependencies enthalten. Eine Erweiterung, die Befehle oder Anbieter bereitstellt, deklariert capabilities. Ein Erweiterungspaket deklariert stattdessen dependencies.

Optionale Eigenschaften:

Das Manifest unterstützt auch die folgenden optionalen Eigenschaften:

Eigentum	Description
`namespace`	Befehlsnamensraum, der die Befehle der Erweiterung gruppiert, z. B. `tagger`.
`entryPoint`	Ausführbare Datei oder Skript, die als Einstiegspunkt dient.
`language`	Programmiersprache, in der die Erweiterung geschrieben ist, wie `go`.
`capabilities`	Vielzahl an Erweiterungsfunktionen.
`usage`	Anweisungen zur Verwendung der Erweiterung.
`examples`	Array von Verwendungsbeispielen mit einem Namen, einer Beschreibung und einer Verwendung.
`tags`	Schlüsselwörter für Kategorisierung und Filterung.
`dependencies`	Andere Erweiterungen, von denen diese Erweiterung abhängt.
`providers`	Liste der von der Erweiterung registrierten Anbieter.
`platforms`	Plattformspezifische Metadaten.
`mcp`	Modellkontextprotokollserverkonfiguration.
`requiredAzdVersion`	Semantische Versionsbeschränkung für die Version, die zur Verwendung der Erweiterung erforderlich ist, z. B. `>= 1.24.0`.

Beispielmanifest

Das folgende Beispiel zeigt ein extension.yaml-Manifest für die Beispielerweiterung 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

Der $schema Kommentar oben in der Datei ermöglicht die Überprüfung und IntelliSense in Editoren, die den YAML-Sprachserver unterstützen.

Deklarieren von Funktionen

Das capabilities Array deklariert, was Ihre Erweiterung tun kann. azd gewährt die entsprechenden Berechtigungen zur Laufzeit, und einige Frameworkdienste schlagen mit einem Berechtigungsfehler fehl, wenn die übereinstimmende Funktion nicht deklariert ist. Die Beispielerweiterung beginnt nur mit custom-commands:

capabilities:
  - custom-commands

Wenn Sie funktionen in den anderen Artikeln hinzufügen, fügen Sie weitere Funktionen hinzu. Fügen Sie beispielsweise Erweiterungsfunktionen hinzulifecycle-events, und fügen Sie einen MCP-Server zu einer Erweiterung hinzumcp-server. Die verfügbaren Funktionen sind:

custom-commands: Fügen Sie azd unter Ihrem Namespace neue Befehle hinzu, z. B. azd tagger show.
lifecycle-events: Führen Sie benutzerdefinierte Logik aus, wenn azd Ereignisse wie preprovision oder postdeploy auslöst.
mcp-server: Verfügbarmachen von Modellkontextprotokolltools, die KI-Agents aufrufen können.
service-target-provider: Fügen Sie ein benutzerdefiniertes Bereitstellungsziel für ein host hinzu, das azd standardmäßig nicht unterstützt.
framework-service-provider: Fügen Sie Unterstützung für Build und Paketierung für ein language hinzu, das azd standardmäßig nicht erkennt.
provisioning-provider: Ersetzen Sie die Art und Weise, wie azd Infrastruktur bereitstellt, durch eine benutzerdefinierte Implementierung.
validation-provider: Fügen Sie Überprüfungen hinzu, die in der Überprüfungspipeline azd ausgeführt werden.
metadata: Bereitstellen detaillierterer Befehls- und Konfigurationsmetadaten für die Hilfeausgabe und IntelliSense.

Eine ausführliche erläuterung der einzelnen Funktionen mit Beispielen finden Sie unter Hinzufügen von Erweiterungsfunktionen.

Hinzufügen von Verwendungsbeispielen

Das examples Array dokumentiert häufig verwendete Methoden für die Verwendung Ihrer Erweiterung. azd zeigt diese Beispiele an, wenn Benutzer Details zu Ihrer Erweiterung anzeigen:

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

Registrieren von Anbietern

Wenn Ihre Erweiterung benutzerdefinierte Dienstziele oder Frameworkdienste bereitstellt, deklarieren Sie sie im providers Abschnitt, damit azd Sie wissen, was Ihre Erweiterung bietet:

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

Plattformspezifische Konfiguration hinzufügen

Verwenden Sie die platforms Eigenschaft, um plattformspezifische Metadaten bereitzustellen, z. B. den namen der ausführbaren Datei für jedes Betriebssystem.

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

Deklarieren von Abhängigkeiten

Erweiterungen können von anderen Erweiterungen abhängig sein, indem sie das dependencies Array verwenden. Abhängigkeiten unterstützen semantische Versionsverwaltungseinschränkungen:

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

azd installiert oder aktualisiert auf die höchste veröffentlichte Version, die jede Einschränkung erfüllt. Zu den gängigen Einschränkungsformaten gehören:

^1.0.0: Kompatibel mit Version 1.x.x.
~1.2.0: Kompatibel mit Version 1.2.x.
>=1.0.0 <2.0.0: Ein Versionsbereich.

Gruppenerweiterungen mit Erweiterungspaketen

Ein Erweiterungspaket ist ein Manifest, das verwandte Erweiterungen gruppiert, sodass Benutzer sie mit einem einzigen Befehl installieren können. Ein Pack deklariert dependencies , stellt jedoch keine ausführbare Datei, keinen Befehlsnamespace oder eigene Funktionen bereit. Verwenden Sie ein Paket, um einen kuratierten Satz von Erweiterungen zu veröffentlichen, z. B. eine Produktfamilie oder ein Szenariobundle:

# 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"

Durch die rekursive Installation eines Pakets werden die Abhängigkeiten aus derselben Erweiterungsquelle wie das Paket installiert.

Feedback

War diese Seite hilfreich?

Last updated on 2026-07-29