Aggiungere funzionalità di estensione

Le funzionalità definiscono le operazioni che un'estensione Azure Developer CLI (azd) può eseguire, dall'aggiunta di comandi personalizzati all'associazione al ciclo di vita della distribuzione. Questo articolo illustra come aggiungere funzionalità all'estensione di esempio Contoso Resource Tagger dalla guida introduttiva Creare un'estensione di esempio. È possibile applicare gli stessi modelli a qualsiasi estensione.

Ogni funzionalità richiede due elementi: una voce nella capabilities matrice del manifesto dell'estensione e l'implementazione corrispondente nel codice dell'estensione.

Annotazioni

azd le estensioni sono attualmente in versione beta.

Funzionalità disponibili

azd Le estensioni possono dichiarare le funzionalità seguenti:

custom-commands: aggiunge nuovi comandi e gruppi di comandi a azd nello spazio dei nomi dell'estensione. Ad esempio, l'estensione di esempio aggiunge azd tagger show. Usare questa funzionalità per esporre le attività eseguite dagli utenti direttamente dalla riga di comando.
lifecycle-events: sottoscrive gli eventi che azd generano durante l'esecuzione, ad esempio preprovision, postprovisiono postdeploy. L'estensione esegue la logica personalizzata in questi punti senza che l'utente lo chiami direttamente. Ad esempio, l'estensione di esempio verifica la presenza di tag obbligatori in preprovision prima della creazione di qualsiasi risorsa.
service-target-provider: registra una nuova destinazione di distribuzione in modo da azd sapere come creare un pacchetto e distribuire un servizio in un host che non supporta. Una destinazione di servizio viene associata al valore host in azure.yaml. Ad esempio, è possibile aggiungere un provider che distribuisce un servizio a una piattaforma di terze parti o a un ambiente di hosting interno.
framework-service-provider: registra il supporto per un linguaggio o un framework in modo da azd sapere come ripristinare, compilare e creare un pacchetto di quel tipo di progetto. Corrisponde al valore language in azure.yaml. Ad esempio, è possibile aggiungere il supporto per la compilazione per una lingua che azd non riconosce per impostazione predefinita.
provisioning-provider: sostituisce il modo in cui azd esegue il provisioning dell'infrastruttura durante azd provision e azd up. Anziché il flusso integrato di Bicep o di Terraform, l'estensione definisce cosa accade. Ad esempio, è possibile integrare uno strumento di infrastruttura come codice diverso o un'API di distribuzione personalizzata.
validation-provider: aggiunge controlli alla pipeline di convalida azd che vengono eseguiti su un progetto o un ambiente. Ad esempio, è possibile verificare che le convenzioni di denominazione, i tag obbligatori o le impostazioni di sicurezza siano applicate prima che una distribuzione proceda.
mcp-server: espone le funzionalità dell'estensione come strumenti MCP (Model Context Protocol) che gli agenti di intelligenza artificiale, ad esempio GitHub Copilot, possono individuare e chiamare. Ad esempio, l'estensione di esempio può esporre uno strumento suggest_tags. Per altre informazioni, vedere Aggiungere un server MCP a un'estensione.
metadata: fornisce metadati più ricchi per comandi e configurazione che azd usa per descrivere la tua estensione, ad esempio descrizioni dettagliate dei comandi e suggerimenti di configurazione visualizzati nell'output della guida e in IntelliSense.

Questo articolo è incentrato sulle due funzionalità più comuni: comandi personalizzati ed eventi del ciclo di vita. Per la mcp-server funzionalità, vedere Aggiungere un server MCP a un'estensione. Per informazioni dettagliate sulle funzionalità del provider, vedere le informazioni di riferimento sul framework di estensione.

Aggiungere comandi personalizzati

La funzionalità custom-commands consente alla tua estensione di registrare nuovi comandi all'interno di uno spazio dei nomi in azd. L'estensione di esempio usa già questa funzionalità per il azd tagger show comando .

Dichiarare la funzionalità in extension.yaml.
```
capabilities:
  - custom-commands
```
Compilare i comandi usando l'helper azdext.NewExtensionRootCommand , che registra i flag standard azd e la gestione delle variabili di ambiente in modo da non doverli dichiarare manualmente:
```
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
}
```
L'helper restituisce un oggetto *ExtensionContext che espone i valori risolti dei flag standard, ad esempio Environment e OutputFormat. Passate il contesto ai vostri sottocomandi e leggetelo all'interno dei rispettivi gestori RunE invece di ridefinire i flag standard.

La funzionalità consente all'estensione lifecycle-events di eseguire logica personalizzata durante gli eventi del ciclo di vita del progetto e del servizio, ad esempio preprovision o postdeploy. Per l'estensione di esempio, usare un preprovision evento per verificare che i tag richiesti siano impostati prima azd di effettuare il provisioning di qualsiasi risorsa.

Dichiarare la funzionalità in extension.yaml.

capabilities:
  - custom-commands
  - lifecycle-events

Aggiungi il comando listen alla tua estensione. azd richiama questo comando per stabilire la connessione bidirezionale usata per gli eventi. Usa il builder azdext.NewExtensionHost per registrare i gestori di eventi:

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

Registra il comando listen sul comando radice:
```
rootCmd.AddCommand(newListenCommand())
```

Quando un utente esegue azd provision o azd up, azd invoca l'estensione e chiama il gestore preprovision prima di eseguire il provisioning delle risorse.

Filtrare gli eventi del servizio

I gestori eventi del servizio supportano il filtro facoltativo in modo da gestire solo tipi di servizio specifici. Ad esempio, è possibile gestire l'evento prepackage solo per i servizi di app contenitore Python:

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

Ricompilare e testare

Dopo aver aggiunto una funzionalità, ricompilare l'estensione e testare il nuovo comportamento:

Se usi il watcher, le modifiche vengono ricompilate automaticamente. In caso contrario, compilare manualmente:
```
azd x build
```
Testare la funzionalità. Per gli eventi del ciclo di vita, eseguire un comando che attiva l'evento, ad esempio azd provision.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-07-30