Concetti relativi allo sviluppo di estensioni

Azure Developer CLI (azd) estensioni aggiungono nuovi comandi, automatizzano i flussi di lavoro e integrano altri servizi con azd. Questo articolo illustra i concetti che è necessario comprendere prima di creare un'estensione, ad esempio gli strumenti per sviluppatori, il software development kit (SDK) e le modalità azd di comunicazione con un'estensione in esecuzione. Per informazioni sulle estensioni dal punto di vista dell'utente, vedere la panoramica delle estensioni.

Estensione per sviluppatori

Il modo più rapido per compilare le estensioni consiste nell'usare l'estensione azd per sviluppatori (microsoft.azd.extensions). L'estensione per sviluppatori aggiunge una serie di comandi nel namespace azd x per creare la struttura, compilare, creare il pacchetto e pubblicare l'estensione:

La guida introduttiva Creare un'estensione di esempio illustra come installare l'estensione per sviluppatori e creare la struttura della tua prima estensione.

L'estensione per sviluppatori supporta i flussi di lavoro di pubblicazione basati sul Registro di sistema e la distribuzione di bundle portabile. Usa azd x pack per creare artefatti di piattaforma per la pubblicazione di release e nel registry, oppure crea un bundle .zip autonomo quando devi condividere un'estensione senza ospitare un registry. I bundle possono essere installati da un file locale o ospitati in remoto in un URL HTTPS. Per istruzioni dettagliate, vedere Pubblicare un'estensione.

Il framework di estensione e gRPC

azd e le estensioni vengono eseguite come processi separati che comunicano tramite gRPC. Quando si richiama un comando di estensione, vengono eseguiti i passaggi seguenti:

1. azd avvia un server gRPC su una porta casuale e imposta la AZD_SERVER variabile di ambiente con l'indirizzo del server.
2. azd imposta la AZD_ACCESS_TOKEN variabile di ambiente, ovvero un token JSON Web (JWT) firmato che concede all'estensione l'accesso ai azd servizi per la durata del comando.
3. azd richiama il comando di estensione e passa gli argomenti, i flag e le variabili di ambiente correnti.
4. L'estensione usa un client gRPC per comunicare con azd tramite i servizi del framework, ad esempio per richiedere input all'utente o leggere la configurazione del progetto.
5. azd attende il completamento del comando e segnala un codice di uscita diverso da zero come errore.

Questo modello consente alle estensioni di interagire azd in modo coerente e sicuro senza accedere direttamente allo stato interno azd .

requisiti di estensione a livello di progetto

I progetti possono dichiarare le estensioni necessarie in azure.yaml. Usa la sezione requiredVersions.extensions per elencare gli ID delle estensioni e i vincoli di versione, in modo che azd possa determinare le versioni compatibili con il progetto.

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

Dichiarare le estensioni necessarie quando un progetto dipende da host, provider, gestori del ciclo di vita, convalida o comandi forniti dall'estensione. Per lo schema esatto e la sintassi della versione supportata, vedere requiredVersions.

The azdext SDK

Il pacchetto azdext è l'SDK Go per il framework delle estensioni. Fornisce un client e helper gRPC che gestiscono automaticamente i dettagli della comunicazione, in modo da poter concentrarsi sulla logica dell'estensione. L’SDK include strumenti di supporto per:

• Creare un comando radice che registra i flag standard azd e la gestione delle variabili di ambiente.
• Collegare il azd token di accesso alle richieste in uscita.
• Richiama azd i servizi del framework, come Project, Environment, Account e Prompt.
• Segnalare gli eventi di utilizzo denominati tramite l'API TelemetryService.ReportUsage gRPC per le estensioni di origine ufficiale. Per informazioni dettagliate sull'utilizzo dell'API, vedere Comunicare con azd usando l'SDK.
• Registra i gestori degli eventi del ciclo di vita e i provider personalizzati tramite un host delle estensioni.

Per informazioni su come chiamare azd i servizi dall'estensione, vedere Comunicare con azd usando l'SDK.

Funzionalità di estensione

Le funzionalità dichiarano le operazioni che un'estensione può eseguire. Elencare le funzionalità di un'estensione nel manifesto extension.yaml e azd concede le autorizzazioni corrispondenti in fase di esecuzione. Le funzionalità disponibili includono:

• custom-commands: aggiungere nuovi gruppi di comandi e comandi a azd.
• lifecycle-events: Sottoscriversi agli eventi del ciclo di vita del progetto e del servizio, ad esempio preprovision e postdeploy.
• mcp-server: fornisce strumenti MCP (Model Context Protocol) per gli agenti di intelligenza artificiale.
• service-target-provider: specificare destinazioni di distribuzione del servizio personalizzate.
• framework-service-provider: fornisce supporto per la compilazione del linguaggio e del framework personalizzato.
• provisioning-provider: Fornisci un'esperienza personalizzata per il provisioning dell'infrastruttura.
• validation-provider: Aggiungere controlli di convalida alla pipeline di convalida azd.
• metadata: specificare metadati avanzati di comando e configurazione per l'output della Guida e IntelliSense.

Per informazioni su come aggiungere funzionalità a un'estensione, vedere Aggiungere funzionalità di estensione.

Lingue disponibili

È possibile compilare azd estensioni in qualsiasi linguaggio che supporta gRPC e azd x init include modelli di base per diverse lingue. Go offre il supporto più completo, inclusi gli helper SDK di prima classe azdext , quindi gli articoli di questa sezione usano Go per tutti gli esempi.

Per le estensioni create in linguaggi diversi da Go, è possibile generare client gRPC dai file proto nel azure/azure-dev repository. Per lo stato attuale del supporto linguistico, consultare la documentazione originale del framework di estensione.

Registri delle estensioni

Le estensioni vengono distribuite tramite registri o bundle di estensioni. Le origini del Registro di sistema sono manifesti basati su URL o basati su file che descrivono le estensioni disponibili e i relativi artefatti. I bundle di estensioni sono pacchetti portabili .zip che è possibile installare direttamente da un file locale o da un host in remoto in un URL HTTPS quando non si vuole ospitare un registro.

• Il registro ufficiale è preconfigurato in azd e ospita estensioni di prima parte controllate. Le estensioni ufficiali vengono sviluppate in un fork del repository azure/azure-dev .
• Le origini basate su URL consentono di eseguire l'installazione da manifesti del Registro di sistema pubblici o privati remoti.
• Le origini basate su file consentono di eseguire l'installazione da manifesti del Registro di sistema locali per scenari di sviluppo, test o offline.
• I registri di sviluppo e nightly sono origini facoltative per estensioni di prima parte in fase di sviluppo e generate automaticamente. Le estensioni nel Registro di sistema di sviluppo non sono firmate, non coperte da supporto tecnico di Azure e possono essere modificate o rimosse senza preavviso.

Per informazioni su come pubblicare un'estensione in un Registro di sistema, vedere Pubblicare un'estensione.

Contenuti correlati

• Creare un'estensione di esempio
• Definire il manifesto dell'estensione
• Aggiungere funzionalità di estensione