Kommunizieren mit azd mithilfe des SDK

Erweiterungen kommunizieren mit der Azure Developer CLI (azd) über eine gRPC-Verbindung mithilfe des azdext SDK. Mit dem SDK kann Ihre Erweiterung Projekt- und Umgebungsdaten lesen, den Benutzer zu Eingaben auffordern und azd-Dienste aufrufen. In diesem Artikel erfahren Sie, wie Sie das SDK verwenden, um die Beispielerweiterung Contoso Resource Tagger aus der Schnellstartanleitung "Erstellen einer Beispielerweiterung" zu verbessern. Sie können die gleichen Muster auf jede Erweiterung anwenden.

Funktionsweise der Kommunikation

Wenn azd Die Erweiterung ausgeführt wird, wird ein gRPC-Server gestartet und zwei Werte über Umgebungsvariablen an die Erweiterung übergeben:

• AZD_SERVER: Die Adresse des gRPC-Servers, zum Beispiel localhost:12345.
• AZD_ACCESS_TOKEN: Ein JWT-Zugriffstoken, das die Anforderungen Ihrer Erweiterung autorisiert.

Ihre Erweiterung verwendet das azdext SDK, um eine Verbindung mit diesem Server herzustellen und Dienste aufzurufen azd . Das Token beschränkt jede Anfrage auf die Funktionen, die Ihre Erweiterung in ihrem Manifest deklariert.

Erstellen eines azd-Clients

Die azdext.NewAzdClient-Funktion stellt einen Client bereit, der mithilfe der Umgebungsvariablen, die azd bereitstellt, eine Verbindung mit azd herstellt. Schließen Sie den eingehenden Kontext so azdext.WithAccessToken ein, dass das SDK das Zugriffstoken an jede Anforderung anfügt:

import (
    "context"
    "fmt"

    "github.com/azure/azure-dev/cli/azd/pkg/azdext"
)

func run(ctx context.Context) error {
    // Attach the AZD_ACCESS_TOKEN to outgoing requests.
    ctx = azdext.WithAccessToken(ctx)

    azdClient, err := azdext.NewAzdClient()
    if err != nil {
        return fmt.Errorf("failed to create azd client: %w", err)
    }
    defer azdClient.Close()

    // Use azdClient to call azd services.
    return nil
}

Lesen von Projekt- und Umgebungsdaten

Verwenden Sie die Projekt- und Umgebungsdienste, um Informationen über das aktuelle azd Projekt und die aktuelle Umgebung abzurufen. Lesen Sie für die Beispielerweiterung das Projekt, damit Sie die zugehörigen Ressourcen und Tags überprüfen können:

// Get the current project.
getProject, err := azdClient.Project().Get(ctx, &azdext.EmptyRequest{})
if err != nil {
    return fmt.Errorf("failed to get project: %w", err)
}

fmt.Printf("Project name: %s\n", getProject.Project.Name)
fmt.Printf("Project path: %s\n", getProject.Project.Path)

// Get the current environment.
getEnv, err := azdClient.Environment().GetCurrent(ctx, &azdext.EmptyRequest{})
if err != nil {
    return fmt.Errorf("failed to get environment: %w", err)
}

fmt.Printf("Environment name: %s\n", getEnv.Environment.Name)

Lese- und Schreibumgebungswerte

Der Umgebungsdienst liest und schreibt Umgebungswerte. Diese Werte bleiben im .azure Verzeichnis des Projekts erhalten. Speichern Sie für die Beispielerweiterung einen erforderlichen Tagwert, den der Benutzer bereitstellt:

// Read an environment value.
getValue, err := azdClient.Environment().GetValue(ctx, &azdext.GetEnvRequest{
    EnvName: getEnv.Environment.Name,
    Key:     "CONTOSO_COST_CENTER",
})
if err == nil {
    fmt.Printf("Cost center: %s\n", getValue.Value)
}

// Write an environment value.
_, err = azdClient.Environment().SetValue(ctx, &azdext.SetEnvRequest{
    EnvName: getEnv.Environment.Name,
    Key:     "CONTOSO_COST_CENTER",
    Value:   "CC-1001",
})
if err != nil {
    return fmt.Errorf("failed to set environment value: %w", err)
}

Benutzer auffordern

Der Promptdienst stellt konsistente, interaktive Aufforderungen bereit, die der azd Benutzererfahrung entsprechen. Fordern Sie für die Beispielerweiterung den Benutzer auf, einen fehlenden Tagwert einzufordern:

promptResponse, err := azdClient.Prompt().Prompt(ctx, &azdext.PromptRequest{
    Options: &azdext.PromptOptions{
        Message: "Enter the cost center tag value",
    },
})
if err != nil {
    return fmt.Errorf("failed to prompt for value: %w", err)
}

costCenter := promptResponse.Value

Der Aufforderungsdienst unterstützt auch Auswahlaufforderungen, Bestätigungsaufforderungen und Mehrfachauswahleingabeaufforderungen. Verwenden Sie diese Optionen, anstatt Ihre eigene Eingabebehandlung zu schreiben, damit Ihre Erweiterung dem Aussehen und Verhalten entspricht azd.

Verfügbare Dienste

Das azdext SDK macht die folgenden gRPC-Dienste über den Client verfügbar:

Die vollständige Liste der Dienste und Nachrichtendefinitionen finden Sie in den Protodateien im repository azure-Dev und in der Referenz zum Erweiterungsframework.

Fehler melden

Geben Sie Fehler aus Ihren Befehlshandlern zurück, damit azd sie konsistent anzeigen und den richtigen Exitcode festlegen kann. Versehen Sie Fehler mithilfe von fmt.Errorf und dem Verb %w mit Kontext, damit Aufrufer den zugrunde liegenden Fehler untersuchen können:

if err != nil {
    return fmt.Errorf("failed to apply tags: %w", err)
}

Verwandte Inhalte

• Hinzufügen von Erweiterungsfunktionen
• Hinzufügen eines MCP-Servers zu einer Erweiterung
• Veröffentlichen einer Erweiterung
• Referenz zum Erweiterungsframework