Panoramica delle estensioni dell'interfaccia della riga di comando per sviluppatori di Azure

Le estensioni dell'interfaccia della riga di comando per sviluppatori di Azure (azd) sono componenti modulari che estendono la funzionalità dell'interfaccia della riga di comando per sviluppatori di Azure. Consentono di aggiungere nuove funzionalità, automatizzare i flussi di lavoro e di integrarsi con altri servizi direttamente dall'interfaccia della riga di comando. Usare le estensioni per adattarsi azd alle esigenze del team in continua evoluzione e agli scenari di Azure.

Gestire le origini delle estensioni

È possibile individuare, installare e aggiornare le estensioni man mano che aumentano i requisiti. Le fonti delle estensioni gestiscono la distribuzione e la gestione.

• Le origini di estensione sono manifesti basati su file o URL che forniscono elenchi di estensioni disponibili azd .
• È possibile aggiungere origini di estensione personalizzate che si connettono a registri privati, locali o pubblici.
• Le origini di estensione sono un concetto equivalente ai feed NuGet o Node Gestione pacchetti (NPM) e devono rispettare lo schema ufficiale del Registro di sistema delle estensioni.

azd supporta diversi modi per risolvere le estensioni:

• Il Registro di sistema di origine dell'estensione ufficiale è preconfigurato in azd ed è ospitato in https://aka.ms/azd/extensions/registry.
• Le fonti basate su URL fanno riferimento ai manifest dei registry remoti ospitati dal tuo team per la distribuzione pubblica o privata.
• Le sorgenti basate su file fanno riferimento ai manifest dei registri locali per l'uso offline o per lo sviluppo locale.
• I registri di sviluppo e nightly sono fonti opzionali per estensioni proprietarie in fase di sviluppo e compilate automaticamente. Usarli per gli scenari di test anziché per i flussi di lavoro di produzione.
• I file bundle indipendenti forniscono pacchetti portabili .zip per l'installazione diretta da un file locale o da un URL HTTPS quando non si vuole ospitare un registro.

azd impone una rigorosa convalida dei nomi di origine delle estensioni personalizzate. I nomi devono contenere da 1 a 64 lettere ASCII minuscole o cifre. È possibile includere trattini () e caratteri di sottolineatura (-_) tra lettere o cifre. I nomi devono iniziare e terminare con una lettera o una cifra. azd restituisce un errore per i nomi non validi; non li normalizza. I nomi azd e bundle sono riservati e non possono essere usati per le origini personalizzate. Il nome di origine deve essere valido quando viene usato con --source.

L'origine preconfigurata azd è il registro ufficiale. Non è possibile rimuoverlo o modificarne la posizione.

Per acconsentire esplicitamente al Registro di sistema di sviluppo, eseguire il comando seguente:

# Add a new extension source name 'dev' to your `azd` configuration.
azd extension source add -n dev -t url -l "https://aka.ms/azd/extensions/registry/dev"

Comandi sorgente dell'estensione

Usare i seguenti comandi per gestire le sorgenti delle estensioni per l'installazione di azd.

Elencare le origini delle estensioni installate

azd extension source list

Aggiungere una nuova origine di estensione

azd extension source add -n <name> -t url -l <registry-url>

• -l, --location: luogo dell'origine dell'estensione.
• -n, --name: nome dell'origine dell'estensione. Usare un nome di origine personalizzato valido.
• -t, --type: tipo di origine dell'estensione. I tipi supportati sono file e URL.

Rimuovere una sorgente dell'estensione

azd extension source remove <name>

Non è possibile rimuovere l'origine preconfigurata azd .

Se un aggiornamento segnala un errore di caricamento di origine causato da un nome di origine non valido legacy in ~/.azd/config.json, rimuovere l'origine che causa l'errore con azd extension source remove, quindi aggiungerlo di nuovo con un nome valido.

Gestire le estensioni

Dopo aver abilitato le estensioni e configurato le origini di estensione, installare le estensioni per aggiungere nuove funzionalità a azd. Per un esempio di uso delle estensioni, vedere Avvio rapido: usare l'estensione di intelligenza artificiale.

Elencare le estensioni

azd extension list [flags]

• --installed Visualizza un elenco di estensioni installate.
• --source Elenca solo le estensioni dall'origine specificata. Il nome dell'origine deve essere un nome di origine registrato valido.
• --tags Filtra le estensioni in base ai tag, ad esempio intelligenza artificiale o test.

Installare un'estensione

azd extension install <extension-names> [flags]

Sostituire <extension-name> con il nome dell'estensione da installare.

• -v, --version Specifica la versione esatta da installare. Questa opzione non accetta intervalli di versioni o vincoli e non può essere usata durante l'installazione di un bundle autonomo (.zip percorso file o URL).
• -s, --source Specifica la sorgente dell'estensione utilizzata per le installazioni. Il nome dell'origine deve essere un nome di origine registrato valido.

Per installare un bundle autonomo da un URL HTTPS, specificare il percorso del bundle come nome dell'estensione:

azd extension install https://example.com/extensions/example.zip

• --all Aggiorna tutte le estensioni installate in precedenza quando specificato.
• -v, --version Aggiorna un'estensione specificata alla versione esatta, se specificata. Questa opzione non accetta intervalli di versioni o vincoli.
• -s, --source Specifica la sorgente dell'estensione utilizzata per le installazioni. Il nome dell'origine deve essere un nome di origine registrato valido.
• --no-dependency-updates Impedisce gli aggiornamenti alle dipendenze quando specificato.

Disinstallare un'estensione

azd extension uninstall <extension-name>

• --all Rimuove tutte le estensioni installate quando specificato.

Dichiarare le estensioni necessarie in un progetto

I progetti possono dichiarare le estensioni necessarie in azure.yaml in modo da azd poter risolvere e installare le versioni dell'estensione necessarie per il progetto. Aggiungere i requisiti di estensione in requiredVersions.extensionse usare latest, una versione esatta o un vincolo di versione semantica supportato.

requiredVersions:
  extensions:
    azure.ai.agents: "latest"
    contoso.azd.tagger: "^2.0.0"

Utilizzare i requisiti a livello di progetto quando un modello dipende da host di servizio forniti dall'estensione, gestori del ciclo di vita, provider di validazione o comandi. Per informazioni dettagliate sullo schema completo e sul vincolo di versione, vedere requiredVersions.

Comprendere i punti di integrazione delle estensioni

Le estensioni possono essere integrate con azd in diversi modi:

• Aggiungere namespace dei comandi con metadati, informazioni della Guida ed esempi.
• Fornire schemi di configurazione e metadati IntelliSense per i file di progetto.
• Registra i gestori di eventi del ciclo di vita per processi quali provisioning, creazione del pacchetto e distribuzione.
• Aggiungere provider per il provisioning personalizzato, la convalida, le destinazioni di servizio e il supporto del linguaggio o del framework.
• Esporre le funzionalità del server MCP (Model Context Protocol) per gli agenti e gli strumenti di sviluppo.

Per indicazioni sull'implementazione, vedere Concetti relativi allo sviluppo di estensioni.

Usare estensioni azd nei contenitori di sviluppo

La azd funzionalità Contenitore di sviluppo supporta un'opzione extensions per installare automaticamente un elenco delimitato da virgole di azd estensioni durante la compilazione del contenitore. Le estensioni installate in questo modo sono disponibili non appena il contenitore viene avviato, riducendo la configurazione manuale e abilitando azd l'esecuzione dei comandi con le estensioni necessarie già installate.

Per installare automaticamente le estensioni, aggiungere l'opzione extensions alla voce di azd funzionalità nel devcontainer.json file:

{
    "name": "Azure Developer CLI",
    "image": "mcr.microsoft.com/devcontainers/python:3.10-bullseye",
    "features": {
        "ghcr.io/azure/azure-dev/azd:latest": {
            "extensions": "my-ext-1,my-ext-2"
        }
    }
}

Il extensions valore è un elenco delimitato da virgole di nomi di azd estensione. L'installazione viene eseguita durante la compilazione del contenitore, quindi le estensioni sono pronte per l'uso non appena viene avviato il contenitore. Dopo aver modificato l'elenco delle estensioni, usare il comando Rebuild and Reopen in Dev Container in Visual Studio Code per ricompilare il contenitore con le estensioni aggiornate.

Altre informazioni sulla funzionalità azd Dev Container.

Passaggi successivi

• Avvio rapido: Usare l'estensione di intelligenza artificiale
• Concetti relativi allo sviluppo di estensioni
• Guida introduttiva: Creare un'estensione azd di esempio
• Readme del framework di estensione