Добавление возможностей расширения

Возможности определяют, что может делать расширение Azure Developer CLI (azd): от добавления настраиваемых команд до подключения к жизненному циклу развертывания. В этой статье показано, как расширить функциональность образца расширения Contoso Resource Tagger, описанного в кратком руководстве по созданию образца расширения. К любому расширению можно применить те же шаблоны.

Каждая возможность требует двух вещей: запись в capabilitiesмассиве манифеста расширения и соответствующую реализацию в коде расширения.

Замечание

Платформа расширений azd стала общедоступной. Отдельные расширения или возможности могут иметь собственное состояние предварительной версии. Сведения о выпуске общедоступной версии см. в статье Общедоступная версия: платформа расширений Azure Developer CLI (azd).

Доступные возможности

azd Расширения могут объявлять следующие возможности:

custom-commands: добавляет новые команды и группы команд в azd в пространстве имен вашего расширения. Например, пример расширения добавляет azd tagger show. Используйте эту возможность для предоставления задач, выполняемых пользователями непосредственно из командной строки.
lifecycle-events: подписывается на события, которые azd вызывает во время выполнения, например preprovision, postprovision или postdeploy. Расширение запускает пользовательскую логику в этих точках без непосредственного вызова пользователя. Например, пример расширения проверяет наличие необходимых тегов preprovision перед созданием ресурсов.
service-target-provider: регистрирует новую цель развертывания, чтобы azd знал, как упаковывать и развертывать сервис на хосте, который он не поддерживает из коробки. Цель службы соответствует значению host в azure.yaml. Например, можно добавить поставщика, который развертывает службу на сторонней платформе или во внутренней среде размещения.
framework-service-provider: регистрирует поддержку языка или платформы, поэтому azd знает, как восстановить, построить и упаковать этот тип проекта. Это сопоставляется со значением language в azure.yaml. Например, можно добавить поддержку сборки для языка, который azd по умолчанию не распознает.
provisioning-provider: заменяет способ, которым azd подготавливает инфраструктуру во время azd provision и azd up. Вместо встроенного потока Bicep или Terraform расширение определяет, что происходит. Например, можно интегрировать другой инструмент IaC (инфраструктура как код) или собственный API для развертывания.
validation-provider: добавляет проверки в конвейер валидации azd, которые выполняются для проекта или среды. Например, вы можете убедиться, что соглашения об именовании, обязательные теги или параметры безопасности установлены перед продолжением развертывания.
mcp-server: предоставляет функциональные возможности расширения в качестве средств протокола контекста модели (MCP), которые агенты ИИ, такие как GitHub Copilot, могут обнаруживать и вызывать. Например, пример расширения может предоставлять инструмент suggest_tags. Дополнительные сведения см. в разделе "Добавление сервера MCP в расширение".
metadata: предоставляет более подробные метаданные о командах и конфигурации, которые azd использует для описания вашего расширения, например подробные описания команд и подсказки по настройке, которые отображаются в справке и IntelliSense.

В этой статье рассматриваются две наиболее распространенные возможности: пользовательские команды и события жизненного цикла. mcp-server Сведения о возможности см. в разделе "Добавление сервера MCP в расширение". Полные сведения о возможностях поставщика см. в справочнике по платформе расширений.

Добавление пользовательских команд

Эта возможность custom-commands позволяет вашему расширению регистрировать новые команды под пространством имён в azd. Пример расширения уже использует эту возможность для azd tagger show команды.

Объявите возможность в extension.yaml.
```
capabilities:
  - custom-commands
```
Создайте команды с помощью вспомогательного azdext.NewExtensionRootCommand средства, который регистрирует стандартные azd флаги и обработку переменных среды, чтобы не объявлять их вручную:
```
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
}
```
Хелпер возвращает *ExtensionContext, который предоставляет доступ к вычисленным значениям стандартных флагов, таких как Environment и OutputFormat. Передайте контекст в свои подкоманды и читайте его в их обработчиках RunE вместо того, чтобы повторно объявлять стандартные флаги.

Эта lifecycle-events возможность позволяет расширению выполнять пользовательскую логику во время событий жизненного цикла проекта и службы, таких как preprovision или postdeploy. В примере расширения используйте событие preprovision, чтобы убедиться, что необходимые теги заданы, прежде чем azd подготовит какие-либо ресурсы.

Объявите возможность в extension.yaml.
```
capabilities:
  - custom-commands
  - lifecycle-events
```

Добавьте команду listen в ваше расширение. azd вызывает эту команду, чтобы установить двунаправленное соединение, используемое для событий. Используйте конструктор azdext.NewExtensionHost для регистрации обработчиков событий:

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
        },
    }
}

Зарегистрируйте команду listen в вашей корневой команде:
```
rootCmd.AddCommand(newListenCommand())
```

Когда пользователь запускает azd provision или azd up, azd вызывает ваше расширение и обращается к обработчику preprovision перед выделением ресурсов.

Фильтровать события службы

Обработчики событий службы поддерживают необязательную фильтрацию, чтобы обрабатывать только определенные типы служб. Например, можно обрабатывать событие prepackage только для служб контейнерных приложений 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",
        },
    )

Перестроение и тестирование

После добавления возможности перестройте расширение и проверьте новое поведение:

Если вы используете режим отслеживания, ваши изменения автоматически пересобираются. В противном случае выполните сборку вручную:
```
azd x build
```
Проверьте функциональность. Для событий жизненного цикла выполните команду, которая активирует событие, например azd provision.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-09-10