擴充功能開發概念

Azure Developer CLI （azd） 擴充功能可新增指令、自動化工作流程，並整合其他服務。azd 本文說明了在建構擴充功能前你需要了解的概念，例如開發工具、軟體開發套件（SDK），以及如何 azd 與執行中的擴充套件溝通。 想從使用者角度了解擴充功能是什麼，請參閱 擴充功能概覽。

開發者擴充功能

建立擴充功能最快的方法就是使用 azd developer 擴充功能（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 Token（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框架服務，如 Project、Environment、Account 及 Prompt 服務。
  • 透過 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