Omówienie rozszerzeń interfejsu wiersza polecenia dla deweloperów platformy Azure

Rozszerzenia Azure Developer CLI (azd) to komponenty modułowe, które zwiększają funkcjonalność tego interfejsu. Umożliwiają one dodawanie nowych funkcji, automatyzowanie przepływów pracy i integrowanie z innymi usługami bezpośrednio z poziomu interfejsu wiersza polecenia. Użyj rozszerzeń, aby dostosować azd do zmieniających się potrzeb zespołu i scenariuszy platformy Azure.

Uwaga / Notatka

Platforma azd rozszerzeń jest ogólnie dostępna. Poszczególne rozszerzenia lub możliwości mogą mieć własny stan wersji zapoznawczej.

Zarządzanie źródłami rozszerzeń

Rozszerzenia można odnajdywać, instalować i aktualizować w miarę wzrostu wymagań. Źródła rozszerzeń obsługują dystrybucję i zarządzanie.

  • Źródła rozszerzeń to manifesty oparte na plikach lub adresach URL, które udostępniają listy dostępnych azd rozszerzeń.
  • Możesz dodać niestandardowe źródła rozszerzeń, które łączą się z prywatnymi, lokalnymi lub publicznymi rejestrami.
  • Źródła rozszerzeń są równoważną koncepcją źródeł pakietów NuGet lub Node Menedżer pakietów (NPM) i muszą być zgodne ze schematem oficjalnego rejestru rozszerzeń.

azd obsługuje kilka sposobów rozwiązywania problemów z rozszerzeniami:

  • Oficjalny rejestr źródłowy rozszerzeń jest wstępnie skonfigurowany w azd i jest hostowany pod adresem https://aka.ms/azd/extensions/registry.
  • Źródła oparte na adresach URL odwołują się do manifestów rejestru zdalnego, które zespół hostuje na potrzeby dystrybucji publicznej lub prywatnej.
  • Źródła oparte na plikach odwołują się do manifestów rejestru lokalnego do użycia w trybie offline lub programowania lokalnego.
  • Rejestry development i nightly są opcjonalnymi źródłami wersji w trakcie rozwoju oraz automatycznie tworzonych własnych rozszerzeń. Używaj ich do testowania scenariuszy zamiast produkcyjnych przepływów pracy.
  • Samodzielne pliki pakietów zapewniają przenośne .zip pakiety do bezpośredniej instalacji z lokalnego pliku lub adresu URL HTTPS, gdy nie chcesz hostować rejestru.

azd Wymusza ścisłą walidację niestandardowych nazw źródeł rozszerzeń. Nazwy muszą zawierać od 1 do 64 małych liter lub cyfr ASCII. Łączniki () i podkreślenia (-_) można uwzględnić między literami lub cyframi. Nazwy muszą zaczynać się i kończyć literą lub cyfrą. azd zwraca błąd dla nieprawidłowych nazw; nie normalizuje ich. Nazwy azd i bundle są zastrzeżone i nie mogą być używane dla źródeł niestandardowych. Nazwa źródła musi być prawidłowa, gdy używasz jej z elementem --source.

Wstępnie skonfigurowane azd źródło jest oficjalnym rejestrem. Nie można go usunąć ani zmienić jego lokalizacji.

Aby wyrazić zgodę na rejestr programowania, uruchom następujące polecenie:

# Add a new extension source name 'dev' to your `azd` configuration.
azd extension source add -n dev -t url -l "https://aka.ms/azd/extensions/registry/dev"

Ostrzeżenie

Rozszerzenia hostowane w rejestrze deweloperów są niepodpisane, nieobjęte pomoc techniczna platformy Azure i mogą ulec zmianie lub usunięciu bez powiadomienia.

Polecenia źródłowe rozszerzeń

Użyj następujących poleceń, aby zarządzać źródłami rozszerzeń na potrzeby azd instalacji.

Wyświetlanie listy zainstalowanych źródeł rozszerzeń

azd extension source list

Dodawanie nowego źródła rozszerzenia

azd extension source add -n <name> -t url -l <registry-url>
  • -l, --location: lokalizacja źródła rozszerzenia.
  • -n, --name: nazwa źródła rozszerzenia. Użyj poprawnej własnej nazwy źródła.
  • -t, --type: typ źródła rozszerzenia. Obsługiwane typy to plik i adres URL.

Usuwanie źródła rozszerzenia

azd extension source remove <name>

Nie można usunąć wstępnie skonfigurowanego azd źródła.

Jeśli podczas aktualizacji zostanie zgłoszony błąd ładowania źródła spowodowany starszą, nieprawidłową nazwą źródła w ~/.azd/config.json, usuń wadliwe źródło za pomocą azd extension source remove, a następnie dodaj je ponownie, używając prawidłowej nazwy.

Zarządzanie rozszerzeniami

Po włączeniu rozszerzeń i skonfigurowaniu źródeł rozszerzeń zainstaluj rozszerzenia, aby dodać nowe możliwości do programu azd. Aby zapoznać się z przykładem pracy z rozszerzeniami, zobacz Szybki start — używanie rozszerzenia sztucznej inteligencji.

Lista rozszerzeń

azd extension list [flags]
  • --installed Wyświetla listę zainstalowanych rozszerzeń.
  • --source Wyświetla tylko rozszerzenia z określonego źródła. Nazwa źródła musi być prawidłową zarejestrowaną nazwą źródła.
  • --tags Filtruje rozszerzenia według tagów, takich jak sztuczna inteligencja lub test.

Instalowanie rozszerzenia

azd extension install <extension-names> [flags]

Zastąp <extension-name> ciąg nazwą rozszerzenia, które chcesz zainstalować.

  • -v, --version Określa dokładną wersję do zainstalowania. Ta opcja nie akceptuje zakresów wersji ani ograniczeń i nie można jej używać podczas instalowania samodzielnego pakietu (.zip ścieżka pliku lub adres URL).
  • -s, --source Określa źródło rozszerzenia używane do instalacji. Nazwa źródła musi być prawidłową zarejestrowaną nazwą źródła.

Aby zainstalować samodzielny pakiet z adresu URL HTTPS, podaj lokalizację pakietu jako nazwę rozszerzenia:

azd extension install https://example.com/extensions/example.zip
  • --all Uaktualnia wszystkie wcześniej zainstalowane rozszerzenia, gdy jest to określone.
  • -v, --version Uaktualnia określone rozszerzenie do dokładnej wersji, jeśli zostanie podane. Ta opcja nie akceptuje zakresów wersji ani ograniczeń.
  • -s, --source Określa źródło rozszerzenia używane do instalacji. Nazwa źródła musi być prawidłową zarejestrowaną nazwą źródła.
  • --no-dependency-updates Zapobiega aktualizacjom zależności po określeniu.

Odinstalowywanie rozszerzenia

azd extension uninstall <extension-name>
  • --all Usuwa wszystkie zainstalowane rozszerzenia po określeniu.

Deklarowanie wymaganych rozszerzeń w projekcie

Projekty mogą deklarować wymagane rozszerzenia w azure.yaml, dzięki czemu azd może ustalać i instalować wersje rozszerzeń wymagane przez dany projekt. Dodaj wymagania dotyczące rozszerzenia w obszarze requiredVersions.extensions, i użyj latest, dokładnej wersji lub obsługiwanego ograniczenia wersji semantycznej.

requiredVersions:
  extensions:
    azure.ai.agents: "latest"
    contoso.azd.tagger: "^2.0.0"

Użyj wymagań na poziomie projektu, gdy szablon zależy od hostów usług udostępnianych przez rozszerzenie, procedur obsługi cyklu życia, dostawców weryfikacji lub poleceń. Aby uzyskać szczegółowe informacje o pełnym schemacie i ograniczeniu wersji, zobacz requiredVersions.

Omówienie punktów integracji rozszerzeń

Rozszerzenia mogą integrować się z azd na kilka sposobów:

  • Dodaj przestrzenie nazw poleceń z metadanymi, pomocą i przykładami.
  • Podaj schematy konfiguracji i metadane funkcji IntelliSense dla plików projektu.
  • Zarejestruj obsługę zdarzeń cyklu życia dla przepływów pracy, takich jak aprowizacja, pakowanie i wdrażanie.
  • Dodaj dostawców do obsługi niestandardowej aprowizacji, walidacji, obiektów docelowych usług oraz obsługi języka lub platformy.
  • Uwidaczniaj możliwości serwera protokołu MCP (Model Context Protocol) dla agentów i narzędzi deweloperskich.

Aby uzyskać wskazówki dotyczące implementacji, zobacz Pojęcia dotyczące programowania rozszerzeń.

Używanie rozszerzeń azd w kontenerach deweloperskich

Funkcja azd kontenera deweloperskiego obsługuje extensions opcję automatycznego instalowania rozdzielanej przecinkami listy azd rozszerzeń podczas kompilacji kontenera. Rozszerzenia zainstalowane w ten sposób są dostępne natychmiast po uruchomieniu kontenera, co zmniejsza konfigurację ręczną i umożliwia azd uruchamianie poleceń z już zainstalowanymi wymaganymi rozszerzeniami.

Żeby automatycznie zainstalować rozszerzenia, dodaj opcję extensions do wpisu funkcji azd w pliku devcontainer.json.

{
    "name": "Azure Developer CLI",
    "image": "mcr.microsoft.com/devcontainers/python:3.10-bullseye",
    "features": {
        "ghcr.io/azure/azure-dev/azd:latest": {
            "extensions": "my-ext-1,my-ext-2"
        }
    }
}

Wartość extensions jest rozdzielaną przecinkami listą azd nazw rozszerzeń. Instalacja odbywa się podczas kompilacji kontenera, więc rozszerzenia są gotowe do użycia natychmiast po uruchomieniu kontenera. Po zmianie listy rozszerzeń użyj polecenia Ponowne kompilowanie i ponowne otwieranie w kontenerze deweloperskim w programie Visual Studio Code, aby ponownie skompilować kontener przy użyciu zaktualizowanych rozszerzeń.

Dowiedz się więcej o funkcji kontenera deweloperskiego azd.

Dalsze kroki

  • Last updated on