Concepten voor uitbreidingsontwikkeling

Azure Developer CLI-extensies nieuweazd opdrachten toevoegen, werkstromen automatiseren en andere services integreren met azd. In dit artikel worden de concepten uitgelegd die u moet begrijpen voordat u een extensie bouwt, zoals de hulpprogramma's voor ontwikkelaars, de SDK (Software Development Kit) en hoe azd u communiceert met een actieve extensie. Zie het overzicht van extensies voor meer informatie over extensies vanuit het perspectief van een gebruiker.

De extensie voor ontwikkelaars

De snelste manier om extensies te bouwen, is door de azd ontwikkelaarsextensie (microsoft.azd.extensions) te gebruiken. Met de extensie voor ontwikkelaars wordt een reeks opdrachten toegevoegd onder de azd x naamruimte die uw extensie opstelt, bouwt, verpakt en publiceert:

In de quickstart Een voorbeeldextensie bouwen ziet u hoe u de extensie voor ontwikkelaars installeert en de basisstructuur voor uw eerste extensie opzet.

De ontwikkelaarsextensie biedt ondersteuning voor publicatiewerkstromen op basis van registers en distributie van draagbare bundels. Gebruik azd x pack om platformartefacten te maken voor publicatie van releases en in registers, of maak een zelfstandige .zip-bundel als u een extensie wilt delen zonder zelf een register te hosten. Bundels kunnen worden geïnstalleerd vanuit een lokaal bestand of extern worden gehost op een HTTPS-URL. Zie Een extensie publiceren voor stapsgewijze instructies.

Het extensieframework en gRPC

azd en extensies worden uitgevoerd als afzonderlijke processen die communiceren via gRPC. Wanneer u een extensieopdracht aanroept, worden de volgende stappen uitgevoerd:

1. azd start een gRPC-server op een willekeurige poort en stelt de AZD_SERVER omgevingsvariabele in met het serveradres.
2. azd stelt de AZD_ACCESS_TOKEN omgevingsvariabele in. Dit is een ondertekend JSON-webtoken (JWT) dat de extensie toegang verleent tot azd services voor de levensduur van de opdracht.
3. azd roept de extensieopdracht aan en geeft de huidige argumenten, vlaggen en omgevingsvariabelen door.
4. Uw extensie gebruikt een gRPC-client om via de frameworkservices terug te communiceren met azd, bijvoorbeeld door de gebruiker om invoer te vragen of de projectconfiguratie te lezen.
5. azd wacht totdat de opdracht is voltooid en rapporteert een niet-nul afsluitcode als een fout.

Met dit model kunnen extensies op een consistente, veilige manier communiceren azd zonder rechtstreeks toegang te krijgen tot de interne azd status.

uitbreidingsvereisten op Project niveau

Projecten kunnen de extensies declareren die ze nodig hebben.azure.yaml Gebruik de requiredVersions.extensions sectie om extensie-id's en versiebeperkingen weer te geven, zodat azd u de versies kunt oplossen die voldoen aan het project.

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

Declareer vereiste extensies wanneer een project afhankelijk is van door extensies geleverde hosts, providers, levenscyclushandlers, validatie of opdrachten. Zie voor de exacte schema- en ondersteunde versiesyntaxis requiredVersions.

De azdext SDK

Het azdext pakket is de Go SDK voor het extensieframework. Het biedt een gRPC-client en helpers die de communicatiedetails voor u afhandelen, zodat u zich kunt richten op uw extensielogica. De SDK bevat helpers voor:

• Bouw een hoofdopdracht waarmee de standaardvlagmen azd en de verwerking van omgevingsvariabelen worden geregistreerd.
• Koppel het azd toegangstoken aan uitgaande aanvragen.
• Roep azd frameworkservices aan, zoals de Project-, Environment-, Account- en Prompt-services.
• Rapporteer benoemde gebruiksgebeurtenissen via de TelemetryService.ReportUsage gRPC-API voor officiële bronextensies. Zie Communiceren met azd met behulp van de SDK voor api-gebruiksgegevens.
• Registreer levenscyclus-eventhandlers en aangepaste providers via een extensiehost.

Zie azd voor meer informatie over het aanroepen van services vanuit uw extensie.

Uitbreidingsmogelijkheden

Mogelijkheden declareren wat een extensie kan doen. Vermeld de mogelijkheden van een extensie in het extension.yaml manifest en azd verleent de bijbehorende machtigingen tijdens runtime. De beschikbare mogelijkheden zijn onder andere:

• custom-commands: Nieuwe opdrachtgroepen en opdrachten toevoegen aan azd.
• lifecycle-events: Abonneren op project- en servicelevenscyclus-gebeurtenissen, zoals preprovision en postdeploy.
• mcp-server: Geef MCP-hulpprogramma's (Model Context Protocol) op voor AI-agents.
• service-target-provider: Geef aangepaste serviceimplementatiedoelen op.
• framework-service-provider: Bied ondersteuning voor aangepaste taal- en framework-build.
• provisioning-provider: Bied een aangepaste ervaring voor het inrichten van infrastructuur.
• validation-provider: Voeg validatiecontroles toe aan de azd validatiepijplijn.
• metadata: Geef uitgebreide opdracht- en configuratiemetagegevens op voor help-uitvoer en IntelliSense.

Zie Uitbreidingsmogelijkheden toevoegen voor meer informatie over het toevoegen van mogelijkheden aan een extensie.

Ondersteunde talen

U kunt extensies bouwen azd in elke taal die gRPC ondersteunt en azd x init starterssjablonen voor verschillende talen bevat. Go biedt de meest volledige ondersteuning, inclusief eersteklas SDK-helpers azdext , dus in de artikelen in deze sectie wordt Go gebruikt voor alle voorbeelden.

Voor extensies die zijn geschreven in andere talen dan Go, kunt u gRPC-clients genereren op basis van de proto-bestanden in de azure/azure-dev opslagplaats. Zie de documentatie van het upstream-extensieframework voor de huidige status van taalondersteuning.

Extensieregisters

U verspreidt extensies via bronnen in het register of extensiebundels. Registerbronnen zijn op URL's of op bestanden gebaseerde manifesten waarin beschikbare extensies en hun artefacten worden beschreven. Extensiebundels zijn draagbare .zip pakketten die u rechtstreeks vanuit een lokaal bestand of host op afstand kunt installeren via een HTTPS-URL wanneer u geen register wilt hosten.

• Het officiële register is vooraf geconfigureerd in azd en bevat geverifieerde extensies van de eerste partij. Officiële extensies worden ontwikkeld in een fork van de azure/azure-dev-repository.
• Met op URL's gebaseerde bronnen kunt u installeren vanuit externe openbare of persoonlijke registermanifesten.
• Met bronnen op basis van bestanden kunt u installeren vanuit lokale registermanifesten voor ontwikkelings-, test- of offlinescenario's.
• De ontwikkelingsregisters en nightly-registers zijn opt-inbronnen voor werk in uitvoering en automatisch gebouwde eigen extensies. Extensies in het ontwikkelaarsregister zijn niet ondertekend, niet gedekt door ondersteuning voor Azure en kunnen zonder kennisgeving worden gewijzigd of verwijderd.

Zie Een extensie publiceren voor meer informatie over het publiceren van een extensie naar een register.

Verwante onderwerpen

• Een voorbeeldextensie maken
• Het extensiemanifest definiëren
• Uitbreidingsmogelijkheden toevoegen