Definování manifestu rozšíření

Každé rozšíření Azure Developer CLI (azd) obsahuje manifest extension.yaml, který popisuje jeho metadata a schopnosti. azd používá tato metadata v registru rozšíření, aby uživatelům pomohla zjistit, nainstalovat a pochopit vaše rozšíření. Tento článek vysvětluje vlastnosti manifestu pomocí ukázkového rozšíření Contoso Resource Tagger z rychlého startu Sestavení ukázkového rozšíření. Stejné koncepty můžete použít u libovolného rozšíření.

Note

azd rozšíření jsou aktuálně v beta verzi.

Vlastnosti manifestu

Manifest extension.yaml podporuje následující vlastnosti.

Požadované vlastnosti

Každý manifest musí obsahovat následující vlastnosti:

Property Description
id Jedinečný identifikátor rozšíření, například contoso.azd.tagger.
version Sémantická verze ve MAJOR.MINOR.PATCH formátu.
displayName Název rozšíření ve srozumitelné podobě.
description Podrobný popis rozšíření

Každý manifest musí obsahovat také buď capabilities nebo dependencies. Rozšíření, které poskytuje příkazy nebo poskytovatele, deklaruje capabilities. Sada rozšíření místo toho deklaruje dependencies.

Volitelné vlastnosti

Manifest také podporuje následující volitelné vlastnosti:

Property Description
namespace Obor názvů příkazů, který seskupuje příkazy rozšíření, například tagger.
entryPoint Spustitelný soubor nebo skript, který slouží jako vstupní bod.
language Programovací jazyk, ve kterém je rozšíření napsané, například go.
capabilities Pole možností rozšíření
usage Pokyny k použití rozšíření
examples Pole příkladů použití s názvem, popisem a využitím
tags Klíčová slova pro kategorizaci a filtrování
dependencies Další rozšíření, na které toto rozšíření závisí.
providers Seznam poskytovatelů, které rozšíření registruje
platforms Metadata specifická pro platformu
mcp Konfigurace serveru protokolu Model Context Protocol
requiredAzdVersion Omezení sémantické verze pro verzi azd, která je vyžadována pro použití rozšíření, například >= 1.24.0.

Příklad manifestu

Následující příklad znázorňuje soubor manifestu extension.yaml pro ukázkové rozšíření Contoso Resource Tagger:

# 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

Komentář $schema v horní části souboru umožňuje ověřování a Technologii IntelliSense v editorech, které podporují jazykový server YAML.

Deklarace možností

Pole capabilities deklaruje, co vaše rozšíření může dělat. azd uděluje odpovídající oprávnění za běhu a některé služby frameworku selžou kvůli chybě oprávnění, pokud není deklarována odpovídající schopnost. Ukázkové rozšíření začíná pouze s custom-commands:

capabilities:
  - custom-commands

Při přidávání funkcí v dalších článcích přidáte další možnosti. Například Přidat možnosti rozšíření přidá lifecycle-eventsa přidat server MCP do rozšíření přidá mcp-server. Dostupné funkce jsou:

  • custom-commands: Přidejte nové příkazy do azd pod svým oborem názvů, například azd tagger show.
  • lifecycle-events: Spusťte vlastní logiku, když azd vyvolá události, jako jsou preprovision nebo postdeploy.
  • mcp-server: Zveřejnění nástrojů protokolu kontextového modelu, které můžou volat agenti umělé inteligence.
  • service-target-provider: Přidejte vlastní cíl nasazení pro host službu, která azd ve výchozím nastavení nepodporuje.
  • framework-service-provider: Přidejte podporu pro sestavení a vytváření balíčků pro language, kterou azd ve výchozím nastavení nerozpoznává.
  • provisioning-provider: Nahraďte způsob, jakým azd zřizuje infrastrukturu vlastní implementací.
  • validation-provider: Přidejte kontroly, které se spouštějí v kanálu ověřování azd.
  • metadata: Poskytuje podrobnější metadata o příkazech a konfiguraci pro výstup nápovědy a IntelliSense.

Úplné vysvětlení jednotlivých funkcí s příklady najdete v tématu Přidání možností rozšíření.

Přidání příkladů použití

Pole examples popisuje běžné způsoby použití vašeho rozšíření. azd zobrazí tyto příklady, když uživatelé zobrazí podrobnosti o vašem rozšíření:

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

Registrace poskytovatelů

Pokud vaše rozšíření poskytuje vlastní cíle služeb nebo služby architektury, deklarujte je v providers části, takže azd ví, co vaše rozšíření nabízí:

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

Přidání konfigurace specifické pro platformu

platforms Pomocí vlastnosti můžete poskytnout metadata specifická pro platformu, jako je například název spustitelného souboru pro každý operační systém.

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

Deklarace závislostí

Rozšíření můžou záviset na jiných rozšířeních pomocí dependencies pole. Závislosti podporují sémantická omezení správy verzí:

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

azd nainstaluje nebo upgraduje na nejvyšší verzi závislostí, která splňuje každé omezení a je kompatibilní s aktuální azd verzí na základě vlastnosti závislosti requiredAzdVersion . Pokud omezení vyhovují jenom nekompatibilním verzím, azd nahlásí chybu kompatibility a poskytne pokyny k jeho vyřešení. Mezi běžné formáty omezení patří:

  • ^1.0.0: Kompatibilní s verzí 1.x.x.
  • ~1.2.0: Kompatibilní s verzí 1.2.x.
  • >=1.0.0 <2.0.0: Rozsah verzí.

Rozšíření skupin s balíčky rozšíření

Balíček rozšíření je manifest, který seskupuje související rozšíření, aby je uživatelé mohli nainstalovat jediným příkazem. Balíček deklaruje dependencies , ale neposkytuje spustitelný soubor, obor názvů příkazů ani vlastní funkce. Balíček použijte k publikování kurátorované sady rozšíření, jako je řada produktů nebo sada scénářů:

# 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"

Při instalaci balíčku se rekurzivně nainstalují jeho závislosti. Pro každou závislost vybere nejvyšší verzi, azd která splňuje deklarované omezení, a je kompatibilní s aktuální azd verzí na základě vlastnosti závislosti requiredAzdVersion .

Související obsah

  • Poslední aktualizace v