定义扩展清单

每个 Azure Developer CLI（azd）扩展都包含一个用于描述其元数据和功能的 extension.yaml 清单。 azd 使用此扩展注册表中的元数据来帮助用户发现、安装和了解扩展。 本文使用创建示例扩展快速入门中的 Contoso 资源标记器示例扩展来解释清单属性。 可以将相同的概念应用于任何扩展。

Note

azd 扩展目前以 beta 版提供。

清单属性

清单 extension.yaml 支持以下属性。

必需的属性

每个清单都必须包含以下属性：

财产 Description
id 扩展的唯一标识符，例如 contoso.azd.tagger。
version 采用 MAJOR.MINOR.PATCH 格式的语义化版本。
displayName 扩展程序的便于用户识别的名称。
description 扩展的详细说明。

每个清单还必须包含 capabilities 或 dependencies 之一。 提供命令或提供程序的扩展会声明 capabilities。 扩展包则声明dependencies。

可选属性

清单还支持以下可选属性：

财产 Description
namespace 对扩展命令进行分组的命令命名空间，例如 tagger。
entryPoint 作为入口点的可执行文件或脚本。
language 编写该扩展所用的编程语言，例如 go。
capabilities 扩展能力数组。
usage 有关如何使用扩展的说明。
examples 具有名称、说明和用法的用法示例数组。
tags 用于分类和筛选的关键字。
dependencies 此扩展所依赖的其他扩展。
providers 扩展注册的提供程序列表。
platforms 特定于平台的元数据。
mcp 模型上下文协议服务器配置。
requiredAzdVersion 对使用扩展所需的 azd 版本的语义版本约束，例如 >= 1.24.0。

示例清单

以下示例展示了用于 Contoso 资源标记器示例扩展的 extension.yaml 清单：

# 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 注释可在支持 YAML 语言服务器的编辑器中启用验证和 IntelliSense。

声明能力

数组 capabilities 声明扩展可以执行的操作。 azd 在运行时授予相应的权限，如果未声明匹配功能，某些框架服务将失败并显示权限错误。 示例扩展仅以 custom-commands 开头：

capabilities:
  - custom-commands

随着你在其他几篇文章中添加更多功能，你也会获得更多能力。 例如，添加扩展功能添加lifecycle-events，并向扩展添加 mcp-server。 可用的功能包括：

  • custom-commands：将新命令添加到 azd 命名空间下，例如 azd tagger show。
  • lifecycle-events：当 azd 触发类似 preprovision 或 postdeploy 的事件时，运行自定义逻辑。
  • mcp-server：公开 AI 代理可以调用的模型上下文协议工具。
  • service-target-provider：为 azd 默认不支持的 host 添加自定义部署目标。
  • framework-service-provider：为默认情况下azd无法识别的language添加生成和打包支持。
  • 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安装或升级到满足每个约束的最高依赖项版本，并根据依赖项requiredAzdVersion的属性与当前azd版本兼容。 如果仅不兼容的版本满足约束， 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选择满足声明约束的最高版本，并根据依赖项requiredAzdVersion的属性与当前azd版本兼容。

相关内容

  • 上次更新时间为