扩展开发概念

Azure开发人员 CLI （azd） 扩展添加新命令，自动化工作流，并将其他服务与azd集成。 本文介绍在生成扩展之前需要了解的概念，例如开发人员工具、软件开发工具包（SDK）以及如何 azd 与正在运行的扩展进行通信。 若要从用户的角度了解哪些扩展，请参阅 扩展概述。

开发者扩展

生成扩展的最快方法是使用 azd 开发人员扩展（microsoft.azd.extensions）。 开发者扩展在 azd x 命名空间下添加了一组命令，用于生成脚手架、构建、打包和发布你的扩展：

命令 Description
azd x init 用所选语言搭建新的扩展项目。
azd x build 生成用于本地开发的扩展二进制文件。
azd x watch 监视项目进行更改，并自动重新生成并安装扩展。
azd x pack 打包扩展工件，为发布做好准备。
azd x release 为扩展创建GitHub版本。
azd x publish 使用新的扩展元数据更新扩展注册表。

“构建示例扩展”快速入门将向你展示如何安装开发者扩展，并为你的第一个扩展生成脚手架。

开发人员扩展支持基于注册表的发布工作流和可移植捆绑包分发。 使用 azd x pack 创建用于发布版本和发布到注册表的平台工件，或者在您需要共享扩展而无需托管注册表时，创建独立的 .zip 包。 可以从本地文件安装捆绑包，也可以在 HTTPS URL 中远程托管。 有关分步指南，请参阅 发布扩展。

扩展框架与 gRPC

azd 和扩展作为彼此独立的进程运行，并通过 gRPC 通信。 调用扩展命令时，将执行以下步骤：

  1. azd 在随机端口上启动 gRPC 服务器，并使用服务器地址设置 AZD_SERVER 环境变量。
  2. azd 设置 AZD_ACCESS_TOKEN 环境变量，该环境变量是一个已签名的 JSON Web 令牌 （JWT），该令牌在命令的生存期内授予对 azd 服务的扩展访问权限。
  3. azd 调用扩展命令并传递当前参数、标志和环境变量。
  4. 你的扩展使用 gRPC 客户端通过框架服务与 azd 通信，例如提示用户或读取项目配置。
  5. azd 等待命令完成并报告非零退出代码作为错误。

此模型允许扩展以一致、安全的方式进行交互 azd ，而无需直接访问内部 azd 状态。

项目级扩展要求

项目可以在 azure.yaml 中声明所需的扩展。 使用节 requiredVersions.extensions 列出扩展 ID 和版本约束，以便 azd 可以解析满足项目的版本。

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

当项目依赖于扩展提供的主机、提供程序、生命周期处理程序、验证或命令时声明所需的扩展。 有关确切的架构和支持的版本语法，请参阅 requiredVersions。

The azdext SDK

包 azdext 是扩展框架的 Go SDK。 它提供处理通信详细信息的 gRPC 客户端和帮助程序，以便你可以专注于扩展逻辑。 SDK 包括以下帮助程序：

  • 生成注册标准 azd 标志和环境变量处理的根命令。
  • 将 azd 访问令牌附加到发出的请求中。
  • 调用 azd 框架服务，例如项目、环境、账户和提示词服务。
  • 通过 TelemetryService.ReportUsage gRPC API 报告官方来源扩展的已命名使用事件。 有关 API 使用情况详细信息，请参阅 使用 SDK 与 azd 通信。
  • 通过扩展主机注册生命周期事件处理程序和自定义提供程序。

若要了解如何从扩展调用 azd 服务，请参阅 使用 SDK 与 azd 通信。

扩展功能

功能声明扩展可以执行的操作。 在清单中 extension.yaml 列出扩展的功能，并在 azd 运行时授予相应的权限。 可用功能包括：

  • custom-commands：将新的命令组和命令添加到 azd。
  • lifecycle-events：订阅项目和服务生命周期事件，例如 preprovision 和 postdeploy。
  • mcp-server：为 AI 代理提供模型上下文协议 （MCP） 工具。
  • service-target-provider：提供自定义服务部署目标。
  • framework-service-provider：提供自定义语言和框架生成支持。
  • provisioning-provider：提供自定义基础结构预配体验。
  • validation-provider：为 azd 验证管道贡献验证检查。
  • metadata：为帮助输出和 IntelliSense 提供丰富的命令和配置元数据。

若要了解如何向扩展添加功能，请参阅 “添加扩展功能”。

支持的语言

可以使用支持 gRPC 的任何语言生成 azd 扩展，并 azd x init 包括多种语言的初学者模板。 Go 具有最完整的支持，包括一流的 azdext SDK 帮助程序，因此本部分中的文章对所有示例都使用 Go。

语言 支持级别
Go 最佳支持服务和一流的 SDK 辅助工具。
.NET （C#） 与入门模板深度集成。
Python 与入门模板集成良好。
JavaScript 与入门模板的基本集成。

对于以 Go 以外的语言编写的扩展，可以从存储库中的 azure/azure-dev生成 gRPC 客户端。 有关语言支持的当前状态，请参阅上游 扩展框架文档。

扩展注册表

可以通过注册表源或扩展捆绑包分发扩展。 注册表源是基于 URL 或文件的清单，用于描述可用扩展及其工件。 扩展捆绑包是可移植 .zip 包，当你不想托管注册表时，可以直接从本地文件或主机远程安装在 HTTPS URL 中。

  • 官方注册表已在azd中预先配置，并托管经过审核的官方扩展。 官方扩展是在 azure/azure-dev 存储库的派生副本中开发的。
  • 基于 URL 的源 允许从远程公共或专用注册表清单进行安装。
  • 基于文件的源 允许从本地注册表清单进行安装，以便开发、测试或脱机方案。
  • 开发和每日构建注册表是用于获取正在开发且自动构建的第一方扩展的选择加入源。 开发注册表中的扩展是未签名的，Azure 支持未涵盖，可以更改或删除，而无需通知。

若要了解如何将扩展发布到注册表，请参阅 发布扩展。

相关内容

  • Last updated on