Panduan Implementasi NuGet Server
Dalam beberapa kasus, Anda mungkin ingin menerapkan umpan paket NuGet Anda sendiri. Ada banyak implementasi yang ada yang memungkinkan Anda untuk menghosting umpan Anda sendiri dengan berbagai cara, tetapi protokol antara perangkat lunak klien NuGet resmi dan umpan paket didokumenkan yang memungkinkan Anda untuk membangun implementasi umpan Anda sendiri dari awal.
Protokol berkembang dari waktu ke waktu dan panduan ini ditujukan kepada mereka yang ingin atau sudah menerapkan server paket NuGet.
Sejak rilis awal protokol NuGet V3 pada tahun 2015, NuGet telah berevolusi untuk memberikan pengalaman yang lebih kaya kepada pengembang, dan ini memerlukan repositori paket untuk melakukan pekerjaan tambahan untuk memberikan nilai tambahan konsumen paket mereka, di luar hanya mengesahkan metadata dari paket yang dihosting dan mengembalikan metadata dalam berbagai bentuk. Misalnya, titik akhir metadata pencarian dan paket berisi lebih dari sekadar metadata yang ditemukan dalam file nuspec nupkg.
Perhatikan bahwa panduan ini difokuskan pada protokol NuGet V3 karena protokol V2 pada dasarnya tidak terdokumentasi dan, sejak 2015, protokol yang direkomendasikan untuk klien NuGet dan komunikasi server adalah protokol V3. Untuk informasi selengkapnya, baca tentang penerapan versi protokol.
Untuk membantu penulis repositori NuGet yang ada mengikuti perkembangan fitur terbaru NuGet, berikut adalah kronologi fitur relevan yang disebutkan dalam sisa dokumen.
Tahun | Fitur |
---|---|
2013 | Posting blog yang menjelaskan cara mengelola pemilik paket di nuget.org mengklarifikasi pemilik yang ditampilkan di situs web adalah akun yang memiliki izin untuk mengunggah versi baru, dan oleh karena itu owners metadata dalam paket diabaikan |
2017 | Ditambahkan verified ke SearchQueryService respons. |
Dukungan Semantic Versioning 2.0.0 | |
2018 | Lisensi yang disematkan |
2019 | Ikon yang disematkan |
Penghentian paket dalam RegistrationBaseUrl (sumber daya metadata paket) |
|
2020 | Informasi kerentanan paket dalam RegistrationsBaseUrl (sumber daya metadata paket) |
Menambahkan packageTypes parameter kueri ke SearchQueryService permintaan |
|
2021 | Readme yang disematkan |
2023 | PraAutentikasi permintaan terautentikasi VulnerabilityInfo Sumber daya |
Pertimbangkan dua bidang <authors>
file manifes paket (.nuspec
), dan <owners>
.
Penulis paket yang mengemas konten pihak ketiga sering memasukkan nama pihak ketiga di <authors>
bidang .
Bidang <owners>
ini dimaksudkan untuk menunjukkan siapa yang menerbitkan paket pada repositori, dan oleh karena itu siapa yang harus dihubungi jika terjadi masalah atau pertanyaan pengemasan.
Ini dijelaskan dalam posting blog dari 2013, sehingga <owners>
bidang dianggap tidak digunakan lagi dalam .nuspec
file.
Jika manifes paket berisi metadata ini, manifes tersebut harus diabaikan.
Jangan mengembalikan nilai .nuspec
bidang file <owners>
di owners
properti dalam sumber daya pencarian atau respons JSON sumber daya metadata paket.
Jika repositori Anda memiliki izin per paket, disarankan untuk melaporkan akun yang memiliki izin untuk menerbitkan versi baru dalam owner
metadata untuk respons JSON sumber daya metadata pencarian dan paket.
UI Manajer Paket Visual Studio menunjukkan tanda centang biru di samping paket dalam hasil layanan pencarian, saat bidang verified
baru diatur ke true
.
NuGet.org menggunakan ini dengan data awalan paket (data sisi server, bukan bagian dari API NuGet), sehingga tanda centang ini hanya ditampilkan kepada pelanggan ketika akun yang memiliki paket mengunggah paket.
Misalnya, paket apa pun dengan awalan microsoft.*
hanya diverifikasi ketika paket dimiliki oleh akun Microsoft di nuget.org. Siapa pun yang mengunggah paket dengan id paket yang dimulai dengan microsoft.
sebelum awalan yang dipesan diimplementasikan, tidak akan memiliki tanda centang terverifikasi ini.
NuGet.org juga memungkinkan prefiks tidak eksklusif, sehingga siapa pun dapat mengunggah paket di bawah Contoso.ToolWithPlugins.Community.*
, tetapi tidak akan mendapatkan tanda centang terverifikasi.
NuGet mendukung hibrid antara System.Version
dan Versi Semantik, tetapi dukungan untuk Semantic Versi 2.0.0 ditambahkan pada tahun 2017.
Oleh karena itu, sumber daya NUGet API yang mengembalikan versi ke versi klien yang lebih rendah dari 3.6.0 tidak boleh mengembalikan paket yang menggunakan fitur Semantic 2.0.0 yang tidak kompatibel dengan Semantic Versioning 1.0.0.
Perbedaan terpenting antara kedua versi adalah label pra-rilis, dan string metadata.
Spesifikasi Semantic Versioning 1.0.0 menyediakan [0-9A-Za-z-]
sebagai contoh string Regex untuk satu-satunya karakter yang diizinkan sebagai bagian dari label pra-rilis, dan tidak mendukung string metadata.
Spesifikasi Semantic Versioning 2.0.0 memungkinkan pengidentifikasi pra-rilis dipisahkan oleh .
karakter (dan melarang pengidentifikasi numerik memiliki nol awal), dan juga memungkinkan metadata build ditambahkan mengikuti +
.
Dalam sumber daya metadata paket (RegistrationsBaseUrl
), versi sumber daya di bawah 3.6.0 hanya boleh mengembalikan paket yang sesuai dengan . NET atau System.Version
Semantic Versioning 1.0.0.
Ini berarti paket yang versinya hanya sesuai dengan Semantic Versioning 2.0.0 tidak terlihat oleh versi klien ini.
Demikian pula, layanan kueri pencarian (SearchQueryService
) dan layanan lengkapi otomatis (SearchAutocompleteService
) menambahkan &semVerLevel={version}
parameter kueri.
Ketika semVerLevel
hilang, asumsikan nilai 1.0.0
.
Seperti sumber daya metadata paket, paket yang versinya hanya kompatibel dengan Semantic Versioning 2.0.0 tidak boleh dikembalikan ketika semVerLevel
nilainya di bawah 2.0.0.
Ikon paket, lisensi, dan file readme dapat (dan disarankan untuk) disematkan dalam paket.
File-file ini memerlukan titik akhir URL, baik diekstrak dan diletakkan di server file statis, atau URL yang secara dinamis mengekstrak file dari .nupkg
sesuai permintaan, sehingga dapat dilihat tanpa mengunduh seluruh nupkg
.
Jika repositori paket Anda menyediakan detail paket penjelajahan dan tampilan paket, Anda dapat menggunakan URL untuk menampilkan konten yang disematkan kepada pelanggan di situs web Anda.
Terakhir, sumber daya metadata paket dan sumber daya pencarian harus berisi URL yang dihosting di iconUrl
properti , , licenseUrl
dan/atau readmeUrl
respons JSON.
Paket (.nupkg
file) tidak boleh dimodifikasi, karena fitur klien (file kunci dan paket yang ditandatangani) akan mendeteksi modifikasi karena paket telah dirusak.
Perhatikan bahwa lisensi bisa berupa ekspresi SPDX, atau file yang disematkan (tetapi tidak keduanya).
Paket yang menggunakan ekspresi lisensi, ketika diwakili dalam hasil metadata pencarian dan paket, dapat mengatur licenseUrl
ke ekspresi lisensi, URL yang dikodekan, dan ditambahkan ke akhir https://licenses.nuget.org/.
Contohnya, https://licenses.nuget.org/Apache-2.0.
Tim server NuGet.org memiliki dokumentasi tambahan tentang licenses.nuget.org.
Sumber Daya Metadata Paket dapat berisi informasi penghentian dan kerentanan. Ini memungkinkan pelanggan menelusuri paket di Antarmuka Pengguna Manajer Paket Visual Studio, atau yang setara di ID Lain, untuk diberi tahu tentang masalah keamanan atau pemeliharaan penting.
Jika repositori paket Anda adalah paket "up-sourcing" dari repositori lain, untuk mencerminkan paket di umpan Anda sendiri, sebaiknya periksa sumber asli secara berkala jika ada data penghentian atau kerentanan, dan cerminkan metadata tersebut di repositori Anda sendiri.
Jika repositori paket Anda ditingkatkan sumbernya dari nuget.org secara khusus, dengan menjaga status terakhir kali Anda memeriksa ("kursor"), Anda dapat menggunakan Catalog
sumber daya untuk memeriksa secara efisien apakah ada pembaruan paket untuk paket yang Anda cerminkan, tanpa harus mengunduh sejumlah besar file JSON metadata paket dari umpan upstream.
Ada panduan tentang menggunakan sumber daya katalog dengan kode sampel yang dapat membantu Anda memulai.
Untuk menyediakan pemindaian kerentanan berkinerja tinggi selama pemulihan paket, NuGet mengunduh daftar lengkap kerentanan yang diketahui dari VulnerabilityInfo
sumber daya.
Nuget.org menyediakan data kerentanan untuk semua saran yang ditinjau GitHub dari database GitHub Advisories, yang mencakup paket yang tidak dihosting di nuget.org.
Jika repositori paket Anda menghosting paket pihak pertama, dan Anda ingin memberikan informasi kerentanan kepada pelanggan menggunakan umpan Anda sendiri, tetapi belum memiliki kerentanan paket yang diungkapkan, Anda harus memberikan indeks kerentanan dengan satu atau beberapa halaman kerentanan yang kontennya adalah array JSON kosong ([]
).
Jika repositori paket Anda dimaksudkan untuk digunakan oleh aplikasi sebagai repositori default (bukan nuget.org), Anda dapat menggunakan data kerentanan nuget.org.
Salah satu opsinya adalah menggunakan URL indeks kerentanan nuget.org dalam indeks layanan Anda.
Opsi lain adalah memeriksa indeks nuget.org VulnerabilityInfo
secara berkala, dan mengunduh halaman yang diubah untuk dicerminkan secara lokal.
.NET CLI memungkinkan pencarian paket alat .NET dengan dotnet tool search
perintah .
Ini diimplementasikan dengan menambahkan &packageTypes={value}
parameter kueri ke sumber daya kueri pencarian, yang membaca nilai dari bidang file <packageTypes>
paket.nuspec
.
Seperti yang dijelaskan dalam gambaran umum NUGet API, URL awal untuk semua komunikasi server NuGet adalah indeks layanan.
Dokumen ini berisi URL untuk semua sumber daya lain yang akan dikueri klien NuGet.
Pada NuGet 6.7 (Visual Studio & MSBuild 17.7, dan .NET SDK 7.0.400), NuGet menggunakan . HttpClientHandler.PreAuthenticate
NET , yang hanya menghindari permintaan HTTP anonim ketika URL berikutnya berada di direktori virtual yang sama, atau subdirektori, dari URL yang sebelumnya telah diautentikasi.
Ini akan secara dramatis mengurangi jumlah permintaan HTTP yang tidak diautentikasi yang dikirim ke server, dan oleh karena itu akan mengurangi beban kerja server Anda.
Berikut adalah beberapa contoh:
URL | Akankah PreAuthenticate? |
---|---|
https://pkgs.contoso.com/nuget/v3/feed/index.json | N/A, ini adalah indeks layanan. |
https://pkgs.contoso.com/nuget/v3/search | Tidak, tidak dalam sub-direktori yang sama dengan indeks layanan. |
https://search.pkgs.contoso.com/nuget/v3/feed/ | Tidak, tidak pada nama host yang sama dengan indeks layanan. |
https://pkgs.contoso.com/nuget/v3/feed/search | Ya, dalam direktori yang sama dengan indeks layanan. |
https://pkgs.contoso.com/nuget/v3/registration/ | Tidak, tidak dalam subdirektori indeks layanan. |
https://pkgs.contoso.com/nuget/v3/feed/registration/ | Ya, dalam subdirektori indeks layanan. |
https://pkgs.contoso.com/nuget/v3/{guid}/registration/ | Lihat di bawah ini |
Dalam contoh terakhir, server mungkin memiliki nama kanonis (dalam contoh ini guid), dan memiliki satu atau beberapa alias.
Jika permintaan indeks layanan diautentikasi pada URL non-kanonis (nama "ramah", dalam contoh feed
kami ), maka tidak, permintaan apa pun ke sumber daya di bawah URL kanonis tidak akan cocok HttpClientHandler
dengan aturan untuk PreAuthenticate
.
Namun, jika URL non-kanonis adalah pengalihan HTTP ke URL kanonis, https://pkgs.contoso.com/nuget/v3/{guid}/index.jsonmaka URL ini akan digunakan dalam HttpClientHandler
cache kredensial .
Dalam hal ini, setiap permintaan ke indeks layanan akan memiliki latensi tambahan, karena pengalihan.
Meskipun API V3 NuGet dirancang untuk bekerja pada server file statis, sumber daya pencarian adalah pengecualian yang selalu memerlukan layanan web dinamis untuk memproses permintaan.
Jika Anda ingin menghosting pencarian, atau memang sumber daya NUGet API lainnya, di server yang berbeda, untuk mendapatkan manfaat dari HttpClientHandler
, PreAuthenticate
Anda harus menggunakan proksi terbalik untuk memastikan semua URL yang dihadapi pelanggan dalam indeks layanan memenuhi aturan "sama atau subdirektori".