新增擴充功能

功能可定義 Azure 開發人員 CLI（azd）擴充功能所能執行的操作，從新增自訂命令到掛接至部署生命週期。 本文將說明如何為 Build a sample extension 快速入門中的 Contoso 資源標註器範例擴充功能新增功能。 你可以把相同的模式套用到任何擴充功能上。

每個能力都需要兩個條件：在capabilities陣列中加入一個項目，以及擴充程式碼中對應的實作。

Note

azd擴充框架已普遍提供。 個別擴充功能或功能可能有自己的預覽狀態。 關於 GA 的詳細資訊，請參閱 Generally Available： Azure Developer CLI （azd） Extension Framework.

可用功能

azd 擴充功能可宣告以下功能：

  • custom-commands：在延伸模組的命名空間下，將新的命令和命令群組新增至 azd。 例如，範例擴充功能會加入 azd tagger show。 利用此功能來公開使用者直接從命令列執行的任務。
  • lifecycle-events：訂閱 azd 在執行時所引發的事件，例如 preprovision、postprovision 或 postdeploy。 你的擴充功能會在這些節點執行自訂邏輯，使用者不需要直接呼叫。 例如，範例擴充功能會在建立任何資源之前，檢查 preprovision 上是否有所需的標籤。
  • service-target-provider： 註冊一個新的部署目標，因此 azd 知道如何將服務打包並部署到它不支援的主機上。 服務目標對應至 host 中的 azure.yaml 值。 例如，你可以新增一個將服務部署到第三方平台或內部主機環境的供應商。
  • framework-service-provider： 註冊語言或框架的支援，因此 azd 知道如何還原、建置及打包該專案類型。 這對應於 language 中的 azure.yaml值。 例如，你可以為一種預設不識別的語言 azd 加入 build 支援。
  • provisioning-provider：取代 azd 在 azd provision 和 azd up 期間佈建基礎結構的方式。 不是由內建的 Bicep 或 Terraform 流程決定，而是由你的擴充功能決定會發生什麼事。 例如，你可以整合不同的基礎設施即程式碼工具或自訂部署 API。
  • validation-provider：將針對專案或環境執行的檢查新增至 azd 驗證管線。 例如，你可以在部署前確認命名慣例、必備標籤或安全設定是否已到位。
  • mcp-server： 將你的擴充功能以模型上下文協定（MCP）工具的形式揭露，AI 代理（如 GitHub Copilot）可以發現並呼叫。 例如，範例擴充可以提供 suggest_tags 工具。 欲了解更多資訊，請參閱 「新增 MCP 伺服器至擴充功能」。
  • metadata：提供更豐富的指令和組態中繼資料，供 azd 用來描述你的延伸模組，例如會顯示在說明輸出和 IntelliSense 中的詳細指令描述與組態提示。

本文聚焦於兩種最常見的功能：自訂指令與生命週期事件。 如需了解 mcp-server 功能，請參閱 將 MCP 伺服器新增至擴充功能。 欲了解提供者功能的完整細節，請參閱擴充框架參考。

新增自訂指令

這個 custom-commands 功能讓你的擴充功能能在 的命名空間 azd下註冊新指令。 範例擴充功能已經將這項功能用於 azd tagger show 命令。

  1. 在 extension.yaml 中宣告該能力。

    capabilities:
  - custom-commands

  2. 使用 azdext.NewExtensionRootCommand 輔助程式來建立指令，它會註冊標準的 azd 旗標和環境變數處理功能，因此您不必手動宣告它們：

    import "github.com/azure/azure-dev/cli/azd/pkg/azdext"

func NewRootCommand() *cobra.Command {
    rootCmd, extCtx := azdext.NewExtensionRootCommand(azdext.ExtensionCommandOptions{
        Name:  "tagger",
        Use:   "tagger <command> [options]",
        Short: "Standardize and report Azure resource tags.",
    })

    rootCmd.AddCommand(newShowCommand(extCtx))
    // Add other subcommands here.
    return rootCmd
}

    輔助程式會回傳一個 *ExtensionContext，其中提供標準旗標的已解析值，例如 Environment 和 OutputFormat。 將上下文傳給子命令，並在其 RunE 處理常式中讀取，而不要重新宣告標準旗標。

訂閱生命週期事件

此功能lifecycle-events允許你的擴充功能在專案及服務生命週期事件中執行自訂邏輯，例如preprovisionpostdeploy。 對於此範例擴充功能，請使用 preprovision 事件確認已先設定所需標籤，再由 azd 佈建任何資源。

  1. 在 extension.yaml 中宣告該能力。

    capabilities:
  - custom-commands
  - lifecycle-events

  2. 在你的擴充功能中新增 listen 指令。 azd 呼叫此指令以建立用於事件的雙向連線。 使用建構器 azdext.NewExtensionHost 註冊你的事件處理者：

    func newListenCommand() *cobra.Command {
    return &cobra.Command{
        Use:    "listen",
        Short:  "Starts the extension and listens for azd events.",
        Hidden: true,
        RunE: func(cmd *cobra.Command, args []string) error {
            ctx := azdext.WithAccessToken(cmd.Context())

            azdClient, err := azdext.NewAzdClient()
            if err != nil {
                return fmt.Errorf("failed to create azd client: %w", err)
            }
            defer azdClient.Close()

            host := azdext.NewExtensionHost(azdClient).
                WithProjectEventHandler(
                    "preprovision",
                    func(ctx context.Context, args *azdext.ProjectEventArgs) error {
                        fmt.Printf("Verifying required tags for project: %s\n", args.Project.Name)
                        // Add your tag validation logic here.
                        return nil
                    },
                )

            // Run blocks until azd closes the connection.
            if err := host.Run(ctx); err != nil {
                return fmt.Errorf("failed to run extension: %w", err)
            }

            return nil
        },
    }
}

  3. 在你的根指令上註冊該 listen 指令：

    rootCmd.AddCommand(newListenCommand())

當使用者執行 azd provision 或 azd up 時，azd 會叫用您的擴充功能，並在配置資源之前呼叫 preprovision 處理常式。

過濾服務事件

服務事件處理器支援可選的過濾功能，因此你只能處理特定類型的服務。 例如，你可以只處理 prepackage Python 容器應用服務的事件：

host := azdext.NewExtensionHost(azdClient).
    WithServiceEventHandler(
        "prepackage",
        func(ctx context.Context, args *azdext.ServiceEventArgs) error {
            fmt.Printf("Packaging service: %s\n", args.Service.Name)
            return nil
        },
        &azdext.ServiceEventOptions{
            Host:     "containerapp",
            Language: "python",
        },
    )

重建與測試

新增功能後，重新建置擴充功能並測試新的行為：

  1. 如果你使用監看程式，你所做的變更會自動重新建置。 否則，請手動建造：

    azd x build

  2. 測試能力。 對於生命週期事件，執行觸發該事件的指令，例如 azd provision。

相關內容

  • Last updated on