Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
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, bacalah tentang versi protokol.
Chronology
Untuk membantu penulis repositori NuGet yang ada mengikuti perkembangan fitur terbaru NuGet, berikut adalah kronologi fitur relevan yang disebutkan dalam sisa dokumen.
| Year | Feature |
|---|---|
| 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 untuk Semantic Versioning 2.0.0 | |
| 2018 | Lisensi yang disematkan |
| 2019 | Ikon yang disematkan |
Penghentian dukungan paket dalam RegistrationBaseUrl (sumber daya metadata paket) |
|
| 2020 |
Informasi kerentanan paket dalam RegistrationsBaseUrl (sumber daya metadata paket) |
Menambahkan parameter kueri packageTypes ke permintaan SearchQueryService |
|
| 2021 | Readme yang disematkan |
| 2023 |
Praotentikasi permintaan terautentikasi VulnerabilityInfo Sumber daya |
| 2025 | Aktifkan unduhan README yang disematkan |
Bidang Pemilik
Pertimbangkan dua bidang file manifes paket (.nuspec), yaitu <authors> 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 tahun 2013, jadi <owners> bidang dianggap tidak digunakan lagi dalam .nuspec berkas.
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.
verified bidang respons pencarian
Antarmuka Pengguna Manajer Paket Visual Studio menunjukkan tanda centang biru di samping paket dalam hasil layanan pencarian, ketika 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.* diverifikasi hanya 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.
Dukungan Semantic Versioning 2.0.0
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 tertentu . (dan melarang pengidentifikasi numerik untuk memiliki nol di awal), dan juga memungkinkan penambahan metadata pembangunan setelah +.
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.
File yang disematkan
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 penjelajahan paket dan melihat detail paket, Anda dapat menggunakan URL untuk menyajikan konten tertanam kepada pelanggan di situs web Anda.
Terakhir, sumber daya metadata paket dan sumber daya pencarian harus berisi URL yang dihosting dalam properti iconUrl, licenseUrl, dan/atau readmeUrl dari 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 pencarian dan metadata paket, dapat mengatur licenseUrl sebagai ekspresi lisensi, yang dikodekan dalam URL, dan menambahkannya 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.
Data kerentanan dan pembatalan yang diketahui
Sumber Daya Metadata Paket (RegistrationsBaseUrl)
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 IDE lain, untuk diberi tahu tentang masalah keamanan atau pemeliharaan penting.
Jika repositori paket Anda mengambil paket dari repositori lain untuk merefleksikan paket di umpan Anda sendiri, kami sarankan Anda memeriksa sumber asli secara berkala untuk melihat apakah ada data penghentian atau kerentanan, dan merefleksikan metadata tersebut di repositori Anda sendiri. Jika repositori paket Anda mengambil sumber dari nuget.org secara khusus, dengan menjaga status pemeriksaan terakhir Anda ("kursor"), Anda dapat menggunakan sumber daya tersebut untuk efisien memeriksa apakah ada pembaruan untuk paket yang Anda cerminkan, tanpa perlu 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.
Database Kerentanan yang Diketahui (VulnerabilityInfo)
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 ([]).
Menggunakan ulang data kerentanan dari nuget.org
NuGet tidak mengharuskan sumber daya dalam indeks layanan, atau indeks kerentanan, harus berada di server yang sama dengan indeks layanan itu sendiri. Namun, ada beberapa alasan mengapa beberapa perusahaan memilih untuk memblokir nuget.org di firewall, atau memiliki umpan lokal pada jaringan yang terputus. Untuk menghindari masalah konektivitas, sebaiknya sajikan data kerentanan dari aplikasi web Anda sendiri, sehingga klien NuGet hanya membuat koneksi HTTP ke host tempat umpan diinstal.
✔️ Lakukan cache atau proksi halaman kerentanan di aplikasi web Anda sendiri
❌ JANGAN mengiklankan api.nuget.org dalam indeks layanan atau indeks kerentanan Anda tanpa konfigurasi untuk menonaktifkannya.
packageTypes kueri pencarian
.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 file .nuspec bidang <packageTypes> paket.
Struktur URL untuk umpan terautentikasi
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.
Sejak NuGet 6.7 (Visual Studio & MSBuild 17.7, dan .NET SDK 7.0.400), NuGet menggunakan
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 yang 'mudah dibaca', dalam contoh kami feed), maka tidak, permintaan apa pun ke sumber daya di bawah URL kanonis tidak akan memenuhi aturan HttpClientHandler untuk PreAuthenticate.
Namun, jika URL non-kanonis adalah pengalihan HTTP ke URL kanonis, https://pkgs.contoso.com/nuget/v3/{guid}/index.json, maka URL ini akan digunakan dalam cache kredensial HttpClientHandler.
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 sumber daya API NuGet lainnya, di server yang berbeda untuk mendapatkan manfaat dari HttpClientHandler dan PreAuthenticate, Anda harus menggunakan proksi terbalik untuk memastikan semua URL yang dihadapi pelanggan dalam indeks layanan memenuhi aturan "sama atau subdirektori".
Aktifkan unduhan README yang disematkan
Sumber daya baru didokumenkan untuk membuat URL yang dapat digunakan untuk mengunduh README untuk paket tertentu. Ini akan memungkinkan klien, seperti antarmuka pengguna Manajemen Paket di VS, untuk menampilkan README yang disematkan untuk paket yang sebelumnya belum diinstal oleh pengguna. Klien akan membuat URL ini dan mencoba mengunduh README, menggunakan respons terhadap permintaan untuk menentukan apakah README tersedia. Ini berarti server harus mengharapkan beberapa permintaan ke titik akhir yang dibangun saat pengguna menavigasi PM UI.