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.

Kronolojisi

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.

Yıl	Özellik
2013	Web sitesinde gösterilen sahipleri netleştirdikten nuget.org paket sahiplerinin nasıl yönetileceğini açıklayan bir blog gönderisi, yeni sürümleri karşıya yükleme izni olan hesaplardır ve bu nedenle owners paketteki meta veriler yoksayılır
2017	Yanıtlara SearchQueryService eklendiverified.
	Anlamsal Sürüm Oluşturma 2.0.0 desteği
2018	Ekli lisanslar
2019	Eklenmiş simgeler
	içinde RegistrationBaseUrl paket kullanımdan kaldırma (paket meta veri kaynağı)
2020	içindeki RegistrationsBaseUrl paket güvenlik açığı bilgileri (paket meta veri kaynağı)
	İsteklere SearchQueryService sorgu parametresi eklendi packageTypes
2021	Katıştırılmış benioku
2023	Kimliği doğrulanmış istekleri Önceden Doğrula VulnerabilityInfo Kaynak

Sahip alanı

Paket bildirim dosyası () alanlarından ikisini ve <owners>kullanmayı <authors> göz önünde bulundurun..nuspec Üçü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 meta verileri içeriyorsa yoksayılmalıdır. Arama kaynağında veya paket meta veri kaynağı JSON yanıtında owners özelliğindeki dosya <owners> alanının değerini .nuspec 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 verified olarak ayarlandığında truearama hizmeti sonuçlarında 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'de 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, yayın öncesi etiketin parçası olarak izin verilen tek karakterler için örnek bir Normal İfade dizesi sağlar [0-9A-Za-z-] 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 ile uyumlu paketleri döndürmelidir. NET'in System.Version veya AnlamSal Sürüm Oluşturma 1.0.0. 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. İstemci özellikleri (kilit dosyaları ve imzalı paketler) paket üzerinde oynanmış olarak değişiklikleri algıladığından paketler (.nupkg dosyalar) değiştirilmemelidir.

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, lisans ifadesi olarak ayarlanmış, URL kodlanmış ve sonuna https://licenses.nuget.org/eklenmiş olabilirlicenseUrl. Ö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.

Paket deponuz başka bir depodaki paketleri "kaynak oluşturma" aşamasındaysa, paketleri kendi akışınızda yansıtmak için kullanımdan kaldırma veya güvenlik açığı verileri olup olmadığını düzenli aralıklarla denetlemenizi ve bu meta verileri kendi deponuzda yansıtmanızı öneririz. Paket deponuz özellikle nuget.org'dan kaynak oluşturabiliyorsa, son denetlediğiniz zamanın (bir "imleç") durumunu koruyarak, yukarı akış akışından çok sayıda paket meta veri JSON dosyası indirmek zorunda kalmadan yansıtdığınız paketler için paket güncelleştirmeleri olup olmadığını verimli bir şekilde denetlemek için kaynağı kullanabilirsiniz.Catalog 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, Nuget.org üzerinde barındırılmayan paketleri içeren GitHub Danışmanları veritabanından tüm GitHub gözden geçirilmiş önerileri için güvenlik açığı verileri sağlar.

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çığı dizini sağlamanız gerekir.

Paket deponuzun uygulamalar tarafından varsayılan depo olarak kullanılması amaçlanıyorsa (nuget.org yerine) nuget.org'un güvenlik açığı verilerini kullanabilirsiniz. Seçeneklerden biri, hizmet dizininizde nuget.org'un güvenlik açığı dizini URL'sini kullanmaktır. Bir diğer seçenek de nuget.org'un VulnerabilityInfo dizinini düzenli aralıklarla denetlemek ve değiştirilen sayfaları yerel olarak yansıtmak üzere indirmektir.

packageTypes arama sorgusu

.NET CLI komutuyla .NET araç paketlerinin dotnet tool search aranmasına olanak tanır. Bu, arama sorgusu kaynağına paketin .nuspec dosya <packageTypes> alanından değerleri okuyan bir &packageTypes={value} 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 kullanır . NET'in HttpClientHandler.PreAuthenticate, yalnızca daha önce kimliği doğrulanmış bir URL'nin aynı sanal dizininde veya alt dizininde bulunan anonim HTTP isteklerini önler. 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.

Burada 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ğinin kimliği kurallı olmayan bir URL'de doğrulandıysa (örneğimizdeki feed"kolay" ad), hayır, kurallı URL altındaki kaynaklara yönelik istekler 'in kurallarıyla PreAuthenticateeşleşmezHttpClientHandler. 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, 'PreAuthenticatelerinden HttpClientHandleryararlanmak 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.