Konsep pengembangan ekstensi

ekstensi Azure Developer CLI (azd) menambahkan perintah baru, mengotomatiskan alur kerja, dan mengintegrasikan layanan lain dengan azd. Artikel ini menjelaskan konsep yang perlu Anda pahami sebelum membuat ekstensi, seperti alat pengembang, kit pengembangan perangkat lunak (SDK), dan cara azd berkomunikasi dengan ekstensi yang sedang berjalan. Untuk mempelajari ekstensi apa dari perspektif pengguna, lihat gambaran umum ekstensi.

Ekstensi pengembang

Cara tercepat untuk membangun ekstensi adalah dengan menggunakan azd ekstensi pengembang (microsoft.azd.extensions). Ekstensi pengembang menambahkan serangkaian perintah di bawah namespace azd x yang menghasilkan kerangka, membangun, mengemas, dan menerbitkan ekstensi Anda:

Command	Description
`azd x init`	Membuat kerangka proyek ekstensi baru dengan bahasa pilihan Anda.
`azd x build`	Membangun biner ekstensi untuk pengembangan lokal.
`azd x watch`	Mengawasi proyek untuk perubahan dan secara otomatis membangun kembali dan menginstal ekstensi.
`azd x pack`	Mengemas artefak ekstensi untuk dipublikasikan.
`azd x release`	Membuat rilis GitHub untuk ekstensi.
`azd x publish`	Memperbarui registri ekstensi dengan metadata ekstensi baru.

Panduan cepat Membuat ekstensi sampel menunjukkan cara menginstal ekstensi pengembang dan membuat kerangka awal untuk ekstensi pertama Anda.

Ekstensi pengembang mendukung alur kerja penerbitan berbasis registri dan distribusi bundel portabel. Gunakan azd x pack untuk membuat artefak platform agar dapat dipublikasikan sebagai rilis dan ke registri, atau buat bundel .zip mandiri saat Anda perlu membagikan ekstensi tanpa harus menghosting registri. Bundel dapat diinstal dari file lokal atau dihosting dari jarak jauh di URL HTTPS. Untuk panduan langkah demi langkah, lihat Menerbitkan ekstensi.

Kerangka kerja ekstensi dan gRPC

azd dan ekstensi berjalan sebagai proses terpisah yang berkomunikasi melalui gRPC. Saat Anda memanggil perintah ekstensi, langkah-langkah berikut terjadi:

azd memulai server gRPC pada port acak dan mengatur AZD_SERVER variabel lingkungan dengan alamat server.
azd AZD_ACCESS_TOKEN mengatur variabel lingkungan, yang merupakan JSON Web Token (JWT) yang ditandatangani yang memberikan akses ekstensi ke azd layanan selama masa pakai perintah.
azd memanggil perintah ekstensi Anda dan meneruskan argumen, bendera, dan variabel lingkungan saat ini.
Ekstensi Anda menggunakan klien gRPC untuk berkomunikasi kembali azd melalui layanan kerangka kerja, seperti meminta pengguna atau membaca konfigurasi proyek.
azd menunggu hingga perintah selesai dan melaporkan kode keluar nonnol sebagai kesalahan.

Model ini memungkinkan ekstensi berinteraksi dengan dengan azd cara yang konsisten dan aman tanpa langsung mengakses status internal azd .

Persyaratan ekstensi tingkat proyek

Proyek dapat mendeklarasikan ekstensi yang mereka butuhkan di azure.yaml. Gunakan bagian requiredVersions.extensions untuk mencantumkan ID ekstensi dan batasan versi sehingga azd dapat menyelesaikan versi yang memenuhi proyek.

requiredVersions:
  extensions:
    azure.ai.agents: ">=1.0.0"
    contoso.azd.tagger: "^2.0.0"

Deklarasikan ekstensi yang diperlukan ketika proyek bergantung pada host, penyedia, penangan siklus hidup, validasi, atau perintah yang disediakan ekstensi. Untuk skema yang tepat dan sintaks versi yang didukung, lihat requiredVersions.

The azdext SDK

Paket azdext ini adalah Go SDK untuk kerangka kerja ekstensi. Ini menyediakan klien dan pembantu gRPC yang menangani detail komunikasi untuk Anda, sehingga Anda dapat fokus pada logika ekstensi Anda. SDK mencakup pembantu untuk:

Buat perintah root yang mendaftarkan bendera standar azd dan penanganan variabel lingkungan.
Sertakan azd token akses ke permintaan yang dikirim.
Panggil layanan azd framework, seperti layanan Project, Environment, Account, dan Prompt.
Laporkan peristiwa penggunaan yang diberi nama melalui API gRPC TelemetryService.ReportUsage untuk ekstensi dari sumber resmi. Untuk detail penggunaan API, lihat Berkomunikasi dengan azd dengan menggunakan SDK.
Daftarkan penanganan aktivitas siklus hidup dan penyedia kustom melalui host ekstensi.

Untuk mempelajari cara memanggil azd layanan dari ekstensi Anda, lihat Berkomunikasi dengan azd dengan menggunakan SDK.

Kemampuan ekstensi

Kapabilitas menyatakan apa yang dapat dilakukan oleh ekstensi. Mencantumkan kemampuan ekstensi dalam manifesnya extension.yaml , dan azd memberikan izin yang sesuai saat runtime. Kemampuan yang tersedia meliputi:

custom-commands: Tambahkan grup perintah dan perintah baru ke azd.
lifecycle-events: Berlangganan ke peristiwa siklus hidup proyek dan layanan, seperti preprovision dan postdeploy.
mcp-server: Menyediakan alat Protokol Konteks Model (MCP) untuk agen AI.
service-target-provider: Berikan target penyebaran layanan kustom.
framework-service-provider: Menyediakan dukungan build kustom untuk bahasa dan framework.
provisioning-provider: Memberikan pengalaman provisi infrastruktur kustom.
validation-provider: Tambahkan pemeriksaan validasi ke dalam azd pipeline validasi.
metadata: Berikan metadata perintah dan konfigurasi yang kaya untuk output bantuan dan IntelliSense.

Untuk mempelajari cara menambahkan kemampuan ke ekstensi, lihat Menambahkan kemampuan ekstensi.

Bahasa yang didukung

Anda dapat membangun azd ekstensi dalam bahasa apa pun yang mendukung gRPC, dan azd x init menyertakan templat pemula untuk beberapa bahasa. Go memiliki dukungan paling lengkap, termasuk pembantu SDK kelas azdext satu, sehingga artikel di bagian ini menggunakan Go untuk semua contoh.

Bahasa	Tingkat dukungan
Go	Dukungan terbaik dan pembantu SDK kelas satu.
.NET (C#)	Integrasi kuat dengan templat awal.
Python	Integrasi yang baik dengan templat awal.
JavaScript	Integrasi dasar dengan templat awal.

Untuk ekstensi yang ditulis dalam bahasa selain Go, Anda dapat menghasilkan klien gRPC dari file proto di azure/azure-dev repositori. Untuk status dukungan bahasa saat ini, lihat dokumentasi upstream framework ekstensi.

Registri ekstensi

Anda mendistribusikan ekstensi melalui sumber registri atau bundel ekstensi. Sumber registri adalah manifes berbasis URL atau berbasis file yang menjelaskan ekstensi yang tersedia dan artefaknya. Bundel ekstensi adalah paket portabel .zip yang dapat Anda instal langsung dari file lokal atau host dari jarak jauh di URL HTTPS saat Anda tidak ingin menghosting registri.

registri resmi sudah dikonfigurasi sebelumnya di azd dan menampung ekstensi pihak pertama yang telah diverifikasi. Ekstensi resmi dikembangkan di fork dari repositori azure/azure-dev.
Sumber berbasis URL memungkinkan Anda menginstal dari manifes registri publik atau privat jarak jauh.
Sumber berbasis file memungkinkan Anda menginstal dari manifes registri lokal untuk skenario pengembangan, pengujian, atau offline.
Registri pengembangan dan nightly adalah sumber opsional untuk ekstensi pihak pertama yang masih dalam pengembangan dan dibangun secara otomatis. Ekstensi dalam registri dev tidak ditandatangani, tidak dicakup oleh Azure support, dan dapat berubah atau dihapus tanpa pemberitahuan.

Untuk mempelajari cara menerbitkan ekstensi ke registri, lihat Menerbitkan ekstensi.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-09-04