A bővítményjegyzék definiálása

Minden Azure fejlesztői parancssori felület (azd) bővítmény tartalmaz egy jegyzékfájltextension.yaml, amely leírja a metaadatokat és a képességeket. azd A bővítményregisztrációs adatbázisban található metaadatok segítségével a felhasználók felfedezhetik, telepíthetik és megérthetik a bővítményt. Ez a cikk a Contoso Resource Tagger mintabővítménnyel kapcsolatos jegyzéktulajdonságokat ismerteti a Mintabővítmény létrehozása rövid útmutatóból. Ugyanezeket a fogalmakat bármely bővítményre alkalmazhatja.

Megjegyzés:

azd bővítmények jelenleg bétaverzióban érhetők el.

Jegyzéktulajdonságok

A extension.yaml jegyzék a következő tulajdonságokat támogatja.

Kötelező tulajdonságok

Minden jegyzéknek tartalmaznia kell a következő tulajdonságokat:

Property Description
id A bővítmény egyedi azonosítója, például contoso.azd.tagger.
version Szemantikai verzió MAJOR.MINOR.PATCH formátumban.
displayName A bővítmény ember által olvasható neve.
description A bővítmény részletes leírása.

Minden manifesztumnak tartalmaznia kell a capabilities vagy a dependencies egyikét. A parancsokat vagy szolgáltatókat biztosító bővítmény deklarálja a(z) capabilities elemet. Ehelyett egy bővítménycsomag deklarál dependencies .

Választható tulajdonságok

A jegyzék a következő választható tulajdonságokat is támogatja:

Property Description
namespace Parancsnévtér, amely csoportosítja a bővítmény parancsát, például tagger.
entryPoint Végrehajtható fájl vagy parancsfájl, amely belépési pontként szolgál.
language Programozási nyelv, amelybe a bővítmény be van írva, például go.
capabilities Bővítési képességek tömbje.
usage Útmutató a bővítmény használatához.
examples Használati példák tömbje névvel, leírással és használati móddal.
tags Kategorizálási és szűrési kulcsszavak.
dependencies Egyéb bővítmények, amelyektől ez a bővítmény függ.
providers A bővítményregisztrálást végző szolgáltatók listája.
platforms Platformspecifikus metaadatok.
mcp Modellkörnyezeti protokoll kiszolgálókonfigurációja.
requiredAzdVersion Szemantikai verziókorlátozás a azd bővítmény használatához szükséges verzióra, például >= 1.24.0.

Példamanifeszt

Az alábbi példa a Contoso Resource Tagger mintabővítmény extension.yaml jegyzékét mutatja be:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/cli/azd/extensions/extension.schema.json

id: contoso.azd.tagger
namespace: tagger
displayName: Contoso Resource Tagger
description: Standardize and report Azure resource tags for an azd project.
usage: azd tagger <command> [options]
version: 0.1.0
language: go
capabilities:
  - custom-commands

examples:
  - name: show
    description: Displays a greeting from the extension.
    usage: azd tagger show

tags:
  - tags
  - governance
  - example

A $schema fájl tetején található megjegyzés lehetővé teszi az ellenőrzés és az IntelliSense használatát a YAML nyelvi kiszolgálót támogató szerkesztőkben.

Képességek deklarálása

A capabilities tömb deklarálja, hogy mire képes a bővítmény. azd futásidőben adja meg a megfelelő engedélyeket, és egyes keretrendszerszolgáltatások engedélyhiba miatt meghiúsulnak, ha a megfelelő képesség nincs deklarálva. A mintabővítmény kezdetben csak custom-commands tartalmaz.

capabilities:
  - custom-commands

A többi cikkben szereplő funkciók hozzáadásakor további képességeket adhat hozzá. A bővítmény képességeinek hozzáadása például hozzáadja a bővítményeketlifecycle-events, és hozzáad egy MCP-kiszolgálót egy bővítményhezmcp-server. Az elérhető képességek a következők:

  • custom-commands: Adjon hozzá új parancsokat azd a névtérhez, például azd tagger show.
  • lifecycle-events: Futtasson egyéni logikát, amikor a(z) azd olyan eseményeket vált ki, mint a(z) preprovision vagy a(z) postdeploy.
  • mcp-server: Az AI-ügynökök által meghívható modellkörnyezeti protokoll eszközeinek felfedése.
  • service-target-provider: Adjon hozzá egy egyéni üzembehelyezési célértéket egy host olyanhoz, amely azd alapértelmezés szerint nem támogatott.
  • framework-service-provider: Build- és csomagtámogatás hozzáadása egy language számára, amelyet a azd alapértelmezetten nem ismer fel.
  • provisioning-provider: Cserélje le az azd infrastruktúra kiépítésének módját egy egyéni implementációra.
  • validation-provider: Adjon hozzá az érvényesítési folyamatban futó azd ellenőrzéseket.
  • metadata: Adjon meg részletesebb parancs- és konfigurációs metaadatokat a súgó kimenetéhez és az IntelliSense-hez.

Az egyes képességek példákkal való teljesebb magyarázatáért lásd: Bővítményfunkciók hozzáadása.

Használati példák hozzáadása

A examples tömb a bővítmény használatának gyakori módjait ismerteti. azd ezeket a példákat jeleníti meg, amikor a felhasználók megtekintik a bővítmény részleteit:

examples:
  - name: show
    description: Displays a greeting from the extension.
    usage: azd tagger show

Szolgáltatók regisztrálása

Ha a bővítmény egyéni szolgáltatási célokat vagy keretrendszerszolgáltatásokat biztosít, deklarálja őket a providers szakaszban, hogy azd tudja, mit kínál a bővítmény:

providers:
  - name: tagger
    type: service-target
    description: Deploys tagged resources to Azure.

Platformspecifikus konfiguráció hozzáadása

platforms A tulajdonság használatával platformspecifikus metaadatokat adhat meg, például az egyes operációs rendszerek végrehajtható nevét.

platforms:
  windows:
    executable: tagger.exe
  linux:
    executable: tagger
  darwin:
    executable: tagger

Függőségek deklarálása

A bővítmények a dependencies tömb használatával más bővítményektől is függhetnek. A függőségek támogatják a szemantikai verziószámozási korlátozásokat:

dependencies:
  - id: microsoft.azd.core
    version: "^1.0.0"

azd telepíti vagy frissíti a legmagasabb függőségi verziót, amely megfelel az egyes korlátozásoknak, és kompatibilis az aktuális azd verzióval a függőség tulajdonsága requiredAzdVersion alapján. Ha csak az inkompatibilis kiadások felelnek meg a korlátozásnak, kompatibilitási hibát jelez, azd és útmutatást nyújt a probléma megoldásához. Gyakori kényszerformátumok a következők:

  • ^1.0.0: Kompatibilis az 1.x.x verzióval.
  • ~1.2.0: Kompatibilis az 1.2.x verzióval.
  • >=1.0.0 <2.0.0: Egy verziótartomány.

Bővítmények csoportosítása bővítménycsomagokkal

A bővítménycsomagok olyan jegyzékfájlok, amelyek a kapcsolódó bővítményeket csoportosítják, így a felhasználók egyetlen paranccsal telepíthetik őket. A csomagok deklarálják dependencies , de nem biztosítanak végrehajtható, parancsnévteret vagy saját képességeket. Csomag használatával közzétehet egy válogatott bővítménykészletet, például egy termékcsaládot vagy egy forgatókönyvcsomagot:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/cli/azd/extensions/extension.schema.json

id: contoso.tools
displayName: Contoso Tools Extension Pack
description: Installs the Contoso azd extensions.
version: 0.1.0

dependencies:
  - id: contoso.azd.tagger
    version: "~0.1.0"

A csomagok telepítése rekurzív módon telepíti a függőségeit. Minden függőséghez a(z) azd a megadott korlátozásnak megfelelő legmagasabb verziót választja ki, amely a függőség azd tulajdonsága alapján kompatibilis az aktuális requiredAzdVersion verzióval.

Kapcsolódó tartalom

  • Last updated on