Dodawanie możliwości rozszerzenia

Funkcje określają, co rozszerzenie Azure Developer CLI (azd) może robić — od dodawania poleceń niestandardowych po integrowanie się z cyklem życia wdrażania. W tym artykule pokazano, jak dodać funkcje do przykładowego rozszerzenia Contoso Resource Tagger z przewodnika Szybki start dotyczącego tworzenia przykładowego rozszerzenia. Te same wzorce można zastosować do dowolnego rozszerzenia.

Każda funkcja wymaga dwóch rzeczy: wpisu w tablicy capabilitiesmanifestu rozszerzenia oraz odpowiedniej implementacji w kodzie rozszerzenia.

Dostępne możliwości

azd Rozszerzenia mogą deklarować następujące możliwości:

• custom-commands: dodaje nowe polecenia i grupy poleceń do azd obszaru nazw rozszerzenia. Na przykład, przykładowe rozszerzenie dodaje azd tagger show. Ta funkcja umożliwia uwidocznienie zadań uruchamianych bezpośrednio z poziomu wiersza polecenia.
• lifecycle-events: subskrybuje zdarzenia, które są zgłaszane przez azd podczas jego działania, takie jak preprovision, postprovision lub postdeploy. Rozszerzenie uruchamia logikę niestandardową w tych punktach bez bezpośredniego wywoływania go przez użytkownika. Na przykład przykładowe rozszerzenie sprawdza wymagane tagi preprovision przed utworzeniem jakichkolwiek zasobów.
• service-target-provider: Rejestruje nowy cel wdrożenia, dzięki czemu azd wie, jak spakować i wdrożyć usługę na hoście, który nie obsługuje gotowego rozwiązania. Obiekt docelowy usługi mapuje na wartość host w pliku azure.yaml. Możesz na przykład dodać dostawcę, który wdraża usługę na platformie innej firmy lub wewnętrznym środowisku hostingu.
• framework-service-provider: Rejestruje obsługę języka lub struktury, aby azd wiedzieć, jak przywrócić, skompilować i spakować ten typ projektu. To odpowiada wartości language w azure.yaml. Możesz na przykład dodać obsługę kompilacji dla języka, który azd nie rozpoznaje domyślnie.
• provisioning-provider: zastępuje sposób, w jaki azd udostępnia infrastrukturę podczas azd provision i azd up. Zamiast wbudowanego przepływu Bicep lub Terraform, Twoje rozszerzenie określa, co się dzieje. Możesz na przykład zintegrować inne narzędzie do zarządzania infrastrukturą jako kod lub niestandardowy interfejs API do wdrażania.
• validation-provider: Dodaje kontrole do potoku walidacji azd, które są uruchamiane dla projektu lub środowiska. Na przykład przed kontynuowaniem wdrażania można sprawdzić, czy obowiązują konwencje nazewnictwa, wymagane tagi lub ustawienia zabezpieczeń.
• mcp-server: udostępnia funkcje rozszerzenia jako narzędzia protokołu MCP (Model Context Protocol), które agenci sztucznej inteligencji, tacy jak GitHub Copilot, mogą odnajdywać i wywoływać. Na przykład przykładowe rozszerzenie może udostępniać narzędzie suggest_tags. Aby uzyskać więcej informacji, zobacz Dodawanie serwera MCP do rozszerzenia.
• metadata: zapewnia bardziej rozbudowane metadane poleceń i konfiguracji, których azd używa do opisywania Twojego rozszerzenia, takie jak szczegółowe opisy poleceń i wskazówki konfiguracyjne wyświetlane w danych wyjściowych pomocy i w funkcji IntelliSense.

Ten artykuł koncentruje się na dwóch najczęściej spotykanych funkcjach: poleceniach niestandardowych i zdarzeniach cyklu życia. Aby uzyskać informacje na temat mcp-server możliwości, zobacz Dodawanie serwera MCP do rozszerzenia. Aby uzyskać szczegółowe informacje na temat możliwości dostawcy, zobacz dokumentację platformy rozszerzeń.

Dodawanie poleceń niestandardowych

Ta custom-commands możliwość umożliwia rozszerzeniu rejestrowanie nowych poleceń w przestrzeni nazw w azd. Przykładowe rozszerzenie używa już tej funkcji dla azd tagger show polecenia .

1. Zadeklaruj funkcję w extension.yaml.

   capabilities:
     - custom-commands
   

2. Twórz swoje polecenia przy użyciu pomocnika azdext.NewExtensionRootCommand, który rejestruje standardowe flagi azd oraz obsługę zmiennych środowiskowych, dzięki czemu nie musisz deklarować ich ręcznie:

   import "github.com/azure/azure-dev/cli/azd/pkg/azdext"
   
   func NewRootCommand() *cobra.Command {
       rootCmd, extCtx := azdext.NewExtensionRootCommand(azdext.ExtensionCommandOptions{
           Name:  "tagger",
           Use:   "tagger <command> [options]",
           Short: "Standardize and report Azure resource tags.",
       })
   
       rootCmd.AddCommand(newShowCommand(extCtx))
       // Add other subcommands here.
       return rootCmd
   }
   

   Pomocnik zwraca element *ExtensionContext , który uwidacznia rozpoznane wartości flag standardowych, takich jak Environment i OutputFormat. Przekaż kontekst do podpoleceń i odczytaj go z niego w ich programach obsługi RunE, zamiast ponownie deklarować standardowe flagi.

Subskrybowanie zdarzeń cyklu życia

Ta możliwość umożliwia rozszerzeniu uruchamianie lifecycle-events niestandardowej logiki podczas zdarzeń cyklu życia projektów i usług, takich jak preprovision lub postdeploy. W przypadku przykładowego rozszerzenia użyj zdarzenia preprovision, aby sprawdzić, czy wymagane tagi są ustawione, zanim azd utworzy jakiekolwiek zasoby.

1. Zadeklaruj funkcję w extension.yaml.

   capabilities:
     - custom-commands
     - lifecycle-events
   

2. Dodaj listen polecenie do swojego rozszerzenia. azd wywołuje to polecenie w celu ustanowienia dwukierunkowego połączenia używanego do obsługi zdarzeń. Użyj elementu builder azdext.NewExtensionHost, aby zarejestrować procedury obsługi zdarzeń:

   func newListenCommand() *cobra.Command {
       return &cobra.Command{
           Use:    "listen",
           Short:  "Starts the extension and listens for azd events.",
           Hidden: true,
           RunE: func(cmd *cobra.Command, args []string) error {
               ctx := azdext.WithAccessToken(cmd.Context())
   
               azdClient, err := azdext.NewAzdClient()
               if err != nil {
                   return fmt.Errorf("failed to create azd client: %w", err)
               }
               defer azdClient.Close()
   
               host := azdext.NewExtensionHost(azdClient).
                   WithProjectEventHandler(
                       "preprovision",
                       func(ctx context.Context, args *azdext.ProjectEventArgs) error {
                           fmt.Printf("Verifying required tags for project: %s\n", args.Project.Name)
                           // Add your tag validation logic here.
                           return nil
                       },
                   )
   
               // Run blocks until azd closes the connection.
               if err := host.Run(ctx); err != nil {
                   return fmt.Errorf("failed to run extension: %w", err)
               }
   
               return nil
           },
       }
   }
   

3. Zarejestruj polecenie listen w swoim poleceniu głównym:

   rootCmd.AddCommand(newListenCommand())
   

Gdy użytkownik wykonuje azd provision lub azd up, azd uruchamia twoje rozszerzenie i wywołuje procedurę obsługi preprovision przed udostępnieniem zasobów.

Filtruj zdarzenia usługi

Programy obsługi zdarzeń usługi obsługują filtrowanie opcjonalne, aby obsługiwać tylko określone typy usług. Na przykład, można obsłużyć zdarzenie prepackage tylko dla usług aplikacji kontenerowych w języku Python:

host := azdext.NewExtensionHost(azdClient).
    WithServiceEventHandler(
        "prepackage",
        func(ctx context.Context, args *azdext.ServiceEventArgs) error {
            fmt.Printf("Packaging service: %s\n", args.Service.Name)
            return nil
        },
        &azdext.ServiceEventOptions{
            Host:     "containerapp",
            Language: "python",
        },
    )

Ponowne kompilowanie i testowanie

Po dodaniu możliwości ponownie skompiluj rozszerzenie i przetestuj nowe zachowanie:

1. Jeśli używasz obserwatora, zmiany zostaną automatycznie ponownie ponownie utworzone. W przeciwnym razie skompiluj ręcznie:

   azd x build
   

2. Przetestuj możliwości. W przypadku zdarzeń cyklu życia uruchom polecenie, które wyzwala zdarzenie, takie jak azd provision.

Treści powiązane

• Komunikacja z azd przy użyciu zestawu SDK
• Dodawanie serwera MCP do rozszerzenia
• Publikowanie rozszerzenia
• Dokumentacja platformy rozszerzeń