Общие сведения о расширениях ИНТЕРФЕЙСА командной строки разработчика Azure

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

Замечание

Платформа расширений azd стала общедоступной. Отдельные расширения или возможности могут иметь собственное состояние предварительной версии.

Управление источниками расширений

Вы можете обнаруживать, устанавливать и обновлять расширения по мере роста ваших требований. Источники расширений обрабатывают распределение и управление.

• Источники расширений — это манифесты на основе файлов или URL-адресов, предоставляющие списки доступных azd расширений.
• Можно добавить пользовательские источники расширений, которые подключаются к частным, локальным или общедоступным реестрам.
• Источники расширений — это эквивалентная концепция потоков NuGet или Node.js пакета NPM и должны соответствовать официальной схеме реестра расширений.

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

• Официальный исходный реестр расширений предварительно настроен azd и размещен в https://aka.ms/azd/extensions/registry.
• Источники на основе URL ссылаются на манифесты удалённого реестра, которые ваша команда размещает для публичного или частного распространения.
• Источники на основе файлов ссылаются на манифесты локального реестра для автономного использования или локальной разработки.
• Реестры разработки и nightly — это подключаемые по выбору источники расширений в процессе разработки и автоматически собираемых расширений от разработчика. Используйте их для тестирования сценариев вместо рабочих рабочих процессов.
• Автономные файлы пакета предоставляют переносимые .zip пакеты для прямой установки из локального файла или URL-адреса HTTPS, если вы не хотите размещать реестр.

azd выполняет строгую проверку имён источников пользовательских расширений. Имена должны состоять из 1–64 строчных букв ASCII или цифр. Можно включить дефисы () и символы подчеркивания (-_) между буквами или цифрами. Имена должны начинаться и заканчиваться буквой или цифрой. azd возвращает ошибку для недопустимых имен; он не нормализует их. Имена azd и bundle зарезервированы и не могут использоваться для пользовательских источников. Имя источника должно быть допустимым при использовании с --source.

Предварительно настроенный azd источник является официальным реестром. Вы не можете удалить его или изменить его расположение.

Чтобы войти в реестр разработки, выполните следующую команду:

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

Осторожность

Расширения, размещенные в реестре разработчиков, не подписываются, не охватываются поддержка Azure и могут изменяться или удаляться без уведомления.

Команды источника расширения

Используйте следующие команды для управления источниками расширений для вашей установки azd.

Список установленных источников расширений

azd extension source list

Добавление нового источника расширения

azd extension source add -n <name> -t url -l <registry-url>

• -l, --location: расположение источника расширения.
• -n, --name: имя источника расширения. Используйте допустимое пользовательское имя источника.
• -t, --type: тип источника расширения. Поддерживаемые типы — это файл и URL-адрес.

Удаление источника расширения

azd extension source remove <name>

Невозможно удалить предварительно настроенный azd источник.

Если при обновлении сообщается об ошибке загрузки источника, вызванной устаревшим недопустимым именем источника в ~/.azd/config.json, удалите проблемный источник с помощью azd extension source remove, затем снова добавьте его с допустимым именем.

Управление расширениями

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

Перечисление расширений

azd extension list [flags]

• --installed Отображает список установленных расширений.
• --source Перечисляет только расширения из указанного источника. Имя источника должно быть допустимым зарегистрированным именем источника.
• --tags Фильтрует расширения по тегам, таким как ИИ или тест.

Установка расширения

azd extension install <extension-names> [flags]

Замените <extension-name> именем расширения, которое требуется установить.

• -v, --version Указывает точную версию для установки. Этот параметр не принимает диапазоны версий или ограничения и не может использоваться при установке автономного пакета (.zip путь к файлу или URL-адрес).
• -s, --source Указывает источник расширения, используемый для установки. Имя источника должно быть допустимым зарегистрированным именем источника.

Чтобы установить автономный пакет из URL-адреса HTTPS, укажите расположение пакета в качестве имени расширения:

azd extension install https://example.com/extensions/example.zip

• --all Обновляет все ранее установленные расширения при указании.
• -v, --version Обновляет указанное расширение до точной версии, если она указана. Этот параметр не принимает диапазоны версий или ограничения.
• -s, --source Указывает источник расширения, используемый для установки. Имя источника должно быть допустимым зарегистрированным именем источника.
• --no-dependency-updates Предотвращает обновление зависимостей, если указано.

Удаление расширения

azd extension uninstall <extension-name>

• --all Удаляет все установленные расширения при указании.

Объявление необходимых расширений в проекте

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

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

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

Общие сведения о точках интеграции расширений

Расширения могут интегрироваться с azd несколькими способами:

• Добавьте пространства имен команд с метаданными, справкой и примерами.
• Укажите схемы конфигурации и метаданные IntelliSense для файлов проекта.
• Зарегистрируйте обработчики событий жизненного цикла для рабочих процессов, таких как подготовка, пакет и развертывание.
• Добавьте поставщиков для пользовательской подготовки, проверки, целевых объектов служб и поддержки языка или платформы.
• Откройте доступ к возможностям сервера протокола Model Context Protocol (MCP) для агентов и инструментов разработчика.

Рекомендации по реализации см. в концепциях разработки расширений.

Использование расширений azd в контейнерах разработки

Функция azd контейнера разработки поддерживает extensions возможность автоматической установки списка, разделенного запятыми, расширений azd во время сборки контейнера. Расширения, установленные таким образом, доступны сразу после запуска контейнера, что сокращает необходимость ручной настройки и позволяет выполнять команды azd с уже установленными расширениями.

Для автоматической установки расширений добавьте параметр extensions в запись функции azd в файл 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"
        }
    }
}

Это extensions значение представляет собой разделенный запятыми список имен расширений azd . Установка происходит во время сборки контейнера, и, как следствие, расширения готовы к использованию сразу после запуска контейнера. После изменения списка расширений используйте команду "Перестроить и повторно открыть" в Контейнере разработки в Visual Studio Code, чтобы перестроить контейнер с обновленными расширениями.

Узнайте больше о функции контейнера azd Dev.

Дальнейшие шаги

• Краткое руководство: Использование расширения ИИ
• Основные понятия разработки расширений
• Краткое руководство: создайте пример расширения azd
• Модуль чтения платформы расширений