Tentukan manifes ekstensi

Setiap ekstensi Azure Developer CLI (azd) menyertakan extension.yaml manifes yang menjelaskan metadata dan kemampuannya. azd menggunakan metadata ini dalam registri ekstensi untuk membantu pengguna menemukan, menginstal, dan memahami ekstensi Anda. Artikel ini menjelaskan properti manifes dengan menggunakan ekstensi contoh Contoso Resource Tagger dari mulai cepat Membangun ekstensi contoh. Anda dapat menerapkan konsep yang sama ke ekstensi apa pun.

Nota

azd ekstensi saat ini dalam versi beta.

Properti manifest

Manifes extension.yaml mendukung properti berikut.

Properti yang diperlukan

Setiap manifes harus menyertakan properti berikut:

Property Description
id Pengidentifikasi unik untuk ekstensi, seperti contoso.azd.tagger.
version Versi semantik dalam MAJOR.MINOR.PATCH format.
displayName Nama ekstensi yang mudah dibaca oleh manusia.
description Deskripsi terperinci tentang ekstensi.

Setiap manifes juga harus menyertakan capabilities atau dependencies. Ekstensi yang menyediakan perintah atau penyedia mendeklarasikan capabilities. Paket ekstensi mendeklarasikan dependencies sebagai gantinya.

Properti yang opsional

Manifes juga mendukung properti opsional berikut:

Property Description
namespace Namespace perintah yang mengelompokkan perintah ekstensi, seperti tagger.
entryPoint Berkas yang dapat dieksekusi atau skrip yang berfungsi sebagai titik awal.
language Bahasa pemrograman yang digunakan untuk menulis ekstensi, seperti go.
capabilities Array kemampuan ekstensi.
usage Petunjuk tentang cara menggunakan ekstensi.
examples Array contoh penggunaan yang berisi nama, deskripsi, dan cara penggunaan.
tags Kata kunci untuk kategorisasi dan pemfilteran.
dependencies Ekstensi lain yang bergantung pada ekstensi ini.
providers Daftar penyedia yang didaftarkan oleh ekstensi.
platforms Metadata khusus platform.
mcp Konfigurasi server Protokol Konteks Model.
requiredAzdVersion Batasan versi semantik pada versi azd yang diperlukan untuk menggunakan ekstensi, seperti >= 1.24.0.

Contoh daftar rincian

Contoh berikut menunjukkan manifes extension.yaml untuk ekstensi contoh Contoso Resource Tagger:

# 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 Komentar di bagian atas file memungkinkan validasi dan IntelliSense di editor yang mendukung server bahasa YAML.

Mendeklarasikan kemampuan

Array capabilities menyatakan apa yang dapat dilakukan ekstensi Anda. azd memberikan izin yang sesuai saat aplikasi berjalan, dan beberapa layanan framework akan gagal dengan error izin jika kapabilitas yang sesuai tidak dideklarasikan. Ekstensi contoh dimulai hanya dengan custom-commands:

capabilities:
  - custom-commands

Saat Anda menambahkan fungsionalitas di artikel lain, Anda menambahkan lebih banyak kemampuan. Misalnya, Tambahkan kemampuan ekstensi menambahkan lifecycle-events, dan Menambahkan server MCP ke ekstensi menambahkan mcp-server. Kemampuan yang tersedia adalah:

  • custom-commands: Tambahkan perintah baru ke azd di bawah namespace Anda, seperti azd tagger show.
  • lifecycle-events: Jalankan logika kustom saat azd menaikkan peristiwa seperti preprovision atau postdeploy.
  • mcp-server: Mengekspos alat Protokol Konteks Model yang dapat dipanggil agen AI.
  • service-target-provider: Tambahkan target penyebaran kustom untuk host yang azd tidak didukung secara default.
  • framework-service-provider: Tambahkan dukungan build dan paket untuk language yang azd tidak dikenali secara default.
  • provisioning-provider: Ganti cara azd menyediakan infrastruktur dengan implementasi kustom.
  • validation-provider: Tambahkan pemeriksaan yang berjalan di azd alur validasi.
  • metadata: Berikan metadata perintah dan konfigurasi yang lebih kaya untuk output bantuan dan IntelliSense.

Untuk penjelasan yang lebih lengkap tentang setiap kemampuan dengan contoh, lihat Menambahkan kemampuan ekstensi.

Menambahkan contoh penggunaan

Array examples mendokumentasikan cara-cara umum untuk menggunakan ekstensi Anda. azd menampilkan contoh-contoh ini saat pengguna melihat detail tentang ekstensi Anda:

examples:
  - name: show
    description: Displays a greeting from the extension.
    usage: azd tagger show

Mendaftarkan penyedia

Saat ekstensi Anda menyediakan target layanan kustom atau layanan kerangka kerja, nyatakan di bagian sehingga providersazd tahu apa yang ditawarkan ekstensi Anda:

providers:
  - name: tagger
    type: service-target
    description: Deploys tagged resources to Azure.

Tambahkan konfigurasi spesifik platform

platforms Gunakan properti untuk menyediakan metadata khusus platform, seperti nama yang dapat dieksekusi untuk setiap sistem operasi.

platforms:
  windows:
    executable: tagger.exe
  linux:
    executable: tagger
  darwin:
    executable: tagger

Mendeklarasikan dependensi

Ekstensi dapat bergantung pada ekstensi lain dengan menggunakan dependencies array. Dependensi mendukung batasan penerapan versi semantik:

dependencies:
  - id: microsoft.azd.core
    version: "^1.0.0"

azd menginstal atau meningkatkan ke versi dependensi tertinggi yang memenuhi setiap batasan dan kompatibel dengan versi saat ini azd , berdasarkan properti dependensi requiredAzdVersion . Jika hanya rilis yang tidak kompatibel yang memenuhi batasan, azd laporkan kesalahan kompatibilitas dan berikan panduan untuk mengatasinya. Format batasan umum meliputi:

  • ^1.0.0: Kompatibel dengan versi 1.x.x.
  • ~1.2.0: Kompatibel dengan versi 1.2.x.
  • >=1.0.0 <2.0.0: Rentang versi.

Mengelompokkan ekstensi dengan paket ekstensi

Paket ekstensi adalah manifes yang mengelompokkan ekstensi terkait sehingga pengguna dapat menginstalnya dengan satu perintah. Paket mendeklarasikan dependencies, tetapi tidak menyediakan file eksekusi, namespace perintah, atau kapabilitasnya sendiri. Gunakan paket untuk menerbitkan sekumpulan ekstensi yang dikumpulkan, seperti rangkaian produk atau bundel skenario:

# 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"

Menginstal paket secara rekursif menginstal dependensinya. Untuk setiap dependensi, azd memilih versi tertinggi yang memenuhi batasan yang dinyatakan dan kompatibel dengan versi saat ini azd berdasarkan properti dependensi requiredAzdVersion .

Konten terkait

  • Terakhir diperbarui pada