Hinzufügen von Erweiterungsfunktionen

Funktionen definieren, was eine Azure Developer CLI (azd)-Erweiterung tun kann, von dem Hinzufügen von benutzerdefinierten Befehlen zum Verbinden mit dem Bereitstellungslebenszyklus. In diesem Artikel erfahren Sie, wie Sie der Beispielerweiterung Contoso Resource Tagger Funktionen aus der Schnellstartanleitung "Erstellen einer Beispielerweiterung" hinzufügen. Sie können die gleichen Muster auf jede Erweiterung anwenden.

Jede Funktion erfordert zwei Dinge: einen Eintrag im capabilities Array Ihres Erweiterungsmanifests und die entsprechende Implementierung in Ihrem Erweiterungscode.

Note

azd Erweiterungen befinden sich derzeit in der Betaversion.

Verfügbare Funktionen

azd Erweiterungen können die folgenden Funktionen deklarieren:

  • custom-commands: Fügt neue Befehle und Befehlsgruppen unter azd dem Namespace Ihrer Erweiterung hinzu. Zum Beispiel fügt die Beispielerweiterung azd tagger show hinzu. Verwenden Sie diese Funktion, um Aufgaben verfügbar zu machen, die Benutzer direkt über die Befehlszeile ausführen.
  • lifecycle-events: Abonniert Ereignisse, die azd während der Ausführung auslöst, wie preprovision, postprovision oder postdeploy. Ihre Erweiterung führt an diesen Punkten benutzerdefinierte Logik aus, ohne dass der Benutzer sie direkt aufruft. Zum Beispiel überprüft die Beispielerweiterung, ob auf preprovision erforderliche Tags vorhanden sind, bevor Ressourcen erstellt werden.
  • service-target-provider: Registriert ein neues Bereitstellungsziel, damit azd er weiß, wie ein Dienst auf einem Host verpackt und bereitgestellt wird, der nicht sofort unterstützt wird. Ein Dienstziel entspricht dem Wert host in azure.yaml. Sie können beispielsweise einen Anbieter hinzufügen, der einen Dienst auf einer Drittanbieterplattform oder einer internen Hostingumgebung bereitstellt.
  • framework-service-provider: Registriert die Unterstützung für eine Sprache oder ein Framework, sodass azd Sie wissen, wie Sie diesen Projekttyp wiederherstellen, erstellen und verpacken können. Dies entspricht dem language Wert in azure.yaml. Sie könnten beispielsweise Build-Unterstützung für eine Sprache hinzufügen, die azd standardmäßig nicht erkennt.
  • provisioning-provider: Ersetzt, wie azd während azd provision und azd up Infrastruktur bereitstellt. Anstelle des integrierten Bicep- oder Terraform-Flusses definiert Ihre Erweiterung, was passiert. Sie können beispielsweise ein anderes Infrastruktur-as-Code-Tool oder eine benutzerdefinierte Bereitstellungs-API integrieren.
  • validation-provider: Fügt der azd-Validierungspipeline Prüfungen hinzu, die für ein Projekt oder eine Umgebung ausgeführt werden. So können Sie beispielsweise überprüfen, ob Benennungskonventionen, erforderliche Tags oder Sicherheitseinstellungen vorhanden sind, bevor eine Bereitstellung fortgesetzt wird.
  • mcp-server: Macht die Funktionalität Ihrer Erweiterung als MCP-Tools (Model Context Protocol) verfügbar, die KI-Agents wie GitHub Copilot ermitteln und aufrufen können. Beispielsweise kann die Beispielerweiterung ein suggest_tags Tool verfügbar machen. Weitere Informationen finden Sie unter Hinzufügen eines MCP-Servers zu einer Erweiterung.
  • metadata: Stellt erweiterte Metadaten für Befehle und Konfigurationen bereit, die azd verwendet, um Ihre Erweiterung zu beschreiben, z. B. detaillierte Befehlsbeschreibungen und Konfigurationshinweise, die in der Hilfeausgabe und in IntelliSense angezeigt werden.

In diesem Artikel werden die beiden am häufigsten verwendeten Funktionen behandelt: benutzerdefinierte Befehle und Lebenszyklusereignisse. Informationen zur mcp-server Funktion finden Sie unter Hinzufügen eines MCP-Servers zu einer Erweiterung. Ausführliche Informationen zu den Anbieterfunktionen finden Sie in der Referenz zum Erweiterungsframework.

Hinzufügen von benutzerdefinierten Befehlen

Mit der custom-commands Funktion können Ihre Erweiterung neue Befehle unter einem Namespace in azdregistrieren. Die Beispielerweiterung verwendet diese Funktion bereits für den azd tagger show Befehl.

  1. Deklarieren Sie die Funktion in extension.yaml.

    capabilities:
  - custom-commands

  2. Erstellen Sie Ihre Befehle mithilfe des azdext.NewExtensionRootCommand Hilfsprogramms, das die Standardkennzeichnungen azd und die Umgebungsvariablenbehandlung registriert, sodass Sie sie nicht manuell deklarieren müssen:

    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
}

    Die Hilfsfunktion gibt ein *ExtensionContext zurück, das die ermittelten Werte der Standard-Flags wie Environment und OutputFormat bereitstellt. Übergeben Sie den Kontext an Ihre Unterbefehle und lesen Sie ihn in deren RunE-Handlern, anstatt die Standard-Flags erneut zu deklarieren.

Abonnieren von Lebenszyklusereignissen

Die lifecycle-events-Möglichkeit ermöglicht Ihrer Erweiterung, benutzerdefinierte Logik während Lebenszyklusereignissen von Projekten und Diensten auszuführen, wie preprovision oder postdeploy. Verwenden Sie für die Beispielerweiterung ein preprovision Ereignis, um sicherzustellen, dass erforderliche Tags festgelegt werden, bevor azd Ressourcen festgelegt werden.

  1. Deklarieren Sie die Funktion in extension.yaml.

    capabilities:
  - custom-commands
  - lifecycle-events

  2. Fügen Sie Ihrer Erweiterung einen listen Befehl hinzu. azd ruft diesen Befehl auf, um die bidirektionale Verbindung einzurichten, die für Ereignisse verwendet wird. Verwenden Sie den azdext.NewExtensionHost Generator, um Ihre Ereignishandler zu registrieren:

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

  3. Registrieren Sie den listen Befehl in Ihrem Stammbefehl:

    rootCmd.AddCommand(newListenCommand())

Wenn ein Benutzer azd provision oder azd up ausführt, ruft azd Ihre Erweiterung auf und ruft den preprovision-Handler auf, bevor Ressourcen bereitgestellt werden.

Ereignisse des Filterdienstes

Dienstereignishandler unterstützen optionale Filterung, sodass Sie nur bestimmte Diensttypen behandeln. Beispielsweise können Sie das prepackage Ereignis nur für Python Container-App-Dienste behandeln:

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

Neuerstellen und Testen

Nachdem Sie eine Funktion hinzugefügt haben, erstellen Sie die Erweiterung neu, und testen Sie das neue Verhalten:

  1. Wenn Sie den Watcher verwenden, werden Ihre Änderungen automatisch neu gebaut. Andernfalls erstellen Sie manuell:

    azd x build

  2. Testen Sie die Funktion. Bei Lebenszyklusereignissen führen Sie einen Befehl aus, der das Ereignis auslöst, z. B. azd provision.

Verwandte Inhalte

  • Last updated on