Menambahkan kemampuan ekstensi

Kemampuan menentukan apa yang dapat dilakukan ekstensi Azure Developer CLI (azd), dari menambahkan perintah kustom hingga menghubungkan ke siklus hidup penyebaran. Artikel ini menjelaskan cara menambahkan kapabilitas ke ekstensi contoh Contoso Resource Tagger dari quickstart Membuat ekstensi contoh. Anda dapat menerapkan pola yang sama ke ekstensi apa pun.

Setiap kemampuan memerlukan dua hal: entri dalam capabilities array manifes ekstensi Anda, dan implementasi yang sesuai dalam kode ekstensi Anda.

Nota

azd Kerangka kerja ekstensi umumnya tersedia. Setiap ekstensi atau kemampuan mungkin memiliki status pratinjau tersendiri. Untuk detail tentang GA, lihat Ketersediaan Umum: Azure Developer CLI (azd) Extension Framework.

Kemampuan yang tersedia

azd ekstensi dapat mendeklarasikan kemampuan berikut:

custom-commands: Menambahkan perintah dan grup perintah baru ke azd di bawah namespace ekstensi Anda. Misalnya, ekstensi sampel menambahkan azd tagger show. Gunakan kemampuan ini untuk mengekspos tugas yang dijalankan pengguna langsung dari baris perintah.
lifecycle-events: Berlangganan ke event yang dimunculkan azd selama berjalan, seperti preprovision, postprovision, atau postdeploy. Ekstensi Anda menjalankan logika kustom di titik-titik tersebut tanpa pengguna memanggilnya secara langsung. Misalnya, ekstensi contoh memeriksa tag yang diperlukan pada preprovision sebelum sumber daya apa pun dibuat.
service-target-provider: Mendaftarkan target deployment baru sehingga azd tahu cara mengemas dan men-deploy layanan ke host yang secara bawaan tidak didukung. Target layanan dipetakan ke nilai host dalam azure.yaml. Misalnya, Anda dapat menambahkan penyedia yang menyebarkan layanan ke platform pihak ketiga atau lingkungan hosting internal.
framework-service-provider: Mendaftarkan dukungan untuk bahasa atau kerangka kerja sehingga azd tahu cara memulihkan, membangun, dan mengemas jenis proyek tersebut. Ini sesuai dengan nilai language di azure.yaml. Misalnya, Anda dapat menambahkan dukungan build untuk bahasa yang azd tidak dikenali secara default.
provisioning-provider: Menggantikan cara azd menyediakan infrastruktur selama azd provision dan azd up. Alih-alih alur Bicep atau Terraform bawaan, ekstensi Anda menentukan apa yang terjadi. Misalnya, Anda dapat mengintegrasikan alat infrastruktur sebagai kode yang berbeda atau API penyebaran kustom.
validation-provider: Menyumbangkan pemeriksaan ke alur validasi azd yang dijalankan pada proyek atau lingkungan. Misalnya, Anda dapat memverifikasi bahwa konvensi penamaan, tag yang diperlukan, atau pengaturan keamanan ada sebelum penyebaran dilanjutkan.
mcp-server: Menyediakan fungsionalitas ekstensi Anda sebagai alat Model Context Protocol (MCP) yang dapat ditemukan dan dipanggil oleh agen AI, seperti GitHub Copilot. Misalnya, ekstensi contoh dapat menyediakan alat suggest_tags. Untuk informasi selengkapnya, lihat Menambahkan server MCP ke ekstensi.
metadata: Menyediakan metadata perintah dan konfigurasi yang lebih kaya yang azd menggunakan untuk menjelaskan ekstensi Anda, seperti deskripsi perintah terperinci dan petunjuk konfigurasi yang muncul dalam output bantuan dan IntelliSense.

Artikel ini berfokus pada dua kemampuan paling umum: perintah kustom dan peristiwa siklus hidup. Untuk kemampuannya mcp-server , lihat Menambahkan server MCP ke ekstensi. Untuk detail lengkap tentang kemampuan penyedia, lihat referensi kerangka kerja ekstensi.

Menambahkan perintah kustom

Kemampuan custom-commands ini memungkinkan ekstensi Anda untuk mendaftarkan perintah baru di bawah namespace di azd. Ekstensi sampel sudah menggunakan kemampuan ini untuk perintah azd tagger show.

Deklarasikan kemampuan dalam extension.yaml.
```
capabilities:
  - custom-commands
```
Buat perintah Anda dengan menggunakan pembantu azdext.NewExtensionRootCommand , yang mendaftarkan bendera standar azd dan penanganan variabel lingkungan sehingga Anda tidak perlu mendeklarasikannya secara manual:
```
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
}
```
Fungsi pembantu ini mengembalikan *ExtensionContext yang menyediakan nilai flag standar yang telah ditetapkan, seperti Environment dan OutputFormat. Teruskan konteks ke subperintah Anda dan akses konteks tersebut di dalam handler RunE alih-alih mendeklarasikan ulang flag standar.

Kemampuan ini lifecycle-events memungkinkan ekstensi Anda menjalankan logika kustom selama peristiwa siklus hidup proyek dan layanan, seperti preprovision atau postdeploy. Untuk ekstensi sampel, gunakan event preprovision untuk memverifikasi bahwa tag yang diperlukan telah ditetapkan sebelum azd memprovisikan sumber daya apa pun.

Deklarasikan kemampuan dalam extension.yaml.

capabilities:
  - custom-commands
  - lifecycle-events

listen Tambahkan perintah ke ekstensi Anda. azd memanggil perintah ini untuk membuat koneksi dua arah yang digunakan untuk peristiwa. Gunakan penyusun azdext.NewExtensionHost untuk mendaftarkan penanganan aktivitas Anda:

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
        },
    }
}

Daftarkan listen perintah pada perintah root Anda:
```
rootCmd.AddCommand(newListenCommand())
```

Saat pengguna menjalankan azd provision atau azd up, azd memanggil ekstensi Anda dan memanggil preprovision handler sebelum menyediakan sumber daya.

Memfilter peristiwa layanan

Penanganan aktivitas layanan mendukung pemfilteran opsional sehingga Anda hanya menangani jenis layanan tertentu. Misalnya, Anda dapat menangani peristiwa prepackage hanya untuk layanan aplikasi kontainer 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",
        },
    )

Membangun kembali dan menguji

Setelah Anda menambahkan kemampuan, bangun ulang ekstensi dan uji perilaku baru:

Jika Anda menggunakan watcher, perubahan Anda akan dibangun ulang secara otomatis. Jika tidak, bangun secara manual:
```
azd x build
```
Uji kemampuannya. Untuk peristiwa siklus hidup, jalankan perintah yang memicu peristiwa, seperti azd provision.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-09-10