Erweiterungsentwicklungskonzepte

Azure Developer CLI (azd) Erweiterungen fügen neue Befehle hinzu, automatisieren Workflows und integrieren andere Dienste in azd. In diesem Artikel werden die Konzepte erläutert, die Sie verstehen müssen, bevor Sie eine Erweiterung erstellen, z. B. die Entwicklertools, das Software Development Kit (SDK) und die azd Kommunikation mit einer ausgeführten Erweiterung. Informationen dazu, welche Erweiterungen aus Benutzerperspektive stammen, finden Sie in der Übersicht über Erweiterungen.

Die Entwicklererweiterung

Die schnellste Möglichkeit zum Erstellen von Erweiterungen ist die Verwendung der azd Entwicklererweiterung (microsoft.azd.extensions). Die Entwicklererweiterung fügt im Namespace azd x eine Reihe von Befehlen hinzu, mit denen Sie das Grundgerüst Ihrer Erweiterung erstellen, sie bauen, paketieren und veröffentlichen können:

Command Description
azd x init Erstellt die Grundstruktur für ein neues Erweiterungsprojekt in der Sprache Ihrer Wahl.
azd x build Erstellt die Binärdatei der Erweiterung für die lokale Entwicklung.
azd x watch Überwacht das Projekt auf Änderungen und erstellt die Erweiterung automatisch neu und installiert sie.
azd x pack Erstellt ein Paket aus den Artefakten der Erweiterung, um sie zur Veröffentlichung vorzubereiten.
azd x release Erstellt eine GitHub Version für die Erweiterung.
azd x publish Aktualisiert eine Erweiterungsregistrierung mit den neuen Erweiterungsmetadaten.

In der Schnellstartanleitung zum Erstellen einer Beispielerweiterung wird gezeigt, wie Sie die Entwicklererweiterung installieren und das Gerüst für Die erste Erweiterung erstellen.

Die Entwicklererweiterung unterstützt registrierungsbasierte Veröffentlichungsworkflows und portierbare Bundleverteilung. Verwenden Sie azd x pack, um Plattformartefakte für die Veröffentlichung und zur Veröffentlichung in einer Registry zu erstellen, oder erstellen Sie ein eigenständiges .zip-Paket, wenn Sie eine Erweiterung freigeben müssen, ohne selbst eine Registry zu hosten. Bundles können aus einer lokalen Datei installiert oder remote unter einer HTTPS-URL gehostet werden. Eine schrittweise Anleitung finden Sie unter Veröffentlichen einer Erweiterung.

Das Erweiterungsframework und gRPC

azd und Erweiterungen werden als separate Prozesse ausgeführt, die über gRPC kommunizieren. Wenn Sie einen Erweiterungsbefehl aufrufen, treten die folgenden Schritte auf:

  1. azd startet einen gRPC-Server auf einem zufälligen Port und legt die AZD_SERVER Umgebungsvariable mit der Serveradresse fest.
  2. azd legt die Umgebungsvariable fest, bei der AZD_ACCESS_TOKEN es sich um ein signiertes JSON-Webtoken (JWT) handelt, das den Erweiterungszugriff auf azd Dienste für die Lebensdauer des Befehls gewährt.
  3. azd ruft den Erweiterungsbefehl auf und übergibt die aktuellen Argumente, Flags und Umgebungsvariablen.
  4. Ihre Erweiterung verwendet einen gRPC-Client, um über die Framework-Dienste mit azd zu kommunizieren, beispielsweise um den Benutzer zu einer Eingabe aufzufordern oder die Projektkonfiguration zu lesen.
  5. azd wartet, bis der Befehl abgeschlossen ist, und meldet einen Exitcode ungleich null als Fehler.

Mit diesem Modell können Erweiterungen auf konsistente und sichere Weise mit azd interagieren, ohne direkt auf den internen azd-Zustand zuzugreifen.

Anforderungen an Erweiterungen auf Projektebene

Projekte können die Erweiterungen, die sie benötigen, in azure.yaml deklarieren. Verwenden Sie den requiredVersions.extensions Abschnitt, um Erweiterungs-IDs und Versionsbeschränkungen aufzulisten, damit azd die Versionen aufgelöst werden können, die dem Projekt entsprechen.

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

Deklarieren Sie die erforderlichen Erweiterungen, wenn ein Projekt von von Erweiterungen bereitgestellten Hosts, Anbietern, Lebenszyklushandlern, Überprüfungen oder Befehlen abhängt. Die genaue Schemasyntax und die unterstützte Versionssyntax finden Sie unter requiredVersions.

Das Azdext SDK

Das azdext Paket ist das Go SDK für das Erweiterungsframework. Es stellt einen gRPC-Client und Hilfsprogramme bereit, die die Kommunikationsdetails für Sie verarbeiten, damit Sie sich auf Ihre Erweiterungslogik konzentrieren können. Das SDK enthält Hilfsfunktionen für Folgendes:

  • Erstellen Sie einen Stammbefehl, der die Standardkennzeichnungen azd und die Behandlung von Umgebungsvariablen registriert.
  • Fügen Sie das azd Zugriffstoken ausgehenden Anfragen hinzu.
  • Framework-Dienste azd wie den Diensten Projekt, Umgebung, Konto und Prompt aufrufen.
  • Melden Sie benannte Verwendungsereignisse über die TelemetryService.ReportUsage gRPC-API für offizielle Quellerweiterungen. Details zur API-Verwendung finden Sie unter "Kommunizieren mit azd" mithilfe des SDK.
  • Registrieren von Lebenszyklusereignishandlern und benutzerdefinierten Anbietern über einen Erweiterungshost.

Informationen zum Aufrufen azd von Diensten aus Ihrer Erweiterung finden Sie unter "Kommunizieren mit azd" mithilfe des SDK.

Erweiterungsfunktionen

Funktionen deklarieren, was eine Erweiterung tun kann. Führe die Fähigkeiten einer Erweiterung im extension.yaml Manifest auf, und azd erteilt die entsprechenden Berechtigungen zur Laufzeit. Zu den verfügbaren Funktionen gehören:

  • custom-commands: Fügen Sie neue Befehlsgruppen und Befehle hinzu.azd
  • lifecycle-events: Abonnieren Sie Projekt- und Servicelebenszyklusereignisse, z. B. preprovision und postdeploy.
  • mcp-server: Bereitstellen von MCP-Tools (Model Context Protocol) für KI-Agents.
  • service-target-provider: Bereitstellen benutzerdefinierter Dienstbereitstellungsziele.
  • framework-service-provider: Stellen Sie unterstützung für benutzerdefinierte Sprachen und Framework-Builds bereit.
  • provisioning-provider: Stellen Sie einen benutzerdefinierten Ablauf für die Infrastrukturbereitstellung bereit.
  • validation-provider: Validierungsprüfungen zur azd Validierungspipeline beitragen.
  • metadata: Stellen Sie umfangreiche Befehls- und Konfigurationsmetadaten für die Hilfeausgabe und IntelliSense bereit.

Informationen zum Hinzufügen von Funktionen zu einer Erweiterung finden Sie unter Hinzufügen von Erweiterungsfunktionen.

Unterstützte Sprachen

Sie können Erweiterungen in jeder Sprache erstellen azd , die gRPC unterstützt, und azd x init Startvorlagen für mehrere Sprachen enthält. Go verfügt über den vollständigsten Support, einschließlich erstklassiger SDK-Hilfsprogramme azdext , sodass die Artikel in diesem Abschnitt go für alle Beispiele verwenden.

Language Supportstufe
Go Optimale Unterstützung und erstklassige SDK-Hilfsprogramme.
.NET (C#) Starke Integration mit einer Startvorlage.
Python Gute Integration mit einer Startvorlage.
JavaScript Grundlegende Integration mit einer Startervorlage.

Für Erweiterungen, die in anderen Sprachen als Go erstellt wurden, können Sie gRPC-Clients aus den Protodateien im azure/azure-dev Repository generieren. Den aktuellen Status der Sprachunterstützung finden Sie in der Dokumentation zum upstream-Erweiterungsframework.

Erweiterungsregister

Sie verteilen Erweiterungen über Registrierungsquellen oder Erweiterungspakete. Registrierungsquellen sind URL-basierte oder dateibasierte Manifeste, die verfügbare Erweiterungen und ihre Artefakte beschreiben. Erweiterungs-Bundles sind eigenständige .zip Pakete, die Sie direkt aus einer lokalen Datei installieren oder per HTTPS-URL remote hosten können, wenn Sie keine Registry betreiben möchten.

  • Die offizielle Registry ist in azd vorkonfiguriert und enthält geprüfte Erweiterungen des Erstanbieters. Offizielle Erweiterungen werden in einer Verzweigung des Azure/Azure-Dev-Repositorys entwickelt.
  • URL-basierte Quellen ermöglichen die Installation aus öffentlichen oder privaten Remote-Registrierungsmanifesten.
  • Mit dateibasierten Quellen können Sie aus lokalen Registrierungsmanifesten für Entwicklungs-, Test- oder Offlineszenarien installieren.
  • Die Entwicklungs- und Nightly-Registries sind optionale Quellen für noch in Arbeit befindliche und automatisch erstellte Erstanbieter-Erweiterungen. Erweiterungen in der Dev-Registrierung sind nicht signiert, werden nicht vom Azure-Support abgedeckt und können ohne Vorankündigung geändert oder entfernt werden.

Informationen zum Veröffentlichen einer Erweiterung in einer Registrierung finden Sie unter Veröffentlichen einer Erweiterung.

Verwandte Inhalte

  • Last updated on