Uzantı geliştirme kavramları

Azure Developer CLI (azd) uzantıları, yeni komutlar eklemenizi, iş akışlarını otomatikleştirmenizi ve diğer hizmetleri azd ile tümleştirmenizi sağlar. Bu makalede geliştirici araçları, yazılım geliştirme seti (SDK) ve çalışan bir uzantıyla nasıl azd iletişim kuracakları gibi bir uzantı oluşturmadan önce anlamanız gereken kavramlar açıklanmaktadır. Kullanıcı açısından hangi uzantıların olduğunu öğrenmek için uzantılara genel bakış bölümüne bakın.

Geliştirici uzantısı

Uzantı oluşturmanın en hızlı yolu, geliştirici uzantısını azd (microsoft.azd.extensions ) kullanmaktır. Geliştirici uzantısı, ad alanının altına azd x uzantınızı iskeleleyen, derleyen, paketleyen ve yayımlayan bir komut paketi ekler:

Komut	Description
azd x init	Seçtiğiniz dilde yeni bir uzantı projesi oluşturur.
azd x build	Yerel geliştirme için uzantı ikili dosyasını oluşturur.
azd x watch	Projeyi değişiklikler için izler ve uzantıyı otomatik olarak yeniden derleyip yükler.
azd x pack	Yayımlamaya hazırlanmak için uzantı yapıtlarını paketler.
azd x release	Uzantı için bir GitHub sürümü oluşturur.
azd x publish	Uzantı kayıt defterini yeni uzantı meta verileriyle güncelleştirir.

Örnek uzantı derleme hızlı başlangıcı, geliştirici uzantısının nasıl yükleneceğini ve ilk uzantınızın iskelesini nasıl oluşturabileceğinizi gösterir.

Geliştirici uzantısı, kayıt defteri tabanlı yayımlama iş akışlarını ve taşınabilir paket dağıtımını destekler. Sürüm ve kayda yayımlamak için platform artefaktları oluşturmak üzere .zip kullanın veya bir kayıt barındırmadan bir uzantıyı paylaşmanız gerektiğinde bağımsız bir azd x pack paketi oluşturun. Paketler yerel bir dosyadan yüklenebilir veya BIR HTTPS URL'sinde uzaktan barındırılabilir. Adım adım yönergeler için bkz. Uzantı yayımlama.

Uzantı çerçevesi ve gRPC

azd ve uzantıları gRPC aracılığıyla iletişim kuran ayrı işlemler olarak çalışır. Uzantı komutunu çağırdığınızda aşağıdaki adımlar gerçekleşir:

1. azd rastgele bir bağlantı noktasında bir gRPC sunucusu başlatır ve ortam değişkenini AZD_SERVER sunucu adresiyle ayarlar.
2. azd, komutun süresi boyunca uzantıya AZD_ACCESS_TOKEN hizmetlerine erişim sağlayan imzalı bir JSON Web Belirteci (JWT) olan azd ortam değişkenini ayarlar.
3. azd uzantı komutunuzu çağırır ve mevcut bağımsız değişkenleri, bayrakları ve ortam değişkenlerini aktarır.
4. Uzantınız, kullanıcıdan bilgi isteme veya proje yapılandırmasını okuma gibi çerçeve hizmetleri üzerinden azd ile iletişim kurmak için bir gRPC istemcisi kullanır.
5. azd komutun tamamlanmasını bekler ve sıfır olmayan bir çıkış kodunu hata olarak bildirir.

Bu model, uzantıların dahili azd durumuna doğrudan erişmeden azd ile tutarlı ve güvenli bir şekilde etkileşim kurmasına olanak tanır.

Project düzeyinde uzantı gereksinimleri

Projeler, içinde azure.yamlihtiyaç duydukları uzantıları bildirebilir. Uzantı kimliklerini ve sürüm kısıtlamalarını listelemek için requiredVersions.extensions bölümünü kullanın; böylece azd projenin gereksinimlerini karşılayan sürümleri çözümleyebilir.

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

Bir proje, uzantıların sağladığı ana bilgisayarlara, sağlayıcılara, yaşam döngüsü işleyicilerine, doğrulamalara veya komutlara bağlıysa gerekli uzantıları belirtin. Tam şema ve desteklenen sürüm söz dizimi için bkz requiredVersions. .

The azdext SDK

Paket azdext , uzantı çerçevesi için Go SDK'dır. Uzantı mantığınıza odaklanabilmeniz için sizin için iletişim ayrıntılarını işleyen bir gRPC istemcisi ve yardımcıları sağlar. SDK şunların yardımcılarını içerir:

• Standart azd bayrakları ve ortam değişkeni işlemesini kaydeden bir kök komutu oluşturun.
• azd Giden isteklere erişim belirtecini ekleyin.
• azd Project, Environment, Account ve Prompt hizmetleri gibi çerçeve hizmetlerini çağırın.
• Resmî kaynaklı uzantılar için kullanım olaylarını TelemetryService.ReportUsage gRPC API'si aracılığıyla bildirin. API kullanımı ayrıntıları için bkz. SDK kullanarak azd ile iletişim kurma.
• Yaşam döngüsü olay işleyicilerini ve özel sağlayıcıları bir uzantı konağı aracılığıyla kaydedin.

Uzantınızdan hizmetleri çağırmayı azd öğrenmek için bkz. SDK'yı kullanarak azd ile iletişim kurma.

Uzantı özellikleri

Özellikler, bir uzantının neler yapabileceğini bildirir. Bir uzantının özelliklerini bildiriminde extension.yaml listeleyin ve azd çalışma zamanında ilgili izinleri verir. Kullanılabilir özellikler şunlardır:

• custom-commands: öğesine azdyeni komut grupları ve komutlar ekleyin.
• lifecycle-events: preprovision ve postdeploy gibi proje ve hizmet yaşam döngüsü olaylarına abone olun.
• mcp-server: Yapay zeka aracıları için Model Bağlam Protokolü (MCP) araçları sağlayın.
• service-target-provider: Özel hizmet dağıtım hedefleri sağlayın.
• framework-service-provider: Özel dil ve çerçeve derleme desteği sağlayın.
• provisioning-provider: Özel bir altyapı sağlama deneyimi sağlayın.
• validation-provider: Doğrulama işlem hattına azd doğrulama denetimleri ekleyin.
• metadata: Yardım çıkışı ve IntelliSense için zengin komut ve yapılandırma meta verileri sağlayın.

Uzantıya özellik eklemeyi öğrenmek için bkz. Uzantı özellikleri ekleme.

Desteklenen diller

gRPC'yi destekleyen ve azd çeşitli diller için başlangıç şablonları içeren herhangi bir dilde uzantılar oluşturabilirsinizazd x init. Go, birinci sınıf azdext SDK yardımcıları da dahil olmak üzere en eksiksiz desteğe sahiptir, bu nedenle bu bölümdeki makalelerde tüm örnekler için Go kullanılır.

Language	Destek düzeyi
Go	En iyi destek ve birinci sınıf SDK yardımcıları.
.NET (C#)	Başlangıç şablonuyla güçlü entegrasyon.
Python	Başlangıç şablonuyla iyi entegrasyon.
Javascript	Bir başlangıç şablonu ile temel entegrasyon.

Go dışındaki dillerde yazılan uzantılar için, depodaki proto dosyalarındanazure/azure-dev gRPC istemcileri oluşturabilirsiniz. Dil desteğinin mevcut durumu için üst kaynak uzantı çerçevesi belgelerine bakın.

Uzantı kayıt defterleri

Uzantıları kayıt defteri kaynakları veya uzantı paketleri aracılığıyla dağıtırsınız. Kayıt defteri kaynakları, kullanılabilir uzantıları ve yapıtlarını açıklayan URL tabanlı veya dosya tabanlı bildirimlerdir. Uzantı paketleri, bir kayıt defterini barındırmak istemediğinizde doğrudan yerel bir dosyadan veya HTTPS URL'sinde uzaktan yükleyebileceğiniz taşınabilir .zip paketlerdir.

• Resmî kayıt, azd içinde önceden yapılandırılmıştır ve incelemeden geçmiş birinci taraf uzantılarını barındırır. Resmi uzantılar, azure/azure-dev deposunun çatallanmış bir sürümünde geliştirilir.
• URL tabanlı kaynaklar , uzak genel veya özel kayıt defteri bildirimlerinden yüklemenizi sağlar.
• Dosya tabanlı kaynaklar geliştirme, test veya çevrimdışı senaryolar için yerel kayıt defteri bildirimlerinden yüklemenizi sağlar.
• Geliştirme ve gecelik depoları, devam eden geliştirmeler ve otomatik olarak oluşturulan birinci taraf uzantıları için isteğe bağlı kaynaklardır. Geliştirme kayıt defterindeki uzantılar imzalanmamıştır, Azure desteği kapsamında değildir ve bildirimde bulunmaksızın değiştirilebilir veya kaldırılabilir.

Bir uzantıyı kayıt defterinde yayımlamayı öğrenmek için bkz. Uzantı yayımlama.

İlgili içerik

• Örnek uzantı oluşturma
• Uzantı bildirimini tanımlama
• Uzantı özellikleri ekleme