快速入门：生成示例 azd 扩展

在本快速入门中，你将构建一个名为 Contoso 资源标记器的示例 Azure Developer CLI（azd）扩展。 使用 azd 开发人员扩展为 Go 项目搭建基架，添加自定义命令，并在本地运行扩展。 你创建的示例扩展是本部分中其他文章的起点，其中介绍了如何添加功能、通信 azd、添加模型上下文协议（MCP）服务器并发布工作。

若要在开始之前了解扩展开发背后的概念，请参阅 扩展开发概念。

Note

扩展 azd 框架已正式发布。 单个扩展或功能可能具有自己的预览状态。

先决条件

azd 默认包含官方扩展源。 还可以从基于 URL 或基于文件的源、本地开发注册表、选择加入开发或夜间注册表以及可移植 .zip 捆绑包安装扩展。 有关详细信息，请参阅 扩展开发概念。

Tip

azd如果项目依赖于扩展提供的主机、提供程序、验证、生命周期处理程序或命令，请使用azure.yaml版本约束声明这些所需的扩展。 有关详细信息，请参阅 requiredVersions。

安装开发人员扩展

azd 开发人员扩展（microsoft.azd.extensions）提供用于构建扩展的 azd x 命令。

  1. 从官方扩展源安装开发人员扩展：

    azd extension install microsoft.azd.extensions

  2. 验证是否已安装扩展：

    azd extension list --installed

    开发者扩展在 x 命名空间下注册了一组命令。 运行 azd x 以查看可用的命令。

搭建示例扩展基架

使用 azd x init 该命令为新的扩展项目搭建基架。

  1. 为你的扩展创建一个目录并切换到该目录：

    mkdir azd-extensions
cd azd-extensions

  2. 初始化 git 存储库并创建初始提交。 此命令 azd x init 要求 git 跟踪扩展文件夹：

    git init
git commit --allow-empty -m "Initial commit"

  3. 运行命令 azd x init 来搭建扩展基架：

    azd x init

  4. 出现提示时，请提供以下值：

    提示 Value
    扩展 ID contoso.azd.tagger
    显示名称 Contoso Resource Tagger
    Description Standardize and report Azure resource tags for an azd project.
    命名空间 tagger
    能力 Custom commands
    语言 Go

该命令搭建扩展基架，生成初始二进制文件，打包扩展，将其发布到本地扩展源，并将其安装在本地以供立即使用。

浏览项目结构

该 azd x init 命令生成具有以下关键文件的项目：

contoso.azd.tagger/
├── bin/                    # Contains built binaries
├── build.ps1               # Windows build script
├── build.sh                # Unix build script
├── CHANGELOG.md            # Version history and release notes
├── extension.yaml          # Extension metadata and capabilities
├── main.go                 # Entry point for the extension
├── go.mod                  # Go module definition
└── internal/               # Internal implementation code

最重要的文件包括：

  • extension.yaml：定义扩展的元数据、功能和命令。 若要了解详细信息，请参阅 “定义扩展清单”。
  • main.go：运行您的扩展的根命令的入口点。
  • build.sh和build.ps1：跨平台生成脚本，为每个受支持的平台（Linux、Windows 和 macOS）编译单独的二进制文件。
  • CHANGELOG.md：记录版本之间的更改，并在发布时提供发布说明。

添加自定义命令

添加一个 show 命令，用于打印问候语以验证扩展是否正常工作。 确切的文件布局取决于初学者模板，但模式相同：定义 Cobra 命令并在根命令上注册它。

  1. 在 internal/cmd 目录中，创建包含以下内容的命名 show.go 文件：

    package cmd

import (
    "fmt"

    "github.com/spf13/cobra"
)

func newShowCommand() *cobra.Command {
    return &cobra.Command{
        Use:   "show",
        Short: "Displays a greeting from the Contoso Resource Tagger extension.",
        RunE: func(cmd *cobra.Command, args []string) error {
            fmt.Println("Hello from the Contoso Resource Tagger extension!")
            return nil
        },
    }
}

  2. 在根命令上注册命令。 在 internal/cmd/root.go 文件中，在文件底部附近、其他 AddCommand 函数之后添加以下这一行：

    rootCmd.AddCommand(newShowCommand())

运行扩展

在运行该扩展之前，将其打包并发布到本地扩展源以注册更改。

  1. 打包扩展程序：

    azd x pack

  2. 发布扩展以注册它：

    azd x publish

  3. 运行新命令：

    azd tagger show

    输出如以下示例所示：

    Hello from the Contoso Resource Tagger extension!

现在，你已经有了一个可用的扩展，可以在此基础上继续开发。

监视开发过程中的更改

与其在每次更改后手动运行azd x pack和azd x publish，不如使用azd x watch，以便在开发过程中自动构建并安装该扩展。

  1. 从扩展目录中启动观察程序：

    azd x watch

  2. 在第二个终端中，运行相应命令，以便在进行更改的过程中测试这些更改：

    azd tagger show

若要手动生成扩展而不是使用观察程序，请运行 azd x build。

清理资源

完成试验后，请卸载示例扩展：

azd extension uninstall contoso.azd.tagger

相关内容

若要继续基于示例扩展进行构建，请参阅以下文章。 每篇文章都是独立的，因此你可以按任意顺序完成它们：

  • Last updated on