NuGet Server Uygulama Kılavuzu

Bazı durumlarda kendi NuGet paket akışınızı uygulamak isteyebilirsiniz. Kendi akışınızı çeşitli şekilde barındırmanıza olanak tanıyan birçok mevcut uygulama vardır , ancak resmi NuGet istemci yazılımı ile bir paket akışı arasındaki protokol, sıfırdan kendi akış uygulamanızı oluşturmanıza olanak tanıyan belgelenmiştir.

Protokol zaman içinde gelişir ve bu kılavuz bir NuGet paket sunucusu uygulamak isteyenlere yöneliktir.

NuGet V3 protokolünün 2015'teki ilk sürümünden bu yana, NuGet geliştiricilere daha zengin bir deneyim sağlayacak şekilde gelişti ve bu, barındırılan paketlerden meta verileri tam olarak belirlemenin ve meta verileri çeşitli biçimlerde döndürmenin ötesinde paket tüketicilerine ek değer sağlamak için paket depolarının ek iş yapması gerekiyor. Örneğin, arama ve paket meta veri uç noktaları nupkg'un nuspec dosyasında bulunan meta verilerden fazlasını içerir.

V2 protokolü temel olarak belgelenmemiş olduğundan ve 2015'ten bu yana NuGet istemci ve sunucu iletişimi için önerilen protokol V3 protokolü olduğundan bu kılavuzun NuGet V3 protokolüne odaklandığını unutmayın. Daha fazla bilgi için protokol sürümü oluşturma hakkında bilgi edinin.

Chronology

Mevcut NuGet depolarının yazarlarının NuGet'in en yeni özellikleriyle güncel kalmalarına yardımcı olmak için, belgenin geri kalanında bahsedilen ilgili özelliklerin kronolojisini burada bulabilirsiniz.

Year	Feature
2013	Nuget.org'da paket sahiplerinin nasıl yönetileceğini açıklayan bir blog gönderisi, site üzerinde gösterilen sahiplerin yeni sürümleri yükleme iznine sahip hesaplar olduğunu ve bu nedenle paketteki owners meta verinin yoksayıldığını netleştirdi.
2017	Yanıtlara verified eklendiSearchQueryService.
	Anlamsal Sürüm Oluşturma 2.0.0 desteği
2018	Ekli lisanslar
2019	Eklenmiş simgeler
	RegistrationBaseUrl paket meta veri kaynağında paket kullanımdan kaldırma
2020	içindeki RegistrationsBaseUrl paket güvenlik açığı bilgileri (paket meta veri kaynağı)
	İsteklere packageTypes sorgu parametresi eklendi SearchQueryService
2021	Gömülü benioku
2023	Kimliği doğrulanmış istekleri Önceden Doğrula VulnerabilityInfo kaynak
2025	Eklenmiş README indirmelerini etkinleştirme

Sahiplik alanı

Paket bildirim dosyası (.nuspec) alanlarından ikisini, <authors> ve <owners> göz önünde bulundurun. Üçüncü taraf içeriği paketleyen paket yazarları genellikle üçüncü taraf adını <authors> alana koyar. Alanı <owners> , paketi bir depoda kimin yayımladığını ve bu nedenle paketleme sorunları veya soruları durumunda kiminle iletişime geçilmesi gerektiğini belirtmek için tasarlanmıştır.

Bu, 2013'teki bir blog gönderisinde açıklanmıştır, bu nedenle <owners> alan dosyada .nuspec kullanım dışı olarak kabul edilir. Paketin bildirimi bu metaveriyi içeriyorsa yoksayılmalıdır. .nuspec veya <owners> JSON yanıtında owners özelliğindeki dosyasının alanının değerini döndürmeyin.

Deponuzun paket başına izinleri varsa, arama ve paket meta verileri kaynakları JSON yanıtları için meta verilerde owner yeni sürüm yayımlama izinlerine sahip hesapları raporlamanız önerilir.

verified arama yanıtı alanı

Visual Studio'nun Paket Yöneticisi kullanıcı arabirimi, yeni bir alan olarak ayarlandığında verifiedtrue sonuçlarındaki paketlerin yanında mavi bir onay işareti gösterir.

NuGet.org bunu paket ön eki verileriyle (NuGet API'sinin parçası olmayan sunucu tarafı verileri) kullanır, böylece bu onay işareti yalnızca paketin sahibi olan hesap paketi karşıya yüklediğinde müşterilere gösterilir. Örneğin, ön eki microsoft.* olan tüm paketler yalnızca paketin nuget.org'da Microsoft hesabına ait olduğu durumlarda doğrulanır. Ayrılmış ön ekleri uygulanmadan önce ile başlayan microsoft. paket kimliğine sahip bir paketi karşıya yükleyen herkes bu doğrulanmış onay işaretine sahip olmayacaktır. NuGet.org ayrıca ön eklerin özel olmamasını da sağlar, böylece herkes altına Contoso.ToolWithPlugins.Community.*bir paket yükleyebilir, ancak doğrulanmış bir onay işareti alamaz.

Anlamsal Sürüm Oluşturma 2.0.0 desteği

NuGet , ile AnlamSal Sürüm arasında System.Version bir karmayı destekler, ancak AnlamSal Sürüm 2.0.0 desteği 2017'de eklenmiştir. Bu nedenle, 3.6.0'dan düşük istemci sürümlerine sürüm döndüren NuGet API kaynakları, AnlamSal Sürüm 1.0.0 ile uyumlu olmayan Anlamsal 2.0.0 özelliklerini kullanan paketleri döndürmemelidir.

İki sürüm arasındaki en önemli farklar yayın öncesi etiketler ve meta veri dizesidir. Anlamsal Sürüm Oluşturma 1.0.0 belirtimi, yalnızca yayın öncesi etiketin parçası olarak izin verilen karakterler için bir örnek Normal İfade dizesi [0-9A-Za-z-] sağlar ve meta veri dizelerini desteklemez. Anlamsal Sürüm Oluşturma 2.0.0 belirtimi, yayın öncesi tanımlayıcıların karakterlerle . ayrılmasını sağlar (ve bir sayısal tanımlayıcının başında sıfır olmasını yasaklar) ve ayrıca bir +sonrasında derleme meta verilerinin eklenmesine izin verir.

Paket meta veri kaynağında (RegistrationsBaseUrl), 3.6.0'ın altındaki kaynak sürümleri yalnızca .NET'in System.Version veya İşlevsel Sürümleme 1.0.0 ile uyumlu paketleri döndürmelidir. Bu, sürümleri yalnızca AnlamSal Sürüm 2.0.0 ile uyumlu olan paketlerin bu istemci sürümleri için görünmez olduğu anlamına gelir.

Benzer şekilde, arama sorgusu hizmeti (SearchQueryService) ve otomatik tamamlama hizmeti (SearchAutocompleteService) sorgu parametreleri ekledi &semVerLevel={version} . eksik olduğunda semVerLevel değerini 1.0.0varsayın. Paket meta veri kaynağında olduğu gibi, sürümü yalnızca AnlamSal Sürüm Oluşturma 2.0.0 ile uyumlu olan paketler, değer 2.0.0'ın altında olduğunda semVerLevel döndürülmemelidir.

Eklenmiş dosyalar

Paket simgeleri, lisans ve benioku dosyaları pakete eklenebilir (ve bunlar önerilir). Bu dosyalar, ayıklanıp statik bir dosya sunucusuna konulabilecek bir URL uç noktasına veya istek üzerine dosyaları .nupkg dinamik olarak ayıklayan bir URL'ye ihtiyaç duyar, böylece bunların tamamını nupkgindirmeden görüntülenebilir. Paket deponuz pakete göz atma ve paket ayrıntılarını görüntüleme olanağı sağlıyorsa, müşterilere web sitenizdeki ekli içeriği göstermek için URL'leri kullanabilirsiniz.

Son olarak, paket meta veri kaynağı ve arama kaynağı , JSON yanıtının iconUrl, licenseUrlve/veya readmeUrl özelliklerinde barındırılan URL'yi içermelidir. Paketler (.nupkg dosyalar) değiştirilmemelidir, çünkü istemci özellikleri (kilit dosyaları ve imzalı paketler), yapılan değişiklikleri paketin üzerinde oynanmış olarak algılar.

Lisansın bir SPDX ifadesi veya eklenmiş bir dosya (her ikisini birden değil) olabileceğini unutmayın. Arama ve paket meta verileri sonuçlarında temsil edildiğinde, lisans ifadesi kullanan paketler için licenseUrl lisans ifadesine ayarlanabilir, URL kodlanabilir ve https://licenses.nuget.org/ sonuna eklenebilir. Örneğin, https://licenses.nuget.org/Apache-2.0. NuGet.org sunucu ekibinin licenses.nuget.org hakkında ek belgeleri vardır.

Bilinen güvenlik açığı ve kullanımdan kaldırma verileri

Paket Meta Veri Kaynağı (RegistrationsBaseUrl)

Paket Meta Verileri Kaynağıkullanımdan kaldırma ve güvenlik açığı bilgilerini içerebilir. Bu, Visual Studio'nun Paket Yöneticisi Kullanıcı Arabirimindeki veya diğer IDE'lerdeki eşdeğer paketlere göz atan müşterilerin önemli güvenlik veya bakım sorunları hakkında bilgilendirilmesini sağlar.

Başka bir depodan paketleri "yukarı kaynak oluşturma" amacıyla paket deponuza ekliyorsanız, paketleri kendi akışınıza yansıtmak için kullanımdan kaldırma veya güvenlik açığı verileri olup olmadığını düzenli olarak kontrol etmenizi ve bu meta verileri kendi deponuzda yansıtmanızı öneririz. Paket deponuz özellikle nuget.org'dan kaynak sağlıyorsa ve son denetlediğiniz zamanın (bir "imleç") bilgisini koruyarak, yansıttığınız paketler için güncellemeler olup olmadığını verimli bir şekilde kontrol etmek için kaynağı kullanabilirsiniz. Bu sayede, kaynak akışından çok sayıda paket meta verisi JSON dosyası indirmek zorunda kalmazsınızCatalog. Kullanmaya başlamanıza yardımcı olabilecek örnek kodla katalog kaynağını kullanma hakkında bir kılavuz vardır.

Bilinen Güvenlik Açıkları Veritabanı (VulnerabilityInfo)

NuGet, paket geri yükleme sırasında yüksek performanslı güvenlik açığı taraması sağlamak için kaynaktan VulnerabilityInfobilinen güvenlik açıklarının tam listesini indirir. Nuget.org, GitHub Danışmanları veritabanından gözden geçirilmiş tüm GitHub önerileri için güvenlik açığı verileri sağlar ve bu veriler nuget.org üzerinde barındırılmayan paketleri içerir.

Paket deponuz birinci taraf paketleri barındırıyorsa ve kendi akışınızı kullanan müşterilere güvenlik açığı bilgileri sağlamak istiyorsanız ancak henüz açıklanmış paket güvenlik açıkları yoksa, içeriği boş bir JSON dizisi () olan bir veya daha fazla güvenlik açığı sayfası içeren bir güvenlik açığı[] sağlamanız gerekir.

nuget.org'un güvenlik açığı verilerini yeniden kullanıyor

NuGet, hizmet dizinindeki veya güvenlik açığı dizinindeki kaynakların hizmet dizininin kendisiyle aynı sunucuda olmasını gerektirmez. Ancak, bazı şirketlerin güvenlik duvarı üzerinden nuget.org'u engellemeyi seçmesinin veya bağlantısı kesilmiş bir ağda yerel beslemeler bulunmasının çeşitli nedenleri vardır. Bağlantı sorunlarını önlemek için, NuGet istemcilerinin yalnızca akışın yüklü olduğu konağa HTTP bağlantıları kurması için güvenlik açığı verilerini kendi web uygulamanızdan sunmanızı öneririz.

✔️ Kendi web uygulamanızda zafiyet sayfalarını önbelleğe alın veya proxy kullanın

❌ Bunu kapatmak için bir yapılandırma olmadan hizmet dizininizde veya güvenlik açığı dizininizde api.nuget.org tanıtMAYIN.

packageTypes arama sorgusu

.NET CLI, dotnet tool search komutuyla .NET araç paketlerini aramaya olanak tanır. Bu, &packageTypes={value} paketin dosya .nuspec alanından değerleri okuyan bir <packageTypes> sorgu parametresi eklenerek uygulanır.

Kimliği doğrulanmış akışlar için URL yapısı

NuGet API'sine genel bakış bölümünde açıklandığı gibi, tüm NuGet sunucu iletişiminin başlangıç URL'si hizmet dizinidir. Bu belge, NuGet istemcilerinin sorgulayacakları diğer tüm kaynakların URL'lerini içerir. NuGet 6.7 (Visual Studio & MSBuild 17.7 ve .NET SDK 7.0.400) itibarıyla, NuGet, yalnızca daha önce kimliği doğrulanmış bir URL'nin aynı sanal dizininde veya bir alt dizininde olan URL'ler için anonim HTTP isteklerini önleyen .NET'in özelliğini kullanır. Bu, sunucuya gönderilen kimliği doğrulanmamış HTTP isteklerinin sayısını önemli ölçüde azaltır ve bu nedenle sunucu iş yükünüzü azaltır.

Aşağıda bazı örnekler verilmiştir:

URL	PreAuthenticate yapacak mı?
https://pkgs.contoso.com/nuget/v3/feed/index.json	Yok, bu hizmet dizinidir.
https://pkgs.contoso.com/nuget/v3/search	Hayır, hizmet diziniyle aynı veya alt dizinde değil.
https://search.pkgs.contoso.com/nuget/v3/feed/	Hayır, hizmet diziniyle aynı ana bilgisayar adında değil.
https://pkgs.contoso.com/nuget/v3/feed/search	Evet, hizmet diziniyle aynı dizinde.
https://pkgs.contoso.com/nuget/v3/registration/	Hayır, hizmet dizininin alt dizininde değil.
https://pkgs.contoso.com/nuget/v3/feed/registration/	Evet, hizmet dizininin bir alt dizininde.
https://pkgs.contoso.com/nuget/v3/{guid}/registration/	Aşağıya bakın

Son örnekte, sunucunun kurallı (bu örnekte guid) bir adı ve bir veya daha fazla diğer adı olabilir. Hizmet dizini isteği kanonik olmayan bir URL'de doğrulandıysa (örneğimizdeki "kolay" ad feed), hayır, kanonik URL altındaki kaynaklara yapılan istekler HttpClientHandler için PreAuthenticate kurallarıyla eşleşmeyecektir. Ancak, kurallı olmayan URL kurallı URL'ye bir HTTP yeniden yönlendirmesiyse, https://pkgs.contoso.com/nuget/v3/{guid}/index.jsonbu URL 'nin kimlik bilgisi önbelleğinde HttpClientHandlerkullanılır. Bu durumda, yeniden yönlendirme nedeniyle hizmet dizinine yapılan her istek ek gecikme süresine sahip olur.

NuGet'in V3 API'si statik bir dosya sunucusu üzerinde çalışacak şekilde tasarlanmış olsa da, arama kaynağı istekleri işlemek için her zaman dinamik bir web hizmeti gerektiren özel durumdur. Arama özelliğini veya başka bir NuGet API kaynağını farklı sunucularda barındırmak istiyorsanız, 'HttpClientHandlerlerinden PreAuthenticateyararlanmak için, hizmet dizininde müşteriye yönelik tüm URL'lerin "aynı veya alt dizin" kuralını karşıladığından emin olmak için ters ara sunucu kullanmanız gerekir.

Eklenmiş README indirmelerini etkinleştirme

Bir paket için BENIOKU dosyasını indirmeye olanak tanıyan bir URL oluşturmak amacıyla yeni bir kaynak belgelendi. Bu, VS'deki Paket Yönetimi kullanıcı arabirimi gibi istemcinin daha önce kullanıcı tarafından yüklenmemiş paketler için eklenmiş README'yi görüntülemesine olanak tanır. İstemci bu URL'yi oluşturur ve bir README mevcut olup olmadığını belirlemek için isteğin yanıtını kullanarak README'yi indirmeye çalışır. Bu, kullanıcılar PM kullanıcı arabiriminde gezinirken sunucuların, yapılandırılan uç noktaya birden çok istek beklemesi gerektiği anlamına gelir.