NuGet platformlar arası eklentiler

Makale
10/18/2023

NuGet'te platformlar arası eklentiler için 4.8+ desteği eklendi. Bu, katı bir çalışma kuralları kümesine uyması gereken yeni bir eklenti genişletilebilirlik modeli oluşturarak elde edildi. Eklentiler, NuGet İstemcilerinin ayrı bir işlemde başlattığı bağımsız yürütülebilir dosyalardır (.NET Core dünyasında çalıştırılabilir dosyalar). Bu bir kez gerçek bir yazmadır, her yerde eklentisini çalıştırın. Tüm NuGet istemci araçlarıyla çalışır. Eklentiler .NET Framework (NuGet.exe, MSBuild.exe ve Visual Studio) veya .NET Core (dotnet.exe) olabilir. NuGet İstemcisi ile eklenti arasında sürümlenmiş bir iletişim protokolü tanımlanır. Başlangıç el sıkışması sırasında, 2 işlem protokol sürümüyle anlaşma sağlar.

Tüm NuGet istemci araçları senaryolarını ele almak için hem .NET Framework hem de .NET Core eklentisi gerekir. Aşağıda eklentilerin istemci/çerçeve birleşimleri açıklanmaktadır.

İstemci aracı	Çerçeve
Visual Studio	.NET Framework
dotnet.exe	.NET Core
NuGet.exe	.NET Framework
Msbuild.exe	.NET Framework
Mono'da NuGet.exe	.NET Framework

Nasıl çalışır?

Üst düzey iş akışı aşağıdaki gibi açıklanabilir:

NuGet kullanılabilir eklentileri bulur.
Uygun olduğunda NuGet, eklentileri öncelik sırasına göre yineler ve tek tek başlatır.
NuGet, isteğe hizmet veren ilk eklentiyi kullanır.
Eklentiler artık gerekli olmadığında kapatılır.

Genel eklenti gereksinimleri

Geçerli protokol sürümü 2.0.0'dır. Bu sürüm altında gereksinimler şunlardır:

Windows ve Mono üzerinde çalışacak geçerli, güvenilir bir Authenticode imza derlemelerine sahip olun. Henüz Linux ve Mac üzerinde çalıştırılacak derlemeler için özel bir güven gereksinimi yoktur. İlgili sorun
NuGet istemci araçlarının geçerli güvenlik bağlamı altında durum bilgisi olmayan başlatma desteği. Örneğin, NuGet istemci araçları daha sonra açıklanan eklenti protokolü dışında yükseltme veya ek başlatma gerçekleştirmez.
Açıkça belirtilmediği sürece etkileşimli olma.
Anlaşmaya varılan eklenti protokolü sürümüne bağlı kalın.
Tüm isteklere makul bir süre içinde yanıt verin.
Devam eden işlemler için iptal isteklerini kabul edin.

Teknik belirtim aşağıdaki özelliklerde daha ayrıntılı olarak açıklanmıştır:

İstemci - Eklenti etkileşimi

NuGet istemci araçları ve eklentileri standart akışlar (stdin, stdout, stderr) üzerinden JSON ile iletişim kurar. Tüm veriler UTF-8 kodlanmış olmalıdır. Eklentiler "-Plugin" bağımsız değişkeniyle başlatılır. Kullanıcının bu bağımsız değişken olmadan doğrudan bir eklenti yürütülebilir dosyası başlatması durumunda eklenti, protokol el sıkışmasını beklemek yerine bilgilendirici bir ileti verebilir. Protokol el sıkışması zaman aşımı 5 saniyedir. Eklenti, kurulumu mümkün olduğunca kısa bir sürede tamamlamalıdır. NuGet istemci araçları, bir NuGet kaynağı için hizmet dizinini geçirerek eklentinin desteklenen işlemlerini sorgular. Eklenti, desteklenen hizmet türlerinin olup olmadığını denetlemek için hizmet dizinini kullanabilir.

NuGet istemci araçları ve eklenti arasındaki iletişim çift yönlüdür. Her isteğin zaman aşımı 5 saniyedir. İşlemlerin daha uzun sürmesi gerekiyorsa, ilgili işlem isteğin zaman aşımına uğramasını önlemek için bir ilerleme iletisi göndermelidir. 1 dakikalık işlem yapılmadığında eklenti boşta kabul edilir ve kapatılır.

Eklenti yükleme ve bulma

Eklentiler kural tabanlı dizin yapısı aracılığıyla bulunur. CI/CD senaryoları ve güç kullanıcıları, davranışı geçersiz kılmak için ortam değişkenlerini kullanabilir. Ortam değişkenlerini kullanırken yalnızca mutlak yollara izin verilir. ve'nin NUGET_NETCORE_PLUGIN_PATHS yalnızca NuGet araçlarının ve sonraki sürümleriyle 5.3+ sürümüyle kullanılabildiğini NUGET_NETFX_PLUGIN_PATHS unutmayın.

NUGET_NETFX_PLUGIN_PATHS - .NET Framework tabanlı araçlar (NuGet.exe/MSBuild.exe/Visual Studio) tarafından kullanılacak eklentileri tanımlar. ' den önceliklidir NUGET_PLUGIN_PATHS. (Yalnızca NuGet sürüm 5.3+ )
NUGET_NETCORE_PLUGIN_PATHS - .NET Core tabanlı araçlar (dotnet.exe) tarafından kullanılacak eklentileri tanımlar. ' den önceliklidir NUGET_PLUGIN_PATHS. (Yalnızca NuGet sürüm 5.3+ )
NUGET_PLUGIN_PATHS - Bu NuGet işlemi için kullanılacak eklentileri tanımlar, öncelik korunur. Bu ortam değişkeni ayarlanırsa kural tabanlı bulmayı geçersiz kılar. Çerçeveye özgü değişkenlerden biri belirtilirse yoksayılır.
Kullanıcı konumu, içindeki %UserProfile%/.nuget/pluginsNuGet Giriş konumu. Bu konum geçersiz kılınamaz. .NET Core ve .NET Framework eklentileri için farklı bir kök dizin kullanılır.

Çerçeve	Kök bulma konumu
.NET Core	`%UserProfile%/.nuget/plugins/netcore`
.NET Framework	`%UserProfile%/.nuget/plugins/netfx`

Her eklenti kendi klasörüne yüklenmelidir. Eklenti giriş noktası, .NET Core için .dll uzantıları ve .NET Framework için .exe uzantılı yüklü klasörün adı olacaktır.

.nuget
    plugins
        netfx
            myPlugin
                myPlugin.exe
                nuget.protocol.dll
                ...
        netcore
            myPlugin
                myPlugin.dll
                nuget.protocol.dll
                ...

Not

Şu anda eklentilerin yüklenmesi için bir kullanıcı hikayesi yoktur. Gerekli dosyaları önceden belirlenmiş konuma taşımak kadar basittir.

Desteklenen işlemler

Yeni eklenti protokolü altında iki işlem desteklenir.

Operasyon adı	En düşük protokol sürümü	En düşük NuGet istemci sürümü
Paketi İndir	1.0.0	4.3.0
Kimlik Doğrulaması	2.0.0	4.8.0

Eklentileri doğru çalışma zamanı altında çalıştırma

dotnet.exe senaryolarındaki NuGet için eklentilerin dotnet.exe ilgili çalışma zamanı altında yürütebilmesi gerekir. Uyumlu bir dotnet.exe/eklenti bileşimi kullanıldığından emin olmak için eklenti sağlayıcısında ve tüketicide bulunur. Örneğin, 2.0 çalışma zamanı altındaki bir dotnet.exe 2.1 çalışma zamanı için yazılmış bir eklentiyi kullanmaya çalıştığında, kullanıcı konumu eklentileriyle ilgili olası bir sorun ortaya çıkabilir.

Özellikleri önbelleğe alma

Eklentilerin güvenlik doğrulaması ve örneği yüksek maliyetlidir. İndirme işlemi, kimlik doğrulama işleminden çok daha sık gerçekleşir, ancak ortalama Bir NuGet kullanıcısının yalnızca bir kimlik doğrulama eklentisi olması olasıdır. Deneyimi geliştirmek için NuGet, verilen istek için işlem taleplerini önbelleğe alır. Bu önbellek eklenti başınadır ve eklenti anahtarı eklenti yoludur ve bu özellik önbelleği için süre sonu 30 gündür.

Önbellek içinde %LocalAppData%/NuGet/plugins-cache bulunur ve ortam değişkeniyle NUGET_PLUGINS_CACHE_PATHgeçersiz kılınır. Bu önbelleği temizlemek için yereller komutunu seçeneğiyle plugins-cache çalıştırabilirsiniz. Yerel all ayarlar seçeneği artık eklenti önbelleğini de silecektir.

Protokol iletileri dizini

Protokol Sürüm 1.0.0 iletileri:

Kapat
- İstek yönü: NuGet -> eklenti
- İstek yük içermiyor
- Yanıt beklenmez. Uygun yanıt, eklenti işleminin hemen çıkması içindir.
Paketteki dosyaları kopyalama
- İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - paket kimliği ve sürümü
  - paket kaynağı deposu konumu
  - hedef dizin yolu
  - hedef dizin yoluna kopyalanacak paketteki dosyaların numaralandırılabilir bir örneği
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
  - İşlem başarılı olursa hedef dizinde kopyalanan dosyalar için tam yolların numaralandırılabiliri
Paket dosyasını kopyalama (.nupkg)
- İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - paket kimliği ve sürümü
  - paket kaynağı deposu konumu
  - hedef dosya yolu
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
Kimlik bilgilerini alma
- İstek yönü: eklenti -> NuGet
- İstek aşağıdakileri içerir:
  - paket kaynağı deposu konumu
  - geçerli kimlik bilgileri kullanılarak paket kaynağı deposundan alınan HTTP durum kodu
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
  - varsa bir kullanıcı adı
  - varsa bir parola
Paketteki dosyaları alma
- İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - paket kimliği ve sürümü
  - paket kaynağı deposu konumu
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
  - İşlem başarılı olursa paketteki dosya yollarının numaralandırılabiliri
İşlem taleplerini alma
- İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - paket kaynağı için hizmet index.json
  - paket kaynağı deposu konumu
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
  - İşlem başarılı olursa desteklenen işlemlerin (örn. paket indirme) numaralandırılabilir bir listesi. Eklenti paket kaynağını desteklemiyorsa eklentinin boş bir desteklenen işlem kümesi döndürmesi gerekir.

Not

Bu ileti 2.0.0 sürümünde güncelleştirildi. Geriye dönük uyumluluğu korumak istemcidedir.

Paket karması alma
- İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - paket kimliği ve sürümü
  - paket kaynağı deposu konumu
  - karma algoritması
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
  - İşlem başarılı olursa istenen karma algoritmasını kullanan bir paket dosyası karması
Paket sürümlerini alma
- İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - paket kimliği
  - paket kaynağı deposu konumu
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
  - İşlem başarılı olursa paket sürümlerinin numaralandırılabiliri
Hizmet dizini alma
- İstek yönü: eklenti -> NuGet
- İstek aşağıdakileri içerir:
  - paket kaynağı deposu konumu
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
  - İşlem başarılı olursa hizmet dizini
El sıkışma
- İstek yönü: NuGet <-> eklenti
- İstek aşağıdakileri içerir:
  - geçerli eklenti protokolü sürümü
  - desteklenen en düşük eklenti protokolü sürümü
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
  - İşlem başarılı olursa, anlaşmaya varılan protokol sürümü. Hata, eklentinin sonlandırılmasına neden olur.
Başlatma
- İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - NuGet istemci aracı sürümü
  - NuGet istemci aracı etkin dili. Bu, kullanılıyorsa ForceEnglishOutput ayarını dikkate alır.
  - protokol varsayılanı yerine geçen varsayılan istek zaman aşımı.
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu. Hata, eklentinin sonlandırılmasına neden olur.
Günlük
- İstek yönü: eklenti -> NuGet
- İstek aşağıdakileri içerir:
  - isteğin günlük düzeyi
  - günlüğe kaydedilecek bir ileti
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu.
NuGet işlem çıkışını izleme
- İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - NuGet işlem kimliği
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu.
Paket ön eki uygulama
- İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - paket kimliği ve sürümü
  - paket kaynağı deposu konumu
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
Kimlik bilgilerini ayarlama
- İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - paket kaynağı deposu konumu
  - varsa bilinen son paket kaynağı kullanıcı adı
  - varsa bilinen son paket kaynağı parolası
  - varsa bilinen son proxy kullanıcı adı
  - varsa bilinen son proxy parolası
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
Günlük düzeyini ayarlama
- İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - varsayılan günlük düzeyi
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu

Protokol Sürüm 2.0.0 iletileri

İşlem Taleplerini Alma

İstek yönü: NuGet -> eklenti
- İstek aşağıdakileri içerir:
  - paket kaynağı için hizmet index.json
  - paket kaynağı deposu konumu
- Yanıtta aşağıdakiler bulunur:
  - işlemin sonucunu gösteren bir yanıt kodu
  - İşlem başarılı olursa desteklenen işlemlerin numaralandırılabilir. Eklenti paket kaynağını desteklemiyorsa eklentinin boş bir desteklenen işlem kümesi döndürmesi gerekir.
Hizmet dizini ve paket kaynağı null ise eklenti kimlik doğrulamasıyla yanıt verebilir.

Kimlik Doğrulama Kimlik Bilgilerini Alma

İstek yönü: NuGet -> eklenti
İstek aşağıdakileri içerir:
- Uri
- isRetry
- Etkileşimsiz
- CanShowDialog
Yanıt,
- Username
- Parola
- İleti
- Kimlik Doğrulama Türleri Listesi
- MessageResponseCode