Základy vývoje rozšíření

Azure Developer CLI (azd) rozšíření přidávají nové příkazy, automatizují pracovní postupy a integrují další služby do azd. Tento článek vysvětluje koncepty, které potřebujete pochopit před vytvořením rozšíření, jako jsou nástroje pro vývojáře, sada SDK (Software Development Kit) a způsob azd komunikace se spuštěným rozšířením. Informace o rozšířeních z pohledu uživatele najdete v přehledu rozšíření.

Rozšíření pro vývojáře

Nejrychlejší způsob, jak vytvářet rozšíření, je použít azd vývojářské rozšíření (microsoft.azd.extensions). Rozšíření pro vývojáře přidává sadu příkazů pod obor názvů azd x, které vytvářejí kostru, sestavují, balí a publikují vaše rozšíření:

Command	Description
azd x init	Vygeneruje nový projekt rozšíření v jazyce, který si zvolíte.
azd x build	Vytvoří binární soubor rozšíření pro lokální vývoj.
azd x watch	Sleduje změny projektu a automaticky znovu sestaví a nainstaluje rozšíření.
azd x pack	Zabalí artefakty rozšíření pro přípravu na publikování.
azd x release	Vytvoří vydání rozšíření na GitHubu.
azd x publish	Aktualizuje registr rozšíření pomocí nových metadat rozšíření.

Rychlý úvod k vytvoření ukázkového rozšíření ukazuje, jak nainstalovat vývojářské rozšíření a vygenerovat kostru svého prvního rozšíření.

Rozšíření pro vývojáře podporuje pracovní postupy publikování založené na registru a distribuci přenosných sad. Pomocí azd x pack vytvoříte artefakty platformy pro vydání a publikování v registru, nebo vytvořte samostatný balíček .zip, pokud potřebujete sdílet rozšíření bez nutnosti hostovat registr. Balíčky je možné nainstalovat z místního souboru nebo vzdáleně hostovat na adrese URL HTTPS. Podrobné pokyny najdete v tématu Publikování rozšíření.

Architektura rozšíření a gRPC

azd a rozšíření běží jako samostatné procesy, které komunikují pomocí gRPC. Při vyvolání příkazu rozšíření dojde k následujícím krokům:

1. azd spustí server gRPC na náhodném portu a nastaví AZD_SERVER proměnnou prostředí s adresou serveru.
2. azd nastaví proměnnou AZD_ACCESS_TOKEN prostředí, což je podepsaný webový token JSON (JWT), který uděluje rozšíření přístup ke azd službám po celou dobu platnosti příkazu.
3. azd vyvolá příkaz rozšíření a předá aktuální argumenty, příznaky a proměnné prostředí.
4. Vaše rozšíření používá klienta gRPC ke komunikaci s azd prostřednictvím služeb frameworku, například k vyzvání uživatele nebo ke čtení konfigurace projektu.
5. azd čeká na dokončení příkazu a hlásí nenulový ukončovací kód jako chybu.

Tento model umožňuje, aby rozšíření komunikovali azd konzistentním a zabezpečeným způsobem bez přímého přístupu k internímu azd stavu.

požadavky na rozšíření na úrovni projektu

Projekty mohou deklarovat rozšíření, která vyžadují v azure.yaml. V tomto oddílu requiredVersions.extensions můžete zobrazit seznam ID rozšíření a omezení verzí, abyste azd mohli vyřešit verze, které vyhovují projektu.

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

Deklarujte požadovaná rozšíření, pokud projekt závisí na hostitelích, poskytovatelích, obslužných rutinách životního cyklu, ověřování nebo příkazech poskytovaných rozšířením. Přesné schéma a podporovanou syntaxi verzí viz requiredVersions.

Sada azdext SDK

Balíček azdext je sada Go SDK pro architekturu rozšíření. Poskytuje klienta gRPC a pomocné rutiny, které za vás zpracovávají podrobnosti komunikace, abyste se mohli zaměřit na logiku rozšíření. SDK obsahuje pomocné funkce pro:

• Vytvořte kořenový příkaz, který zaregistruje standardní azd příznaky a zpracování proměnných prostředí.
• azd Připojte přístupový token k odchozím požadavkům.
• Volejte azd služby frameworku, jako jsou služby Project, Environment, Account a Prompt.
• Nahlašujte pojmenované události používání prostřednictvím rozhraní gRPC API TelemetryService.ReportUsage pro rozšíření z oficiálních zdrojů. Podrobnosti o využití rozhraní API najdete v tématu Komunikace s azd pomocí sady SDK.
• Zaregistrujte obslužné rutiny pro události životního cyklu a vlastní poskytovatele prostřednictvím hostitelského prostředí rozšíření.

Informace o tom, jak volat azd služby z vašeho rozšíření, najdete v tématu Komunikace s azd pomocí sady SDK.

Možnosti rozšíření

Možnosti deklarují, co rozšíření může dělat. Vypište možnosti rozšíření v extension.yaml manifestu a azd udělte odpovídající oprávnění za běhu. Mezi dostupné funkce patří:

• custom-commands: Přidání nových skupin příkazů a příkazů do azd.
• lifecycle-events: Přihlaste se k odběru událostí životního cyklu projektu a služeb, například preprovision a postdeploy.
• mcp-server: Zadejte nástroje MCP (Model Context Protocol) pro agenty AI.
• service-target-provider: Zadejte vlastní cíle nasazení služby.
• framework-service-provider: Poskytování podpory sestavení vlastního jazyka a architektury.
• provisioning-provider: Poskytnout vlastní prostředí pro nasazování infrastruktury.
• validation-provider: Přispívání ověřovacích kontrol do ověřovacího azd kanálu.
• metadata: Poskytuje bohaté metadata příkazů a konfigurace pro výstup nápovědy a IntelliSense.

Další informace o tom, jak do rozšíření přidat možnosti, najdete v tématu Přidání možností rozšíření.

Podporované jazyky

Rozšíření můžete vytvářet azd v libovolném jazyce, který podporuje gRPC, a azd x init obsahuje úvodní šablony pro několik jazyků. Go má nejkomplexnější podporu, včetně plnohodnotných azdext pomocných nástrojů sady SDK, proto všechny příklady v článcích v této části používají jazyk Go.

Jazyk	Úroveň podpory
Go	Špičková podpora a prvotřídní pomocné nástroje SDK.
.NET (C#)	Silná integrace s úvodní šablonou
Python	Dobrá integrace s úvodní šablonou.
JavaScript	Základní integrace s úvodní šablonou

U rozšíření vytvořených v jiných jazycích než Go můžete vygenerovat klienty gRPC ze souborů proto v azure/azure-dev úložišti. Aktuální stav podpory jazyka najdete v dokumentaci k upstreamové platformě rozšíření.

Registr rozšíření

Rozšíření distribuujete prostřednictvím zdrojů registru nebo sad rozšíření. Zdroje registru jsou manifesty založené na adrese URL nebo souborové, které popisují dostupná rozšíření a jejich artefakty. Balíčky rozšíření jsou přenosné .zip balíčky, které můžete nainstalovat přímo z místního souboru nebo je hostovat vzdáleně na adrese URL HTTPS, pokud nechcete hostovat registr.

• Oficiální registr je předem nakonfigurován v azd a hostuje prověřená rozšíření od prvních stran. Oficiální rozšíření se vyvíjejí ve forku úložiště azure/azure-dev.
• Zdroje založené na adrese URL umožňují instalaci ze vzdálených veřejných nebo privátních manifestů registru.
• Zdroje založené na souborech umožňují instalovat z manifestů místního registru pro scénáře vývoje, testování nebo offline.
• Vývojový a nightly registry jsou volitelné zdroje pro rozpracovaná a automaticky sestavovaná oficiální rozšíření. Rozšíření v registru pro vývoj jsou nepodepsaná, nejsou pokryta podpora Azure a je možné je změnit nebo odebrat bez předchozího upozornění.

Informace o publikování rozšíření do registru najdete v tématu Publikování rozšíření.

Související obsah

• Vytvoření ukázkového rozšíření
• Definování manifestu rozšíření
• Přidání možností rozšíření