Определение манифеста расширения

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

Замечание

azd расширения в настоящее время находятся в бета-версии.

Свойства манифеста

Манифест extension.yaml поддерживает следующие свойства.

Обязательные свойства

Каждый манифест должен содержать следующие свойства:

Property	Description
id	Уникальный идентификатор расширения, например contoso.azd.tagger.
version	Семантическая версия в MAJOR.MINOR.PATCH формате.
displayName	Имя расширения, доступное для чтения человеком.
description	Подробное описание расширения.

Каждый манифест также должен содержать либо capabilities, либо dependencies. Расширение, предоставляющее команды или провайдеры, объявляет capabilities. Вместо этого пакет расширений объявляет dependencies .

Необязательные свойства

Манифест также поддерживает следующие необязательные свойства:

Property	Description
namespace	Пространство имен команд, которое группирует команды расширения, например tagger.
entryPoint	Исполняемый файл или скрипт, служащий точкой входа.
language	Язык программирования, в который записывается расширение, например go.
capabilities	Массив возможностей расширения.
usage	Инструкции по использованию расширения.
examples	Массив примеров использования с именем, описанием и использованием.
tags	Ключевые слова для классификации и фильтрации.
dependencies	Другие расширения, от которых зависит это расширение.
providers	Список поставщиков, регистрируемых расширением.
platforms	Метаданные для конкретной платформы.
mcp	Конфигурация сервера протокола контекста модели.
requiredAzdVersion	Ограничение семантического версионирования для версии azd, необходимой для использования расширения, например >= 1.24.0.

Пример манифеста

В следующем примере показан манифест extension.yaml для образца расширения Contoso Resource Tagger:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/cli/azd/extensions/extension.schema.json

id: contoso.azd.tagger
namespace: tagger
displayName: Contoso Resource Tagger
description: Standardize and report Azure resource tags for an azd project.
usage: azd tagger <command> [options]
version: 0.1.0
language: go
capabilities:
  - custom-commands

examples:
  - name: show
    description: Displays a greeting from the extension.
    usage: azd tagger show

tags:
  - tags
  - governance
  - example

Комментарий $schema в верхней части файла включает проверку и IntelliSense в редакторах, поддерживающих сервер языка YAML.

Объявление возможностей

Массив capabilities определяет, что может делать ваше расширение. azd предоставляет соответствующие разрешения во время выполнения, а некоторые службы платформы завершаются ошибкой разрешения, если возможность сопоставления не объявлена. Пример расширения начинается только с custom-commands:

capabilities:
  - custom-commands

При добавлении функциональных возможностей в других статьях вы добавите дополнительные возможности. Например, Добавить возможности расширения добавляет lifecycle-events, а Добавить сервер MCP в расширение добавляет mcp-server. Доступны следующие возможности:

• custom-commands: Добавьте новые команды в azd в вашем пространстве имён, например azd tagger show.
• lifecycle-events: Выполняйте пользовательскую логику, когда azd вызывает такие события, как preprovision или postdeploy.
• mcp-server: Предоставьте инструменты Model Context Protocol, к которым могут обращаться агенты ИИ.
• service-target-provider: добавьте пользовательскую цель развертывания для host, которую azd по умолчанию не поддерживает.
• framework-service-provider: Добавить поддержку сборки и упаковки для language, который azd по умолчанию не распознаёт.
• provisioning-provider: замените способ, которым azd подготавливает инфраструктуру, на пользовательскую реализацию.
• validation-provider: добавьте проверки, которые выполняются в конвейере проверки azd.
• metadata: предоставлять более полные метаданные команд и конфигурации для вывода справки и IntelliSense.

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

Добавление примеров использования

Массив examples описывает распространённые способы использования вашего расширения. azd показывает эти примеры, когда пользователи просматривают сведения о вашем расширении:

examples:
  - name: show
    description: Displays a greeting from the extension.
    usage: azd tagger show

Регистрация поставщиков

Если ваше расширение предоставляет пользовательские цели служб или сервисы фреймворка, объявите их в разделе providers, чтобы azd знал, что предлагает ваше расширение:

providers:
  - name: tagger
    type: service-target
    description: Deploys tagged resources to Azure.

Добавление конфигурации для конкретной платформы

platforms Используйте свойство для предоставления метаданных для конкретной платформы, таких как имя исполняемого файла для каждой операционной системы.

platforms:
  windows:
    executable: tagger.exe
  linux:
    executable: tagger
  darwin:
    executable: tagger

Объявление зависимостей

Расширения могут зависеть от других расширений с помощью массива dependencies . Зависимости поддерживают ограничения семантического версионирования:

dependencies:
  - id: microsoft.azd.core
    version: "^1.0.0"

azd устанавливает или обновляется до самой высокой версии зависимостей, которая удовлетворяет каждому ограничению и совместима с текущей azd версией на основе свойства зависимости requiredAzdVersion . Если только несовместимые выпуски удовлетворяют ограничению, azd сообщает об ошибке совместимости и предоставляет рекомендации по ее устранению. К общим форматам ограничений относятся:

• ^1.0.0: совместим с версией 1.x.x.
• ~1.2.0: совместим с версией 1.2.x.
• >=1.0.0 <2.0.0: диапазон версий.

Группируйте расширения в пакеты расширений

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

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/refs/heads/main/cli/azd/extensions/extension.schema.json

id: contoso.tools
displayName: Contoso Tools Extension Pack
description: Installs the Contoso azd extensions.
version: 0.1.0

dependencies:
  - id: contoso.azd.tagger
    version: "~0.1.0"

Установка пакета рекурсивно устанавливает его зависимости. Для каждой зависимости azd выбирает самую высокую версию, которая удовлетворяет объявленному ограничению и совместима с текущей azd версией на основе свойства зависимости requiredAzdVersion .

Связанные материалы

• Добавление возможностей расширения
• Обмен данными с azd с помощью пакета SDK
• Публикация расширения
• Справочник по фреймворку расширений