每個 Azure Developer CLI (azd) 擴充功能都包含一個 extension.yaml 資訊清單，用來描述其中繼資料和功能。
azd 利用這些元資料在擴充功能登錄檔中幫助使用者發現、安裝並理解你的擴充功能。 本文將使用 Build a sample extension 快速入門中的 Contoso 資源標註器範例擴充來解釋 manifest 屬性。 你可以把同樣的概念套用到任何擴充功能上。
Note
azd 擴展目前處於測試階段。
顯現性質
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 伺服器則 會 mcp-server增加 。 可用的功能包括：
-
custom-commands： 在azd你的命名空間下方新增指令，例如azd tagger show。 -
lifecycle-events：當azd引發如preprovision或postdeploy等事件時，執行自訂邏輯。 -
mcp-server：公開模型情境協定工具，AI 代理可呼叫。 -
service-target-provider：為host預設不支援的azd新增自訂部署目標。 -
framework-service-provider：為language新增建置與封裝支援，而azd預設並不識別該裝置。 -
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 安裝或升級至滿足每個約束且與當前 azd 版本相容的最高相依版本，依據相依 requiredAzdVersion 屬性。 若僅不相容版本符合限制， 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 根據依賴性質，選擇最高版本，滿足宣告約束且與當前 azd 版本 requiredAzdVersion 相容。