Definiowanie manifestu rozszerzenia

Każde rozszerzenie Azure Developer CLI (azd) zawiera plik manifestu extension.yaml, który opisuje jego metadane i funkcje. azd używa tych metadanych w rejestrze rozszerzeń, aby ułatwić użytkownikom odnajdywanie, instalowanie i interpretowanie rozszerzenia. W tym artykule opisano właściwości manifestu na przykładzie przykładowego rozszerzenia Contoso Resource Tagger z przewodnika Szybki start: tworzenie przykładowego rozszerzenia. Te same pojęcia można zastosować do dowolnego rozszerzenia.

Uwaga / Notatka

azd rozszerzenia są obecnie w wersji beta.

Właściwości manifestu

Manifest extension.yaml obsługuje następujące właściwości.

Wymagane właściwości

Każdy manifest musi zawierać następujące właściwości:

Property Description
id Unikatowy identyfikator rozszerzenia, taki jak contoso.azd.tagger.
version Wersja semantyczna w MAJOR.MINOR.PATCH formacie.
displayName Czytelna dla człowieka nazwa rozszerzenia.
description Szczegółowy opis rozszerzenia.

Każdy manifest musi również zawierać wartość capabilities lub dependencies. Rozszerzenie, które udostępnia polecenia lub dostawców, deklaruje capabilities. Pakiet rozszerzeń zamiast tego deklaruje dependencies.

Właściwości opcjonalne

Manifest obsługuje również następujące właściwości opcjonalne:

Property Description
namespace Przestrzeń nazw poleceń, która grupuje polecenia rozszerzenia, takie jak tagger.
entryPoint Plik wykonywalny lub skrypt, który służy jako punkt wejścia.
language Język programowania, w jakim jest napisane rozszerzenie, na przykład go.
capabilities Tablica możliwości rozszerzenia.
usage Instrukcje dotyczące używania rozszerzenia.
examples Tablica przykładów użycia z nazwą, opisem i użyciem.
tags Słowa kluczowe dotyczące kategoryzacji i filtrowania.
dependencies Inne rozszerzenia, od których zależy to rozszerzenie.
providers Lista dostawców rejestrowanych przez rozszerzenie.
platforms Metadane specyficzne dla platformy.
mcp Konfiguracja serwera Model Context Protocol.
requiredAzdVersion Ograniczenie wersji semantycznej w azd wersji wymaganej do korzystania z rozszerzenia, takiego jak >= 1.24.0.

Przykładowy manifest

W poniższym przykładzie przedstawiono manifest extension.yaml przykładowego rozszerzenia 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

$schema Komentarz w górnej części pliku umożliwia walidację i funkcję IntelliSense w edytorach obsługujących serwer języka YAML.

Deklarowanie możliwości

Tablica capabilities deklaruje, co może zrobić rozszerzenie. azd przyznaje odpowiednie uprawnienia w czasie wykonywania, a niektóre usługi platformowe kończą się niepowodzeniem z powodu błędu uprawnień, jeśli nie zadeklarowana jest zgodna możliwość. Przykładowe rozszerzenie zaczyna się tylko od custom-commands:

capabilities:
  - custom-commands

W miarę dodawania funkcji w innych artykułach dodajesz więcej możliwości. Na przykład Dodaj możliwości rozszerzenia dodaje lifecycle-events, a Dodaj serwer MCP do rozszerzenia dodaje mcp-server. Dostępne możliwości to:

  • custom-commands: Dodaj nowe polecenia do azd w swojej przestrzeni nazw, na przykład azd tagger show.
  • lifecycle-events: Uruchom logikę niestandardową, gdy azd zgłasza zdarzenia, takie jak preprovision lub postdeploy.
  • mcp-server: Udostępniaj narzędzia Model Context Protocol, które agenci AI mogą wywoływać.
  • service-target-provider: Dodaj niestandardowy cel wdrożenia dla elementu host , który azd nie obsługuje domyślnie.
  • framework-service-provider: Dodaj obsługę kompilacji i pakietów dla elementu language , który azd nie rozpoznaje domyślnie.
  • provisioning-provider: Zastąp sposób, w jaki azd udostępnia infrastrukturę, niestandardową implementacją.
  • validation-provider: Dodaj kontrole uruchamiane w potoku azd weryfikacji.
  • metadata: Udostępnianie bardziej rozbudowanych metadanych dotyczących poleceń i konfiguracji dla danych wyjściowych pomocy i funkcji IntelliSense.

Aby uzyskać bardziej szczegółowe wyjaśnienie poszczególnych możliwości z przykładami, zobacz Dodawanie możliwości rozszerzenia.

Dodawanie przykładów użycia

Tablica examples zawiera typowe sposoby korzystania z rozszerzenia. azd wyświetla te przykłady, gdy użytkownicy przeglądają szczegóły Twojego rozszerzenia:

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

Rejestrowanie dostawców

Gdy rozszerzenie udostępnia niestandardowe cele usługi lub usługi frameworku, zadeklaruj je w sekcji providers, aby azd wiedział, co oferuje rozszerzenie:

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

Dodawanie konfiguracji specyficznej dla platformy

platforms Użyj właściwości , aby udostępnić metadane specyficzne dla platformy, takie jak nazwa pliku wykonywalnego dla każdego systemu operacyjnego.

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

Deklarowanie zależności

Rozszerzenia mogą zależeć od innych rozszerzeń przy użyciu tablicy dependencies . Zależności obsługują ograniczenia wersjonowania semantycznego:

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

azd instaluje lub uaktualnia do najwyższej wersji zależności, która spełnia każde ograniczenie i jest zgodna z bieżącą azd wersją na podstawie właściwości zależności requiredAzdVersion . Jeśli tylko niezgodne wersje spełniają ograniczenia, azd zgłasza błąd zgodności i zawiera wskazówki dotyczące jego rozwiązania. Typowe formaty ograniczeń obejmują:

  • ^1.0.0: zgodny z wersją 1.x.x.
  • ~1.2.0: zgodny z wersją 1.2.x.
  • >=1.0.0 <2.0.0: zakres wersji.

Grupuj rozszerzenia za pomocą pakietów rozszerzeń

Pakiet rozszerzeń to manifest, który grupuje powiązane rozszerzenia, aby użytkownicy mogli je zainstalować za pomocą jednego polecenia. Pakiet deklaruje dependencies, ale nie udostępnia własnego pliku wykonywalnego, przestrzeni nazw poleceń ani funkcji. Użyj pakietu, aby opublikować starannie dobrany zestaw rozszerzeń, na przykład rodzinę produktów lub pakiet scenariuszy:

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

Instalowanie pakietu rekursywnie instaluje jego zależności. Dla każdej zależności azd wybiera najwyższą wersję, która spełnia zadeklarowane ograniczenie i jest zgodna z bieżącą azd wersją na podstawie właściwości zależności requiredAzdVersion .

Treści powiązane

  • Last updated on