Основные понятия разработки расширений

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

Расширение для разработчиков

Самый быстрый способ сборки расширений — использовать расширение разработчика azd (microsoft.azd.extensions). Расширение для разработчиков добавляет набор команд в пространстве имен azd x, которые позволяют создавать каркас, собирать, упаковывать и публиковать ваше расширение:

Command	Description
`azd x init`	Шаблонирует новый проект расширения на выбранном языке.
`azd x build`	Создает двоичный файл расширения для локальной разработки.
`azd x watch`	Просматривает проект для изменений и автоматически перестраивает и устанавливает расширение.
`azd x pack`	Упаковает артефакты расширения для подготовки к публикации.
`azd x release`	Создает релиз GitHub для расширения.
`azd x publish`	Обновляет реестр расширений с новыми метаданными расширения.

В кратком руководстве по созданию примера расширения описано, как установить расширение для разработчиков и создать каркас своего первого расширения.

Расширение разработчика поддерживает рабочие процессы публикации на основе реестра и переносимое распределение пакетов. Используйте azd x pack, чтобы создавать артефакты платформы для публикации релиза и в реестре, либо создавайте автономный пакет .zip, если нужно распространить расширение без необходимости размещать реестр. Пакеты можно устанавливать из локального файла или размещать удаленно по URL-адресу HTTPS. Пошаговые инструкции см. в разделе "Публикация расширения".

Платформа расширений и gRPC

azd и расширения работают как отдельные процессы, которые взаимодействуют через gRPC. При вызове команды расширения выполняются следующие действия:

azd запускает сервер gRPC на случайном порту и задает AZD_SERVER переменную среды с адресом сервера.
azd задает переменную среды AZD_ACCESS_TOKEN, которая содержит подписанный JSON Web Token (JWT), предоставляющий расширению доступ к службам azd на время выполнения команды.
azd вызывает команду расширения и передает текущие аргументы, флаги и переменные среды.
Ваше расширение использует клиент gRPC, чтобы взаимодействовать с azd через службы фреймворка, например запрашивать данные у пользователя или считывать конфигурацию проекта.
azd ожидает завершения команды и считает ненулевой код выхода ошибкой.

Эта модель позволяет расширениям взаимодействовать azd в согласованном, безопасном способе без прямого доступа к внутреннему azd состоянию.

Требования к расширению на уровне проекта

Проекты могут объявлять в azure.yaml, какие расширения им требуются. Используйте раздел requiredVersions.extensions для перечисления идентификаторов расширений и ограничений версий, чтобы azd мог определить версии, которые соответствуют требованиям проекта.

requiredVersions:
  extensions:
    azure.ai.agents: ">=1.0.0"
    contoso.azd.tagger: "^2.0.0"

Объявите необходимые расширения, если проект зависит от хостов, поставщиков, обработчиков жизненного цикла, средств проверки или команд, предоставляемых расширениями. Подробные сведения о схеме и поддерживаемом синтаксисе версий см. в разделе requiredVersions.

SDK azdext

Пакет azdext — это пакет SDK Go для платформы расширений. Он предоставляет клиент gRPC и вспомогательные компоненты, которые берут на себя детали взаимодействия, чтобы вы могли сосредоточиться на логике своего расширения. SDK включает вспомогательные компоненты:

Создайте корневую команду, которая регистрирует стандартные azd флаги и обработку переменных среды.
Добавьте azd токен доступа к исходящим запросам.
Вызывать azd службы фреймворка, такие как службы Project, Environment, Account и Prompt.
Сообщайте об именованных событиях использования через TelemetryService.ReportUsage gRPC API для расширений из официальных источников. Сведения об использовании API см. в разделе "Обмен данными с azd" с помощью пакета SDK.
Зарегистрируйте обработчики событий жизненного цикла и пользовательские провайдеры в хосте расширений.

Сведения о вызове azd служб из расширения см. в статье Взаимодействие с azd с помощью пакета SDK.

Возможности расширения

Возможности определяют, что может делать расширение. Перечислите возможности расширения в его манифесте extension.yaml, и azd предоставит соответствующие разрешения во время выполнения. Доступные возможности:

custom-commands: Добавьте новые группы команд и команды в azd.
lifecycle-events: Подпишитесь на события жизненного цикла проекта и службы, например preprovision и postdeploy.
mcp-server: предоставьте средства протокола контекста модели (MCP) для агентов ИИ.
service-target-provider: Предоставление настраиваемых целей развертывания сервисов.
framework-service-provider: предоставляет поддержку сборки пользовательских языков и фреймворков.
provisioning-provider: предоставьте настраиваемые возможности для развертывания инфраструктуры.
validation-provider: Добавьте проверки валидации в конвейер валидации azd.
metadata: предоставлять подробные метаданные команд и конфигурации для вывода справки и IntelliSense.

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

Поддерживаемые языки

Вы можете создавать расширения azd на любом языке, который поддерживает gRPC, а azd x init включает стартовые шаблоны для нескольких языков. Go имеет самую полную поддержку, включая вспомогательные средства пакета SDK первого класса azdext , поэтому статьи в этом разделе используют Go для всех примеров.

Language	Уровень поддержки
Go	Лучшая поддержка и первоклассные инструменты SDK.
.NET (C#)	Надежная интеграция с начальным шаблоном.
Python	Хорошая интеграция с начальным шаблоном.
JavaScript	Базовая интеграция с начальным шаблоном.

Для расширений, созданных на языках, отличных от Go, можно создавать клиенты gRPC из proto-файлов в репозитории azure/azure-dev . Сведения о текущем состоянии поддержки языка см. в документации по вышестоящей платформе расширений.

Реестры расширений

Вы распространяете расширения через источники реестра или пакеты расширений. Источники реестра — это URL-адреса или манифесты на основе файлов, описывающие доступные расширения и их артефакты. Пакеты расширений — это переносимые .zip пакеты, которые можно установить непосредственно из локального файла или узла удаленно по URL-адресу HTTPS, если вы не хотите размещать реестр.

Официальный реестр предварительно настроен в azd и содержит проверенные собственные расширения. Официальные расширения разрабатываются в форке репозитория azure/azure-dev.
Источники на основе URL-адресов позволяют устанавливать из манифестов удаленного общедоступного или частного реестра.
Источники на основе файлов позволяют устанавливать из манифестов локального реестра для разработки, тестирования или автономных сценариев.
Реестры development и nightly — это необязательные источники для расширений, находящихся в разработке, и автоматически собираемых собственных расширений. Расширения в реестре разработчиков не подписываются, не охватываются поддержка Azure и могут изменяться или удаляться без уведомления.

Сведения о публикации расширения в реестре см. в статье "Публикация расширения".

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

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

Last updated on 2026-09-03