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 dit om platformartefacten te maken voor publicatie van release en register, of maak een zelfstandige .zip bundel wanneer u een extensie moet delen zonder een register te hosten. 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.
• 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 distribueert extensies via extensiebronnen. Extensiebronnen zijn op URL's of op bestanden gebaseerde manifesten waarin beschikbare extensies en hun artefacten worden beschreven. azd ondersteunt ook draagbare bundelbestanden voor directe installatie 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 ontwikkelings - en nachtregisters zijn opt-in bronnen voor werk in uitvoering en automatisch ingebouwde extensies van eerste partijen. 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